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, the CI inventory of secrets and variables, 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 coversCopy Anchor Link

• 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 API 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 with each contract's handler binding.
• The governed turn. The in-app assistant's turn: ask_assistant, the credit gate, the turn's recorded session, and the loop on stella-serve that hands every completion and tool call back to Oxagen.
• Run evidence. The ingest path a wrapped agent's host reports on, its four enforcement tiers, and how a session is locked and graded on tacho.sessions, the one run table (ADR-5969). Locked means any change after that point shows.
• Metering and billing. Agent actions counted against the monthly allowance, wallet ledger rows for credit purchases and debits, and the charge made before each model call on Oxagen's key.
• Knowledge graph. The ingestion pipeline (ADR-012), Neo4j labels, and vector indexes.
• Datastores. The four stores (Postgres and ClickHouse run in ClickHouse Cloud, ADR-295), 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), Secrets and variables (where each value is kept and how to refresh it), and Decisions (ADR index).

RegeneratingCopy Anchor Link

pnpm docs:architecture           # write apps/docs/public/architecture/ (gitignored)
pnpm docs:architecture --check   # refs resolve + deterministic output (part of pnpm 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 docs build refuses to run when a cited file or symbol is gone, so a broken citation stops the docs deploy. A cited symbol that still exists but no longer does what the flow says passes that check, so review the prose in flows.ts when you change the code it describes.