# Architecture Decision Record

> One decision per record. One page. Written when the decision is made, not reconstructed
> afterwards — the reasoning is the point, and reasoning evaporates within about two weeks.
>
> File as `docs/adr/NNNN-short-title.md` in the repository the decision affects.

**ADR:** _____  **Title:** _______________
**Date:** _______  **Status:** proposed / accepted / superseded by ADR ____
**Deciders:** _______________

## Context

What is true that forces a decision now? Facts and constraints only — no options yet.

- Current state: _______________
- What changed, or what is about to: _______________
- Constraints that are real (deadline, budget, skills present, systems that cannot move):
  _______________
- Constraints that are assumed but unverified: _______________

> Separating those last two lines is the highest-value part of this document. Half of all
> architecture is built around constraints nobody has checked in three years.

## Decision

**We will:** _______________

State it in the active voice, in one or two sentences, specific enough that someone could
disagree with it.

## Options considered

| Option | Why it was attractive | Why it was rejected |
|---|---|---|
| | | |
| | | |
| **Do nothing / defer** | | |

🔴 The "do nothing" row is mandatory. If it was never genuinely considered, this is a
justification, not a decision record.

## Consequences accepted

**What gets better:** _______________

**What gets worse:** _______________

**What we can no longer do easily:** _______________

**Who has to change how they work:** _______________

A decision with no negative consequences has not been thought about. Write the cost down while
you are still willing to admit it.

## Cost and reversibility

| | |
|---|---|
| One-way or two-way door? | one-way / two-way |
| Estimated effort to implement | |
| Estimated effort to reverse in 12 months | |
| Ongoing run cost | |

If it is a two-way door, decide quickly and move on. If it is one-way, the rest of this page
deserves an hour of somebody's full attention.

## What would make us revisit this

| Trigger | Who watches it |
|---|---|
| Scale beyond ___ | |
| Cost above ___ | |
| Latency above ___ | |
| A dependency changing | |
| Date to review | |

An ADR without revisit conditions becomes permanent by accident. Most bad architecture is a good
decision that outlived its context.

## Compliance and data

| | |
|---|---|
| Personal data involved | yes / no |
| Data residency implications | |
| New third party introduced | |
| Security review needed | yes / no — date |
| Accessibility impact | |

## References

- Related ADRs: _______________
- Prototype / spike results: _______________
- Measurements this was based on: _______________

> If the "measurements" line is empty, mark the decision as reversible and set a review date.
> A decision made on intuition is not necessarily wrong, but it should be labelled as such so a
> future reader knows how much weight to give it.

## Sign-off

| | Name | Date |
|---|---|---|
| Author | | |
| Reviewer | | |
| Accepted by | | |