Oxagen Architecture Atlas

System context

• The web app and the MCP server each bootstrap the kernel and call invoke() in their own process. Only the CLI, wrapped agents and HTTP clients reach it through apps/api.
• Counts on this page are read from the tree at build time (package manifests, the storage manifest, the capability manifest, route and function sources). If a number here disagrees with the code, the atlas is stale: run pnpm docs:architecture.

Dependency graph

• Most depended-on: config (48), oxagen (24), tenancy (17), database (16), recorder (16), telemetry (15), billing (12), crypto (11).
• Deprecated and tool workspaces are listed in the table but left out of the drawing.

One org-scoped API request

• A Bearer header wins outright: the session cookie is never consulted, and the key's org scope, and its workspace when it is a workspace key, is copied onto the request. The org slug middleware returns early, and the org slug in the URL is not checked against the key. A workspace key also skips the workspace slug. An organisation key resolves it inside its own org.
• The browser app and the MCP server do not pass through this chain. apps/app and apps/mcp each bootstrap the kernel and call invoke() in their own process.
• The three GUCs are set with set_config(name, value, true), which is transaction-local. No policy reads app.rls_bypass any more (ADR-5879), so no setting turns RLS off. app.org_wide is 'off' here and 'on' only in withOrgDb, or in a savepoint of an open tenant transaction through withTransactionOrgWideRead. Either unlocks the SELECT-only tenant_org_wide_read policies.
• withSystemDb is the deliberate RLS bypass: it runs SET LOCAL ROLE oxagen_system, a NOLOGIN role every RLS table admits through its system_access policy, and always runs on the shared plane. The app role may switch to oxagen_system but does not inherit it, so a tenant transaction never matches that policy. withOrgPlaneSystemDb is the plane-aware variant for system writes to tenant-plane tables. A call made with no active tenant scope increments an in-process counter, written to a debug log line as db.query.unscoped.

Tenant data planes (ADR-042)

• The decrypted plane config never leaves the resolver except inside a binding handed to a store client; it is never logged, serialised into an error, or returned by a read capability.
• The resolver reads org.data_planes through withSystemDb on the shared plane, so withSystemDb itself cannot be plane-aware without a cycle. withOrgPlaneSystemDb resolves the plane first, for system writes to tenant-plane tables.

How a surface reaches a handler

• 684 of 693 contracts bind a handler in @oxagen/handlers; the rest register from @oxagen/agent/register or run inline.
• The registry lives on globalThis under a symbol so a bundler's double evaluation cannot register twice; a duplicate with a different signature keeps the first registration, with a warning outside production, instead of throwing.

Gate order inside invoke()

• The surface check runs only when the caller passes opts.surface. The kernel enters the tenant scope when the contract is scoped or both tenant ids are uuids. A machine key whose scope does not cover the capability is refused before checkIAM. A pending_approval result also creates an access_requests row. A nested invoke skips the billing gate but not the budget gate. Stella's calls and the assistant's own contracts skip the budget and decision-rules gates (ADR-235). The decision-rules gate may reserve a settlement, which the audit step settles and the catch block releases. The replay-input check runs only on the approval-resume path.
• The billing, budget and usage slots are empty until bootstrapBillingRuntime() fills them, once per process. A surface that does not bootstrap runs those gates open. apps/api, apps/mcp and apps/app also bootstrap IAM, decision rules and entitlement at startup.
• IAM enforcement is always on: bootstrapIAMRuntime registers the check with enforcement set to true, and no setting turns it off (ADR-6171). An IAM throw fails closed. An agent-run invocation also fails closed when its IAM check returns no persisted authorization decision.
• Every failure exits before the accrual step. Lookup, binding, platform-only, surface, input and replay-input refusals throw before the tenant scope opens. IAM, billing, budget, entitlement, rules and handler failures leave through the catch block, which releases any reserved settlement. An invalid output throws after that. This is how ADR-052's rule that denials are free is enforced by structure, not by policy.

checkIAM decision order