The complete system map
A spatial map that separates client surfaces, transport, transactional state, hot delivery, side effects, provider routing, and external execution.
What this chapter resolves
- Locate every major package at its runtime boundary.
- See which edges carry commands, events, provider-native protocol, or filesystem effects.
For a selected environment, authoritative repository and provider execution occurs behind that environment’s server boundary. A client can supervise several such environments, while Electron and mobile also own device-local storage, navigation, notifications, preview, update, and operating-system integrations.
Text equivalent
Clients use authenticated HTTP for snapshots and query pages and WebSocket RPC for commands and live subscriptions. A serialized in-memory queue invokes a persistence- and provider-I/O-free decision layer that still reads the clock and creates UUIDs. That decision happens before events, SQL projections, and accepted receipts commit together. A hot PubSub then feeds best-effort reactors and live subscribers. Provider work routes through ProviderService, an instance registry, and one provider adapter before reaching the five native harnesses.
docs/internals/overview.md:5–28 ↗apps/server/src/orchestration/Layers/OrchestrationEngine.ts:83–96 ↗apps/server/src/orchestration/decider.ts:18–173 ↗apps/server/src/orchestration/Layers/OrchestrationEngine.ts:197–259 ↗apps/server/src/ws.ts:1394–1521 ↗apps/server/src/orchestration/Layers/ProviderCommandReactor.ts:1060–1174 ↗apps/server/src/provider/Layers/ProviderService.ts:356–409 ↗Two return paths, one write path
Zoom with the controls, +/−, or Ctrl/⌘ + trackpad scroll. Enable Pan to drag, use two-finger scrolling, or use the arrow keys. 0 fits the diagram; Esc leaves Pan or expanded view.
Text equivalent
A client sends a typed command by WebSocket. The in-memory queue calls the decision layer before the SQL boundary, then atomically commits events, SQL projections, and an accepted receipt. After commit, a hot event bus independently feeds live subscribers and provider reactors. A reactor routes through ProviderService and an adapter to a harness. Canonical harness events return through runtime ingestion and re-enter the command queue. Separately, authenticated HTTP reads authoritative SQLite snapshots for initial and reconnect synchronization.
apps/server/src/orchestration/decider.ts:18–173 ↗apps/server/src/orchestration/Layers/OrchestrationEngine.ts:197–259 ↗apps/server/src/orchestration/Layers/ProviderCommandReactor.ts:1405–1409 ↗packages/client-runtime/src/state/threads.ts:534–645 ↗apps/server/src/ws.ts:1394–1521 ↗packages/contracts/src/providerRuntime.ts:1139–1193 ↗apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts:1490–1874 ↗The downward path is imperative: “start this turn,” “accept this approval,” “revert this checkpoint.” The upward path is descriptive: assistant deltas, activities, plans, usage, session state, and changed-file summaries. The adapter is where each harness’s vocabulary becomes the canonical provider-runtime vocabulary.
Three UI families, four execution clients, five delivery shapes
apps/web serves three roles: the browser UI copied into the npm CLI, the hosted
product UI, and the Electron renderer. Electron and React Native add very different
native systems around shared connection/state semantics. The marketing Astro site
is the fifth delivery shape, but it is a publication surface—not an execution
client.
| Capability | Local web | Hosted web | Electron | iOS | Android |
|---|---|---|---|---|---|
| Environment server | CLI-owned | remote | managed local/WSL | remote | remote |
| Terminal renderer | Ghostty WASM | Ghostty WASM | Ghostty WASM | native Ghostty | native Ghostty VT |
| Offline new-task intent | — | — | — | durable outbox | durable outbox |
| Environment provisioning | primary/pair | pair/relay | primary, WSL, SSH | pair/relay | pair/relay |
| Distinctive native edge | local browser | cloud identity | preview, updates, OS IPC | APNs, Live Activities, share | share, widgets |