Architecture decision records#
These records implement GOV-001: architecture and compatibility decisions are versioned with their rationale, alternatives and migration implications. Each ADR corresponds to one row of the decision register in docs/plan.md §37.1 and records what the code actually does today, including where it falls short of the register.
| ADR | Decision | Status |
|---|---|---|
| 0001 | Product form: modular monolith with worker processes | Accepted |
| 0002 | Implementation language and libraries: Go | Accepted |
| 0003 | First-party license: Apache-2.0 | Accepted |
| 0004 | Durable store: PostgreSQL | Accepted |
| 0005 | Cache and broker: none required; transactional outbox in PostgreSQL | Accepted |
| 0006 | Identity boundaries: realm = issuer and user namespace; organization = business tenant | Accepted |
| 0007 | Stable account key: immutable local IDs; external identity keyed by issuer and subject | Accepted |
| 0008 | Interactive protocol: authorization code with PKCE only | Accepted |
| 0009 | Ordinary access tokens: short-lived asymmetric JWTs with one audience | Accepted |
| 0010 | High-risk and support tokens: opaque, validated online | Accepted |
| 0011 | Refresh model: opaque, rotated, client-bound families | Accepted |
| 0012 | Organization context: one organization per business token | Accepted |
| 0013 | Authorization: scoped RBAC with delegation ceilings and a decision API | Accepted |
| 0014 | Impersonation: explicit, short, actor-preserving support grants | Accepted |
| 0015 | Keys: root keys, HKDF purpose keys, AES-256-GCM, wrapped signing keys | Accepted |
| 0016 | Email and SMS: replaceable operator-configured adapters | Accepted |
| 0017 | Browser integration: external login UI and headless transactions | Accepted |
| 0018 | Federation and enterprise protocols: ship each only when complete | Accepted |
| 0019 | HA topology: one authoritative write region | Accepted |
| 0020 | Compliance posture: evidence and controls, no certification claims | Accepted |
| 0021 | Custom logic: out of process only, no embedded code execution (EXT-013; not a §37.1 register row) | Accepted |
| 0022 | Security-event exchange: an audit-log adapter out, explicit action policies in (AUD-016, ADV-007; not a §37.1 register row) | Accepted |
Format#
Each record has: Status, Context, Decision, Alternatives considered, Consequences, Migration implications and Related requirement IDs (from docs/plan.md).
Changing a decision#
A decision is replaced, not edited: add a new ADR with the next number, set the
old record's status to Superseded by NNNN, and update the threat model, tests and
operations documents in the same pull request. docs/plan.md §37.1 requires that a
substituted decision preserve the security invariant it protects (for example,
choosing another database does not remove atomic one-time proof consumption).