---
status: accepted
date: 2026-04-29
decision-makers: R&D Lead
tags: [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](https://github.com/adr/madr) 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](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](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](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](template.md)
- Tag vocabulary: see "Tag vocabulary" in [README.md](README.md).