Decision records (ADR)
Decision records (ADR)
Section titled “Decision records (ADR)”A short numbered record per decision that is hard to reverse: a dependency, a public contract, a piece of the architecture. Each record states the context, the decision and its consequences — good and bad — so that whoever meets the code later (a teammate, your future self, an AI agent) can tell a deliberate choice from an oversight before changing it.
Format
Section titled “Format”- Status —
Accepted, orSuperseded by ADR-XXXX. - Date — when the decision shipped (its release).
- Context — the forces that led to the decision.
- Decision — what was decided, stated in the present tense.
- Consequences — what gets better, and what gets worse.
Approved records are never rewritten. If the team changes its mind, a new record is written and the old one is marked superseded by it — like a new log entry that does not cross out the previous one. Nothing here is an implementation detail: the Architecture page and the API Reference cover those.
Records
Section titled “Records”| # | Decision | Status | Date |
|---|---|---|---|
| ADR-0001 | Safe Results instead of exceptions | Accepted | 2026-09-26 |
| ADR-0002 | Singleton facades exposed as use* functions |
Accepted | 2026-10-04 |
| ADR-0003 | Framework adapters only on subpath exports | Accepted | 2026-09-20 |
| ADR-0004 | Hexagonal layout with a pure core | Accepted | 2026-09-03 |
| ADR-0005 | Docs as code: generated reference, four page kinds | Accepted | 2026-09-26 |
| ADR-0006 | Retire the Telegram and WhatsApp adapters | Accepted (amends ADR-0003) | 2026-10-18 |
| ADR-0007 | WordPress roles are declared in the app, not created over REST | Accepted | 2026-10-18 |
| ADR-0008 | Access is three orthogonal axes, not one role ladder | Accepted | 2026-10-18 |
| ADR-0009 | The @/ alias is used in src/, rewritten by tsc-alias |
Accepted | 2026-10-18 |
| ADR-0010 | The use* prefix is kept; on* is reserved for Observer callbacks |
Accepted | 2026-10-19 |
| ADR-0011 | No static business methods — Singleton plus DI instead | Accepted | 2026-10-19 |
| ADR-0012 | The currency rate adapter lives in src/infrastructure/ |
Accepted | 2026-10-19 |
| ADR-0013 | Money is rounded with Intl.NumberFormat, not Math.round |
Accepted | 2026-10-19 |
| ADR-0014 | Frankfurter/ECB reference rates behind the provider port | Accepted | 2026-10-19 |
| ADR-0015 | Cross-rates divide through a pivot currency | Accepted | 2026-10-19 |
| ADR-0016 | Universal runtime APIs in the core | Accepted (amends ADR-0004) | 2026-10-25 |
Adding a record
Section titled “Adding a record”Copy the shape of an existing record, number it sequentially and open it in the same pull request as the change it describes. The contributing contract lists what counts as a decision: a new runtime dependency, a public contract change, an architecture move.