Pilot Plan

Pilot Architecture

Pilot Architecture

  • Status: Active
  • Last Updated: 2026-02-17
  • Scope: Monorepo-wide, long-term target architecture

Visual Overview

Service Topology

Request Flow

Package Dependencies

Upstream Lineage

Purpose

This document defines the long-term architecture for the Pilot monorepo. It is the primary architecture source of truth for all execution plans in @plan/plans/.

Governance rules:

  • All plans MUST align with this architecture.
  • If a plan differs, review the plan against this document first.
  • If divergence is valid, update this architecture first, then proceed with the plan.

Architecture Principles

  • Keep ownership boundaries explicit:
    • @packages/* are reusable logic packages.
    • @services/* are deployable runtime surfaces.
  • Define contracts before migration and implementation.
  • Keep gateway as the control-plane ingress for Chamber runtime traffic.
  • Keep runtime-specific behavior behind adapters (compute/sandbox).
  • Preserve upstream lineage mapping for canonical packages.
  • Avoid silent architecture drift: mismatches require architecture review.

Plan Governance

  • @plan/ARCHITECTURE.md is normative.
  • Plans are execution artifacts, not architecture authorities.
  • Every Plan.md should include an "Architecture Reference" section pointing to this file.
  • Required alignment checks for new/updated plans:
    • ownership model alignment,
    • contract/routing alignment,
    • upstream lineage and sync alignment,
    • decommission and rollback alignment.

System Topology (Long-Term)

Control Plane

  • @services/gateway
    • Auth/session validation
    • Workspace-to-runtime resolution
    • Chamber reverse proxy
    • Correlation/error normalization

Runtime Plane

  • @services/runtime (NEW - replaces compute + sandbox)

    • Unified runtime orchestrator + TLS proxy + instance image
    • Orchestrates runtime instances via Pulumi Automation API
    • Wildcard TLS termination via Caddy + Let's Encrypt DNS-01
    • Instance image runs OpenCode + backend with LocalAdapter

  • @services/compute (DEPRECATED - migrating to runtime)

    • Runtime execution target for compute workloads
    • Mounts shared backend package via compute adapter

  • @services/sandbox (DEPRECATED - migrating to runtime)

    • Runtime execution target for sandbox workloads
    • Mounts shared backend package via sandbox adapter

App Plane

  • @services/app
    • Main browser application host
    • Integrates frontend packages
    • Does not own runtime backend implementation

Canonical Package Model

@repo/chamber-ui (@packages/chamber-ui)

Canonical lineage:

  • Upstream source lineage: /Users/bianpratama/Code/ai/openchamber/packages/ui
  • Canonical upstream repository: https://github.com/btriapitsyn/openchamber

Responsibilities:

  • Reusable UI/runtime client/state layers from openchamber-ui lineage.
  • Primary upstream-sync target for openchamber-ui-derived frontend logic.

Must not own:

  • Service deployment wiring
  • Runtime backend handlers
  • Gateway policy logic

@repo/frontend (@packages/frontend)

Renamed from: @repo/chamber-fe

Canonical lineage:

  • Upstream source lineage: frontend part of /Users/bianpratama/Code/ai/openchamber/packages/web
  • Canonical upstream repository: https://github.com/btriapitsyn/openchamber

Responsibilities:

  • Frontend contracts (RuntimeAPIs interface)
  • RuntimeAPIs adapter implementations
  • Gateway API client
  • React hooks and components for app integration
  • createRuntimeAPIs(workspaceSlug) bridge for chamber-ui

Must not own:

  • Backend route handlers
  • Gateway auth/session policy
  • UI components (owned by chamber-ui)

@repo/backend (@packages/backend)

Renamed from: @repo/chamber-be

Canonical lineage:

  • Upstream source lineage: backend part of /Users/bianpratama/Code/ai/openchamber/packages/web
  • Canonical upstream repository: https://github.com/btriapitsyn/openchamber

Responsibilities:

  • Backend contracts (RuntimeAdapter interface)
  • Shared Hono app factory and route registration
  • Adapter implementations (LocalAdapter, MockAdapter)
  • Native routes (settings, sessions, github, push)

Must not own:

  • Gateway global auth/session policy
  • Service-specific environment binding wiring
  • Frontend/UI concerns

Upstream Lineage Mapping

  • /Users/bianpratama/Code/ai/openchamber/packages/ui -> canonical target: @repo/chamber-ui (@packages/chamber-ui)
  • /Users/bianpratama/Code/ai/openchamber/packages/web frontend surfaces -> canonical target: @repo/frontend (@packages/frontend)
  • /Users/bianpratama/Code/ai/openchamber/packages/web backend surfaces -> canonical target: @repo/backend (@packages/backend)

Notes:

  • @refs/* is not a canonical upstream or ownership source and is planned for full removal.
  • Canonical packages are production ownership surfaces.

Runtime Architecture

Components

  1. Orchestrator (Pulumi Automation API)

    • Provisions runtime instances on-demand
    • Manages instance lifecycle (start, stop, health)
    • Provider-agnostic (supports Fly.io, future: CF Containers, VPS)

  2. TLS Proxy (Caddy)

    • Wildcard TLS termination: *.runtime.pilot.prata.ma
    • Let's Encrypt DNS-01 challenge via Cloudflare
    • Routes requests to correct runtime instance

  3. Instance Image

    • Runs OpenCode CLI + backend with LocalAdapter
    • Identical image across all providers
    • Exposes ports: 4096 (OpenCode), 3000 (backend)

Adapter Model

interface RuntimeAdapter {
  identity: RuntimeIdentity
  capabilities(): Promise<RuntimeCapabilities>
  health(): Promise<RuntimeHealth>
  proxy(request: Request, targetPath: string): Promise<Response>
}

interface RuntimeIdentity {
  runtimeId: string
  runtimeLabel: string
  platform: 'compute' | 'sandbox' | 'runtime'
}

Adapter Implementations:

  • LocalAdapter - Proxies to local OpenCode instance (production)
  • MockAdapter - Returns mock responses (testing/development)

Backend Route Strategy

Proxy Routes (forward to OpenCode):

  • /api/terminal/*, /api/fs/*, /api/git/*, /api/session/*
  • /api/event, /api/global/event (SSE)

Native Routes (handled by backend):

  • /api/config/settings - Settings persistence
  • /api/github/* - GitHub OAuth/API
  • /api/push/* - Web push (VAPID)
  • /api/sessions/* - Session status tracking

Integration Contracts

FE -> Gateway

  • Frontend APIs are workspace-scoped through gateway:
    • /api/chamber/workspaces/:slug/*
  • Frontend must not call runtime domains directly.

Gateway -> Runtime

  • Gateway resolves runtime and forwards chamber traffic.
  • Gateway centralizes trust/correlation/error normalization contracts.
  • Runtime services execute behavior through @repo/backend adapter boundaries.

Capability Negotiation

  • Capabilities are explicit (fs, git, terminal, opencode).
  • Frontend must adapt UX based on capability response.
  • Unsupported features must use stable machine-readable errors.

Endpoint Tiering Strategy

  • Tier-1: terminal, fs, core git, session-activity, config/settings, health
  • Tier-2: github/push/skills/quota/tts/voice and ancillary flows

Policy:

  • Tier-1 parity gates runtime migration and decommission actions.
  • Tier-2 parity proceeds incrementally after Tier-1 stability.

Observability and Error Contract

  • Correlation header: x-pilot-request-id across FE -> gateway -> runtime.
  • Stable machine error codes are required for routing and operations.
  • Rollback controls must be explicit and testable in dev.

Networking and Deployment Ownership

  • Source of truth: NETWORK.yml
  • Any service/domain/port ownership change must update NETWORK.yml in the same change.
  • Local host ports follow repo policy (14xxx, no host 4096).

Import and Ownership Boundaries

  • Services may import packages.
  • Packages must not import services.
  • Shared contracts/types should live in package surfaces, not duplicated in services.

Decommission Policy

A legacy surface may be removed only when all are true:

  • no active deploy/runtime path depends on it,
  • docs/scripts/network metadata are updated,
  • replacement path is validated in local/dev,
  • rollback path is documented and rehearsed.

Architecture Change Process

When a plan differs from architecture:

  1. Flag mismatch explicitly.
  2. Decide whether architecture or plan should change.
  3. If architecture changes:
    • update this file first,
    • record rationale and impact,
    • re-baseline affected plans.
  4. Continue implementation only after alignment.

Current Direction (2026-02-16)

  • Active services: @services/app, @services/gateway, @services/runtime (new)
  • Deprecated services: @services/compute, @services/sandbox (migrating to runtime)
  • Decommissioned services: @services/oc, @services/web
  • Canonical package direction:
    • @repo/chamber-ui (@packages/chamber-ui) for openchamber-ui lineage
    • @repo/frontend (@packages/frontend, renamed from chamber-fe) for openchamber-web frontend lineage
    • @repo/backend (@packages/backend, renamed from chamber-be) for openchamber-web backend lineage

Execution Plans

  • Backend Consolidation (@plan/plans/2026-02-16 - 5 - Backend Consolidation/)

    • Package rename: chamber-be -> backend
    • Adapter implementations (LocalAdapter, MockAdapter)
    • Native routes (settings, sessions, github, push)
    • Runtime service creation

  • Frontend Integration (@plan/plans/2026-02-16 - 6 - Frontend Integration/)

    • Package rename: chamber-fe -> frontend
    • RuntimeAPIs contract and adapters
    • createRuntimeAPIs bridge
    • Direct chamber-ui mount in app

Quickstart Guide

Next Page