Architecture Decision Records

The why behind the big choices. Short records live in the repo; the larger ones live in Confluence. This page is just an index — it doesn't copy the ADRs, so they can't rot out of sync.

In the repo — docs/adr/

ADR	Decision	Status
0001	Monorepo layout — composition-root config, one process.env reader per app	accepted (2026-08-06)
0002	Observability — structured origin logs, metrics, live debug	accepted (2026-08-12)

Read them directly in docs/adr/0001-monorepo-layout.md and docs/adr/0002-observability.md. The page-builder walk-through is docs/page-builder-end-to-end.md.

In Confluence

The bigger decision records and living design docs are in Confluence.

The cross-cutting overview (start here for the "why"):

• System Architecture (S0–S8) — the single source of truth for the cross-cutting decisions (stack, cacheability, tenancy, resilience, cache/purge, cost, security, deploy). This is a decision record, not a current-state guide — read it for the reasoning, and this site for what runs today.
• S2 — Multi-tenancy & Routing (deep dive) — the readable walk-through of tenant resolution, routing precedence, isolation, custom domains, and the tenant lifecycle.

The decision records:

• ADR-007 — agent tokens (short-lived, HMAC-signed, store-scoped, scope-narrowing only).
• ADR-010 — control-plane security (Clerk authN + Postgres memberships authZ, deny-by-default).
• ADR-012 — the platform stack (Cloudflare edge + Hono/ECS origin + Postgres, multi-tenant shared host).
• ADR-013 — the page builder (JSON-AST, render-at-edge PoC, keep the custom editor).
• ADR-017 — data-platform boundaries (what stays out of the OLTP database).
• Schema ERD — the canonical Postgres schema.

These predate the code

The S0–S8 page and its deep dives were written in Sprint 0, before/while building. Some items are marked Open, put off, or proven by POC — and a few things were decided differently once built (e.g. the render path stayed at the origin; the "may move to the edge" note is a PoC, not the deployed path). Trust this site + the code for current behaviour, and Confluence for the decisions behind it.

Keep decisions where they're durable

When a decision changes, update its ADR in the same PR as the code. A doc that lags the code is worse than no doc.