Architecture atlas

The Architecture Atlas is the internal engineering map of the platform. The build generates it from the tree. Package manifests, the storage manifest (ADR-031), the capability manifest, route and function sources, the environment registry, CI workflows, and ADRs feed the figures directly. The hand-described mechanism flows cite the files and symbols they depict, and the build verifies each citation.

What it covers

• Overview. System context and the live counts (apps, packages, contracts, routes, tables, functions, variables, workflows, and decisions).
• Workspace. The dependency graph with implied edges removed, and every workspace package.
• Request path. One org-scoped request from identity to row-level security, tenant data planes (ADR-042), auth tiers, and every API route.
• Capability kernel. How a surface reaches a handler, the gate order inside invoke(), checkIAM's decision order, domains × surfaces, and the full catalog.
• The governed turn. The in-app agent loop on stella-serve.
• Evidence ledger and wrapped agents. The ledger's run, attempt, event, and seal records, their status machines, and the ingest path a wrapped agent's host reports on.
• Metering and billing. Governed action to credit debit (ADR-052), and the turn admission gate.
• Knowledge graph. The ingestion pipeline (ADR-012), Neo4j labels, and vector indexes.
• Datastores. The four stores, domains across stores, Postgres schemas, an entity-relationship diagram per schema with RLS classes, ClickHouse tables replayed from migrations, and Blob kinds.
• Background jobs. The Inngest event → function → event graph.
• CLI and MCP surfaces, Deployment (production topology, Caddy routing, CI job graph, workflows, and the local stack), Configuration contract (every variable × service), and Decisions (ADR index).

Regenerating

pnpm docs:architecture           # write apps/docs/public/architecture/ (gitignored)
pnpm docs:architecture --check   # refs resolve + deterministic output (runs in the gate)

The output is not committed. The docs app runs the generator as its prebuild and predev step, so the published atlas describes the tree it shipped with, and no pull request has to regenerate it. The generator lives in tools/scripts/gen-architecture-docs.ts. Its collectors, SVG layout engine, and curated flows live under tools/scripts/lib/archdocs/. To add a mechanism diagram, add a flow to flows.ts with the source references it depends on. The build refuses to run when a cited file or symbol is gone.