apf_portal/docs/decisions/0001-use-adrs-to-record-architectural-decisions.md

status, date, decision-makers, tags

status	date	decision-makers	tags
accepted	2026-04-29	R&D Lead	process

Use ADRs to record architectural decisions

Context and Problem Statement

Architecturally-significant decisions will be taken throughout the lifecycle of apf-portal. Without a written, durable trace of why a decision was made — context, drivers, alternatives, trade-offs — that knowledge fades within months. New contributors re-litigate settled debates, the rationale of constraints (security, performance, accessibility) gets lost, and reversing a choice later becomes risky because nobody remembers what it was protecting against.

How do we record decisions in a way that is light enough to be sustained, durable enough to outlive contributor turnover, and integrated into the development workflow?

Decision Drivers

• Preserve the why of each decision so future contributors can understand or revisit it without re-deriving it.
• Make architecture reviewable — both at the time of a decision and during retrospective audits.
• Keep the format light enough that writing an ADR isn't a bureaucratic deterrent.
• Live alongside the code in version control, so decisions evolve with what they govern.
• Match the project's stated values: high technical bar, no bricolage, security/performance/accessibility as first-class concerns whose rationale must be traceable.

Considered Options

• No formal records — rely on commit messages and tribal knowledge.
• External wiki / Confluence — decisions live outside the codebase.
• ADRs in markdown using the MADR 4.0.0 format, in-repo.
• ADRs in another format (Nygard, Y-Statement, Cockburn).

Decision Outcome

Chosen option: ADRs in markdown using MADR 4.0.0, stored under docs/decisions/ so they sit with the rest of the project documentation.

Amended on 2026-04-30 — ADRs were originally located at decisions/ at the repository root (this ADR was written that way). On 2026-04-30 the folder was relocated to docs/decisions/ to consolidate documentation under docs/. The relocation preserves git history (git mv) and the flat-folder + globally-sequential-numbering + tags conventions are unchanged; only the path moved.

Conventions are defined in README.md:

• flat folder layout (no nested category folders);
• globally sequential 4-digit numeric prefix (NNNN-kebab-title.md);
• categorization via the tags: field in the MADR frontmatter, drawn from a canonical vocabulary;
• status lifecycle: proposed → accepted → optionally deprecated / superseded by ADR-NNNN;
• index maintained in README.md alongside any ADR change.

Consequences

• Good, because the why of every architecturally-significant decision is captured at the moment it is made and travels with the code.
• Good, because ADRs are reviewed via the normal pull-request flow — architecture becomes an explicit team conversation.
• Good, because MADR provides enough structure (drivers, options, trade-offs) without being heavy.
• Good, because flat-folder + tags scales better than nested category folders as the count grows.
• Bad, because writing an ADR adds friction; this must be balanced against the cost of not writing one.
• Bad, because the index is maintained manually until tooling or a CI check is added.

Confirmation

• Every change introducing or transitioning the status of an ADR updates the index table in README.md in the same commit.
• PR review explicitly checks for ADR proposal whenever a non-trivial decision is being introduced.
• (Future) A CI lint job validates filename pattern, frontmatter shape, and tag vocabulary.

More Information

• MADR 4.0.0 specification: https://github.com/adr/madr
• General ADR resources: https://adr.github.io/
• Template: template.md
• Tag vocabulary: see "Tag vocabulary" in README.md.