Skip to content

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.

  • Status — Accepted, or Superseded 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.

# 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

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.