Skip to content

Architecture Decision Records

ADRs capture point-in-time decisions about mocapi's architecture. They are immutable in spirit: a decision that no longer holds gets a new ADR with status "Supersedes ADR-NNNN", and the old ADR's status flips to "Superseded by ADR-MMMM".

Provenance

ADRs 0001–0018 were reconstructed retroactively on 2026-05-07 from the project's now-retired numbered-spec corpus and from git history. The Date: field on each ADR records when the decision landed in the codebase (the commit that introduced the central artifact — class, sealed type, module, or annotation — that the decision manifests as), not when the ADR document itself was authored. Where a decision evolved across multiple commits, the date is the introduction of the canonical artifact. ADRs added from this point on should be authored at decision time and dated accordingly.

Status legend

  • Accepted — currently in effect, reflected in the code and the design docs.
  • Proposed — under discussion, not yet implemented.
  • Superseded — replaced by a later ADR. The replacement is linked.
  • Deprecated — no longer in effect but not replaced (rare).

How to add an ADR

  1. Copy _template.md to NNNN-short-title.md using the next free number.
  2. Fill in Status / Context / Decision / Consequences.
  3. Update the relevant ../design/*.md in the same commit so the living docs stay synchronized.
  4. Add the ADR to the index below.

Index