---
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 `adastra-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 in `decisions/` at the repository root.

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).