Architecture decision records

An architecture decision record (ADR) captures one significant decision: the context, the options that were considered, the choice that was made and its consequences. Together the records explain why Agoranomos is built the way it is. ADR-0001 describes which decisions are recorded and how.

Format

Records follow the MADR 4.0 format (Markdown Architectural Decision Records). Each record is one Markdown file named NNNN-title.md, with a short metadata block (status, date, decision-makers) and these sections:

• Context and Problem Statement: what needs deciding and why.
• Decision Drivers: the forces and concerns that matter.
• Considered Options: the alternatives that were weighed.
• Decision Outcome: the chosen option and its consequences, good and bad.
• More Information: evidence, links and when to revisit the decision.

Statuses

The status in the metadata block of a record is one of these words, written in lowercase.

Accepted records keep their decision

An accepted record keeps its decision. Its status, the implementation status of what it decided (such as an "In place" or "Planned" list), factual corrections and editorial fixes may be edited, and the pull request says which. These edits leave the date unchanged: it is the day the decision was made or last changed. A changed decision needs a new ADR that supersedes the old one. The old record keeps its text. Its status becomes superseded, and one line under its title points to the new record; nothing else changes. That way the history of why things changed stays readable.

A superseded record starts like this:

---
status: superseded
date: 2026-10-02
decision-makers: Andrei Gromov
---

# Title of the old decision

Superseded by [ADR-0123](0123-title-of-the-new-decision.md).

All records

Agoranomos is pre-alpha. A record states a decision, and the components it describes arrive release by release.