Architecture
The canonical architecture document lives in docs/development/architecture.md.
It covers package dependency direction, runtime request flow, JSON-RPC dispatch, task lifecycle, storage, registry polling, outbound URL policy, auth, telemetry, release flow, and the tests and ADRs that protect those decisions.
Package Direction
types/schemas -> core runtime -> transports -> client/registry -> adapters/bridges -> CLI/appspackages/runtime owns protocol types, schemas, runtime, client primitives, storage, and outbound network policy. Auth and telemetry live in separate packages (packages/auth, packages/telemetry) and are re-exported through packages/runtime. Transports, registry, adapters, bridges, CLI, apps, docs-site, and examples consume public package APIs above that layer.
Outbound boundary
Runtime clients, registry polling, callbacks, adapters, MCP bridges, and CLI commands use one outbound policy. Redirect targets are revalidated, DNS answers are pinned to the connection, and a total deadline remains active through body or SSE consumption. Response bytes and SSE events are bounded, non-idempotent retries require an idempotency key, and query values and credential-shaped headers are redacted from telemetry.
See the canonical SSRF policy and ADR-0006.
Workspace graph
Run the graph check when package boundaries change:
node scripts/check-workspace-graph.mjs --summaryExpected summary:
Workspace graph validation passed.
Checked 8 public package import aliases across 36 forbidden dependency edges.
Dependency direction: types/schemas -> core runtime -> transports -> registry -> adapters/bridges -> CLI/apps.