Skip to content

Architecture

BaseHarbor turns portable application intent into verified runtime infrastructure.

Application
    ↓
Portable Intent
    ↓
Environment + Policy
    ↓
BaseHarbor Core
    ↓
Runtime + Capability + Delivery Providers
    ↓
Verified Result

Core installation

An explicitly installed management Core consists of SQL + Secrets + Identity, currently realized by PostgreSQL, OpenBao and Keycloak. These capabilities are mandatory. The Web Console is optional and connects to one selected Core in the same installation/security boundary; same-origin HTTPS is the default topology.

Core bootstrap is independent of applications and repositories. It verifies the three capabilities and persists one authoritative installation identity. A partial failure remains observable; retry reconciles the same owned installation. Foreign or ambiguous resources fail closed instead of being adopted or replaced.

Application lifecycle provisions only requested providers and their genuine dependencies. A supported local workload without managed service requirements needs no service bundle; explicitly enabled management/Console consumers retain their own security dependencies. Development/deployment machine selection changes workspace/source defaults, not capabilities or transport security. Local development keeps required TLS and protected credentials without requiring an interactive login for ordinary local work.

The selected installation remains the authority for Core-managed credentials, service PKI and runtime-permission brokers. Application workload placement has its own runtime boundary. Execution revalidates the selected Core configuration; changed or unavailable bindings fail closed before native workload inspection or mutation. A selected remote Core is never replaced implicitly with a local one.

Management Core dependencies are mandatory while that consumer is enabled; application provider placement may be shared or application-isolated. Additional isolation can require extra provider instances. Resource evidence must identify topology/placement, stabilized idle memory, startup/convergence peak and simultaneous Core total. Unavailable measurements are not presented as measured values.

Optional companion implementations

The public BaseHarbor Console and BaseHarbor Node Connector consume Core-owned contracts; they do not introduce new authority.

CLI / JSON / MCP / protected HTTP / Console
                    ↓
             BaseHarbor Core
                    ↓
           runtime semantics
                    ↓
          Target Access boundary
                    ↓
   local/native API or optional Connector

The Console is a projection/client surface: no Console-local RBAC, deployment database, secret store or direct runtime/Connector path. The Node Connector is an optional outbound-initiated authenticated Target Access transport for remote non-Kubernetes hosts: not a control plane, not a Runtime Provider and not an autonomous agent. Kubernetes/OpenShift normally use native authenticated APIs.

A companion repository may prove its own build/tests independently. BaseHarbor support still requires pinned end-to-end evidence against the exact Core/consumer revisions.

Portable intent

The application describes what it needs, not which infrastructure product must provide it.

Examples are SQL, cache, object storage, secrets, identity, HTTP exposure and telemetry.

Repository workload sources

Repository syntax is interpreted before portable Application Intent and is not itself a provider axis.

Repository
    ↓
Workload Source Adapter
    ↓
Normalized Workload Evidence
    ↓
Inspection / adoption
    ↓
Portable Application Intent

v0.4.20 proves this boundary with Compose, repository-authored Podman Quadlet and raw Kubernetes YAML. Source-native identity remains provenance. Logical workload components are the portable identity.

Helm and Kustomize are intentionally later source adapters. Kubernetes and OpenShift remain later Runtime Providers.

See Workload sources.

Three provider axes

BaseHarbor keeps three concerns separate:

runtime != capability != delivery
  • Runtime Provider: where workloads run.
  • Capability Provider: how a logical dependency is realized.
  • Delivery Provider: how desired runtime state reaches and reconciles with the runtime.

The current local runtime path supports Docker through Docker Compose and Podman through native Quadlets generated from the same Compose-based workload/runtime model. Kubernetes and OpenShift are later runtime providers.

Environment and policy

Environment describes deployment risk and policy context. It does not identify a runtime or provider product.

Ownership and placement

Where applicable, providers use the same placement model:

application
shared
external

BaseHarbor mutates only resources it owns.

Shared placement is a first-class lifecycle boundary, not a shortcut for shared application data. The Target/provider owns the infrastructure; each application owns isolated logical resources, credentials and bindings. This makes resource-efficient topologies such as one PostgreSQL provider serving many isolated application databases possible without coupling portable application intent to provider topology.

Lifecycle

Mutating operations follow:

plan -> preflight -> apply -> verify

Reconciliation compares desired state with observed provider/runtime state and fails closed on ambiguity, ownership conflicts or unsupported requirements.

Canonical local development routing

Development browser surfaces use one target-wide HTTPS gateway. The canonical URL is the developer-facing source of truth; runtime loopback ports and provider-specific internal endpoints remain implementation detail.

https://<app>.baha.localhost
                    |
                    v
          Target dev gateway
                    |
                    v
      owned provider/runtime network
                    |
                    v
        verified internal upstream

The default domain is baha.localhost and remains configurable per Target. The normal application workload uses <app>.<domain>. Application-scoped management surfaces use <app>-<service>.<domain>; shared provider surfaces use short semantic hosts such as pgadmin.<domain>, cache.<domain>, storage.<domain>, auth.<domain>, secrets.<domain> and metrics.<domain>. Route ownership follows provider placement: application routes are removed with the application, shared routes belong to the shared provider boundary, and external providers keep their own URLs. Gateway TLS is issued from the existing BaseHarbor service-PKI boundary and HTTPS upstreams are verified against their projected trust material rather than disabling TLS verification.

Interfaces

CLI, JSON and MCP are adapters over the same semantic core. No interface may bypass policy, ownership, verification or secret safety.

For normative behavior, use Specs. For design rationale, use ADRs.

Documentation boundaries

Documentation follows the same responsibility discipline as code:

Human docs      -> explain use and concepts
Reference       -> exact public behavior
Specs           -> normative contracts
Schemas/code    -> machine-readable authority
ADRs            -> decisions and rationale
GitHub Issues   -> future planning
Releases        -> delivered history

A detailed fact should have one authoritative home. Human documentation links to deeper reference/spec material instead of duplicating it.