Design Decisions (ADRs)
Architecture Decision Records following Michael Nygard’s lightweight format.
Each ADR captures one significant decision: its context, what was decided, the considered alternatives, the trade-offs, and the consequences. ADRs are immutable once accepted — if a decision changes, write a new ADR that supersedes the old one. Never edit history; that way the rationale chain stays honest.
Index
| # | Title | Status |
|---|---|---|
| 0001 | Mail content encryption at rest with searchable blind-token FTS5 | Proposed |
Status lifecycle
- Proposed — written, open for review/feedback (issue or PR comments).
- Accepted — decision is binding; implementation may start or be in flight.
- Implemented — code is merged and shipping.
- Superseded by ADR-NNNN — a later ADR replaces this one. Both stay in the tree.
- Rejected — written but explicitly discarded. Kept for posterity so the next person doesn’t redo the same investigation.
Writing a new ADR
- Copy an existing ADR as the template.
- Number it
NNNN-kebab-case-title.md, four digits, monotonically increasing. - Open with the standard header (Status / Date / Context / Decision / Consequences / Alternatives). Keep it short — if it grows beyond ~5 pages, split it.
- Link related ADRs at the bottom.
- Add the row to the index above in the same PR.