ADR index
Architecture Decision Records
Section titled “Architecture Decision Records”This directory holds Architecture Decision Records (ADRs) — durable, version-controlled records of significant technical decisions.
| ADR | Status | Title |
|---|---|---|
| 2026-05-28-bun-workspaces | Accepted | Use Bun workspaces for the monorepo |
| 2026-05-28-documentation-system | Accepted | Documentation system and ADR process |
| 2026-05-29-personal-authentication | Proposed | Personal plane magic-link authentication |
| 2026-05-30-crypto-agility-post-quantum | Proposed | Crypto agility and post-quantum cryptography |
When to write an ADR
Section titled “When to write an ADR”Create or update an ADR when a decision affects:
- Architecture or domain boundaries
- Authentication, authorization, or tenant isolation
- Accounting, ledger, or financial data handling
- Infrastructure, deployment, or secrets management
- Compliance, privacy, retention, or audit behavior
- Offline/sync semantics or idempotency contracts
- Tooling that affects how the whole team builds or ships
Skip ADRs for routine refactors, bug fixes, or reversible implementation details with no lasting impact.
Process
Section titled “Process”- Copy _template.md to
YYYY-MM-DD-short-title.md. - Set status to Proposed and open a PR for review.
- After approval, set status to Accepted and merge.
- If superseded, set status to Superseded and link to the replacement ADR.
- Add the ADR to the index table in docs/adr/index.md.
Status values
Section titled “Status values”| Status | Meaning |
|---|---|
| Proposed | Under discussion; not yet team-approved |
| Accepted | Active decision |
| Deprecated | No longer recommended; no replacement yet |
| Superseded | Replaced by a newer ADR |