Shipyard

Shipyard is the open-source, framework-agnostic application platform developed alongside The Inverted Stack: Local-First Nodes in a SaaS World.

The book argues that the SaaS paradigm needs inverting — that local-first nodes, kernel/plugin separation, and hosted-node-as-SaaS deployments produce better software than the centralized cloud-tenancy model most teams default to. Shipyard puts that architecture into running code: a suite of building blocks for scaffolding, prototyping, and shipping real applications where every part of a business runs on one set of records, on a computer its owner controls — with interchangeable UI and domain components across Blazor, React, and beyond.

Harborline is the reference application built on Shipyard — a local-first business app that exercises the platform end-to-end (apps/carrier on top of apps/local-node-host).

What's in the box

• Framework-agnostic UI: One set of component contracts (ui-core) surfaced across React (@shipyard/ui-react) and Blazor (ui-adapters-blazor) via thin adapters.
• Local-first kernel: Kernel/plugin split, sync, attestation, signing — the trust model from the book, in real .NET code (apps/local-node-host).
• Domain blocks: Forms, workflows, rules, scheduling, assets, accounting, comms — full feature surfaces, not just UI widgets (the packages/blocks-* family).
• Migration-friendly: Stable abstractions and compatibility kits so you can swap underlying vendors with minimal surface impact.
• A working reference app: Harborline (apps/carrier) composes these blocks into a real local-first application, dogfooded on the platform's own kernel.

Source documents

• The book — github.com/Harborline-Software/the-inverted-stack — motivation, history, alternatives considered, the case for inverting.
• The technical specification — _shared/product/local-node-architecture-paper.md — derived from the book; the precise definitions every directory in this repo traces back to.

High-level architecture

Shipyard is organized into layers:

• Foundation Design tokens, utilities, and core contracts shared across all packages.

• UI Components Framework-agnostic component contracts (ui-core) plus per-framework adapters (React, Blazor).

• Compatibility Kits Optional packages that mirror the public API shape of popular commercial libraries, so you can prototype against Shipyard and later switch vendors with minimal changes.

• Blocks & Modules Higher-level building blocks — dynamic forms, workflows, rules engines, schedulers, asset registries, accounting, and more — that encapsulate patterns and cross-cutting logic.

• Solution Accelerators Opinionated, ready-to-extend solutions composed from Shipyard blocks. Harborline (apps/carrier) is the flagship reference application, demonstrating the local-first deployment shape end-to-end.

Repository layout

shipyard/
  packages/
    foundation-*/          # tokens, utilities, core contracts, auth, governance
    ui-core/               # framework-agnostic component contracts
    ui-react/              # @shipyard/ui-react — React component library
    ui-adapters-blazor/    # Blazor adapter implementation
    compat-*/              # optional, API-compatible surfaces where permissible
    blocks-*/              # domain blocks: forms, calendar, assets, financial-*, comms, docs, …
    kernel-*/              # local-first kernel primitives
  apps/
    carrier/               # Harborline — the reference local-first business app (React/Tauri)
    local-node-host/       # the local-first node host (kernel + sync + signing)
    hull/                  # invoke/sandbox host surface
    docs/                  # documentation site + live examples
    kitchen-sink/          # Blazor component playground
    kitchen-sink-react/    # @shipyard/ui-react component playground
  accelerators/            # reference solution accelerators
  tooling/                 # scaffolding, KB, i18n glossary, update-feed, and other dev tooling
  _shared/                 # design, engineering, product, and research references
  docs/adrs/               # architecture decision records
  icm/                     # ICM pipeline — workflow artifacts only, not code

The platform is built incrementally; package APIs, names, and structure continue to evolve.

Try the Kitchen Sink

The fastest way to see Shipyard components in action.

React components (@shipyard/ui-react):

cd apps/kitchen-sink-react
npm install
npm run dev

Open http://localhost:6100 and pick a family from the sidebar. Every ui-react component has an anchor-linkable demo section with live variant rows. See apps/kitchen-sink-react/README.md for build/typecheck commands.

Blazor components:

dotnet run --project apps/kitchen-sink

Open https://localhost:5301 and browse the sidebar. Every Blazor component has a demo page; the theme picker (top-right) switches providers and dark/light mode.

Documentation

• Published site: https://harborline-software.github.io/shipyard/ (published via .github/workflows/docs.yml on merges to main)
• Edit docs: see apps/docs/README.md for local preview + edit workflow

Example use cases

• Quickly prototype a line-of-business app using open-source Shipyard components, then selectively replace specific grids or charts with commercial equivalents.
• Standardize UX across multiple applications by building against Shipyard contracts instead of directly against vendor-specific libraries.
• Compose domain features like "asset management" or "project planning" from reusable Shipyard blocks and extend them with your own business rules.

Status

Shipyard is in active development. A substantial package set and the ICM pipeline are in place, and Harborline (apps/carrier) exercises the platform end-to-end as the reference application.

APIs, package names, and structure are subject to change until a 1.0 release is tagged.

Contributing

Contributions, ideas, and discussion are very welcome.

• Open an issue to propose new building blocks, adapters, or solution accelerators.
• Share real-world scenarios where a compatibility or abstraction layer would simplify your stack.
• Help refine the API design so Shipyard is pleasant to use from multiple frameworks.

Development process

Shipyard uses an ICM (Integrated Change Management) pipeline to stage work from intake through release. All changes flow through deliberate phases with review gates, keeping design decisions traceable. See /icm/CONTEXT.md for an overview, and CLAUDE.md for AI-assisted development guidance including the tool boundaries between ICM and OpenWolf.

License

Shipyard is released under the MIT License — Copyright © 2026 Harborline-Software.