ARCHITECTURE.md

Product split

Harbor now has three distinct product layers. They should stay separate in both code and product scope.

1. Harbor Node

The true product runtime and trust boundary.

Harbor Node owns:

• local secrets and hidden config
• configured Harbor Ports
• action execution
• policy checks
• approvals
• audit logging
• local operator UI
• local SDK/API access
• local Harbor Pack import/export
• Dock import into local ports

2. Dock / Hub

Hosted but secret-free distribution layer.

Dock owns:

• safe integration catalog pages
• safe manifests for Harbor import
• Harbor Pack-like starter metadata
• install notes, help text, and discovery UX

Dock must not own:

• raw third-party credentials
• hidden config
• customer audit trails
• remote execution on behalf of a node

3. Public / cloud layer

Optional cloud services for identity, licensing, premium coordination, and later Fleet features.

Cloud owns:

• user accounts
• paid member state
• licenses and subscription state
• node enrollment metadata
• feature flags
• premium coordination metadata
• OAuth app metadata
• org/team metadata

Cloud should not become the default runtime for action execution.

Current repo reality

Implemented now:

• apps/harbor-node-api as the local runtime API
• apps/harbor-ui as the local operator surface
• apps/hub as the first hosted Dock catalog
• packages/shared and packages/sdk-ts as the current contracts/SDK layer
• packages/ui-theme as the shared visual/theme foundation

Now implemented end to end:

• apps/website
• apps/docs-site
• apps/cloud-api
• apps/cloud-admin

That means the repo is now strong across the local runtime, Dock import/discovery, public launch surfaces, member/licensing basics, and internal support tooling. The weaker areas now are billing depth, broader OAuth coverage, richer org/team controls, and later Fleet-scale coordination.

Architectural stance

Trust boundary

The local node is the trust boundary.

Harbor should continue to assume:

• connector secrets stay local whenever possible
• agents request named actions, not secret-bearing transport primitives
• cloud services are additive, not required for local trust

Product surface priority

The order of importance is:

1. Harbor Node runtime quality
2. Harbor UI operator experience
3. Dock / Hub catalog quality
4. docs and install clarity
5. cloud accounts, licensing, and premium coordination
6. OAuth support for selected ports
7. admin and team workflows

If a roadmap item weakens the first three, it is likely out of order.

Service ownership

apps/harbor-node-api

Local Harbor Node action API and stateful runtime.

apps/harbor-ui

Primary operator UI for local setup, imports, action review, approvals, and audits.

apps/hub

Hosted Dock catalog for Harbor-safe manifests and install pages, backed by a local SQLite database plus full-text search for integrations and action templates.

apps/website

Minimal public marketing and product-positioning site.

apps/docs-site

User-facing docs frontend sourced from /docs.

apps/cloud-api

Cloud account, license, member, enrollment, and later premium coordination service.

apps/cloud-admin

Internal operator/admin surface for accounts, nodes, premium features, and support workflows.

packages/shared

Cross-surface contracts and product vocabulary.

packages/sdk-ts

Local Harbor client SDK.

packages/ui-theme

Shared Harbor brand tokens, theming, and cross-surface presentation primitives.

Data ownership

Cloud

• users
• memberships and license state
• subscription metadata
• enrollment metadata
• node registry
• feature flags
• OAuth app configuration later
• org/team metadata later
• billing/provider references later

Harbor Node

• local connectors and ports
• hidden connector auth
• local policies
• approvals
• audit events
• local settings
• imported Dock metadata needed for local operation
• optional cached license state
• local OAuth tokens later when provider flows are supported

OAuth stance

OAuth support should follow the local-first rule.

Preferred model:

• cloud may help with account identity, premium gating, and provider app metadata
• Harbor Node completes or receives the provider grant in a way that keeps usable connector tokens local whenever possible
• Dock and website may explain OAuth setup, but must not become token custodians by default

Avoid building a cloud-hosted credential broker as the default Harbor model.

Member and paid-user spaces

There are two different account surfaces to build, and they should not be conflated.

Public member space

Customer-facing cloud account area for:

• sign-in
• license and plan visibility
• node enrollment visibility
• downloads and install links
• future billing/profile management

Internal admin space

Breakwater-operated tooling for:

• account support
• license overrides
• enrollment troubleshooting
• premium feature operations
• future abuse review or support diagnostics

The public member space is a product surface. The admin space is an internal operations surface.

Recommended interaction flow

1. User discovers Harbor through the website or docs.
2. User installs Harbor Node locally.
3. User opens Harbor UI on LAN.
4. User imports a Dock integration or creates a local port.
5. User configures hidden auth locally.
6. Agent or script calls Harbor Node.
7. Harbor Node applies policy and approvals.
8. Harbor Node records audit events.
9. User optionally signs into cloud/member space for license, enrollment, or premium features.
10. Premium metadata may sync selectively later without moving the core trust boundary.

Sequencing guidance

Near-term

• finish Harbor Node and Harbor UI product loops
• improve Dock / Hub authoring and import quality
• ship public website and docs frontend

Next

• ship cloud account/member basics and licensing
• add the first selected OAuth flows
• add internal admin basics

Later

• Harbor Fleet
• team/org controls
• policy sync
• centralized audit aggregation
• advanced Premium Integrations

Storage choices

Harbor Node

Prefer SQLite for the local product.

Cloud

Prefer Postgres for persistent cloud state. Use Redis only where it clearly helps:

• sessions
• queues
• rate limiting
• temporary enrollment state

Ports

See docs/PORTS_AND_SERVICES.md.

Planning references

Use these together:

• docs/MVP_SCOPE.md
• docs/MONETIZATION.md
• docs/ROADMAP.md
• docs/DELIVERY_PLAN.md