Architecture Decision Records¶
Each ADR captures a single architecturally significant decision: the context, the options considered, the choice, and its consequences. ADRs are append-only — once accepted, they're not edited; they're superseded by a later ADR if the decision changes.
ADRs covering the underlying platform (VPS, DB, auth runtime, schema isolation) live in the keystone repo — see its docs/adr/.
Index¶
| # | Title | Status | Owner | Date |
|---|---|---|---|---|
| 0001 | Application stack and multi-tenancy approach | Accepted | Theo | 2026-04-27 |
| 0002 | Receipt PDF design (A4, total in top-left quadrant) | Accepted | Theo | 2026-04-27 |
| 0003 | Multi-tenant data isolation enforcement | Superseded by 0004 | Theo | 2026-04-27 |
| 0004 | Client identity (Person/ClientProfile split) and three-grant sharing model | Accepted | Theo | 2026-05-02 |
| 0004a | R-FADP-4 — Consent-by-proxy provenance on Person (amends ADR-0004) |
Proposed | Theo | 2026-05-06 |
| 0005 | In-app notification model | Accepted | Theo | 2026-05-02 |
| 0006 | JWT/session contract with gotrue | Accepted | Theo | 2026-05-02 |
| 0007 | Order lifecycle state machine | Accepted | Theo | 2026-05-02 |
| 0008 | Receipt numbering under PgBouncer | Accepted | Theo | 2026-05-02 |
| 0009 | Observability and secrets boundary with keystone/Atlas | Proposed | Theo | 2026-05-04 |
| 0010 | Test architecture (real Postgres, fixtures, categories, CI) | Proposed | Theo | 2026-05-02 |
| 0011 | Admin role boundaries (bypass scopes + audit routing + V3 role-switcher slot) | Proposed | Theo | 2026-05-06 |
How decisions land here¶
- A maintainer with sign-off on the area drafts the ADR in MADR-lite format (template below).
- The ADR is opened as a merge request; status starts as
Proposed. - Once merged on
main, status changes toAccepted. - To change a previously-accepted decision: write a new ADR that lists the prior one as superseded (don't edit the old file).
Format (MADR-lite)¶
# ADR-NNNN: <decision title>
- **Status:** Proposed | Accepted | Superseded by ADR-XXXX
- **Date:** YYYY-MM-DD
- **Decider(s):** <names>
## Context
<why this decision matters now>
## Options
- **Option A** — pros / cons
- **Option B** — pros / cons
## Decision
<chosen option + rationale>
## Consequences
<what follows from this — both the good and the costs we accept>