Architecture Decision Records (ADRs)

This directory records the project’s closest-call architectural decisions so that "solo for now, legible for later" is real — a future maintainer (or contributor, or AI agent) inherits not just the choices but their rationale and the triggers that would reverse them (AR-21).

Decisions are first recorded inline in ../../_bmad-output/planning-artifacts/architecture.md §"Architecture Decision Records (closest calls)" as the architecture is designed; they are promoted to standalone files here as the project grows. This set is _seeded in Story 0.7 and completed in Story 6.4 — until then, some decisions below live only in architecture.md (marked accordingly).

Numbering convention

  • ADRs are numbered ADR-NNN, 3-digit zero-padded (matching the ADR-001… numbering already used in architecture.md).

  • The number is a chronological record-ID — importance-independent. A reader finds a decision by its title or this index, never by its number, so a foundational decision may carry a high number simply because it was recorded later. (The full-Rust-stack decision is ADR-005, not because it is minor — it is the most foundational call in the project — but because ADR-001…​004 were assigned their numbers first, in architecture.md.)

  • Numbers are never reused. A reversed decision is marked Superseded by ADR-NNN, not deleted — the history is the point.

  • New ADRs are authored from template.md. The two mandatory fields — Reversal-Trigger and Why-this-matters-to-a-future-maintainer — are non-negotiable on every ADR (AR-21).

Index

ADR Decision Status Where

ADR-001

SSR/hydration over CSR-only

Accepted

architecture.md §ADR — file migrated in Story 6.4

ADR-002

Headless components + own CSS over a packaged lib

Accepted

architecture.md §ADR — file migrated in Story 6.4

ADR-003

redb over SQLite

Accepted

architecture.md §ADR — file migrated in Story 6.4

ADR-004

Monolith over engine/web split (with in-binary runtime isolation)

Accepted

architecture.md §ADR — file migrated in Story 6.4

ADR-005

Rust full-stack

Accepted

this directory

ADR-006

Security ceiling (SD-card secrets-at-rest)

Accepted

this directory

Related

  • template.md — the ADR skeleton (copy to start a new one).

  • risk-seam-map.md — the pre-mortem-risk → mitigating-seam map (which seam parachutes which failure mode). Seeded here, kept current in 6.4.

  • CONTRIBUTING.md — the zero-hardware contributor on-ramp.

  • architecture.md — the full design; "closest-call changes get a new ADR with its Reversal-Trigger" (the pattern-evolution rule).