Architecture Decision

Architecture Decision

Write an ADR when the choice is not obvious, is expensive to reverse, or will be questioned later. Do not write one for a choice with an obvious default; that is paperwork, and it dilutes the record.

Decide whether it needs one

Process

1. State the decision as a question. "Which queue?" is a question. "Use Kafka" is an answer looking for justification, and it will find one.

2. Establish the forces. What is actually in tension: throughput against operational cost, consistency against latency, today's simplicity against tomorrow's migration. If you cannot name a tension, there is no decision here, only a default.

3. Constrain by what is true here. Team size and operational capacity, existing infrastructure, real data volume, latency and durability requirements, cost, compliance. Most technology debates dissolve once the actual numbers are on the table.

4. List real options, including "do nothing" and "use what we already run". Options nobody would choose do not belong; a straw man makes the record worthless.

5. Compare on the axes that distinguish them. Not a feature matrix. Two options that score the same on nine axes and differ on the tenth are decided by the tenth.

6. Decide. Then write the rejected option's strongest argument fairly, because that is the argument someone will make again later.

7. Write the consequences, including what becomes hard.

8. Write the revisit condition as an observable trigger, not a date.

Format

# ADR <n>: <the decision>

- **Status:** proposed | accepted | superseded by ADR <n>
- **Date:** <YYYY-MM-DD>
- **Deciders:** <who>

## Context
<the forces; what is true here that makes this a decision rather than a default>

## Constraints
<the numbers and limits that actually narrow the field>

## Options
### A. <name>
<what it is; the trade-off that distinguishes it>
### B. <name>

## Decision
<what will be done, stated as a decision>

## Rejected
<the losing option and its strongest argument>

## Consequences
- Becomes easy:
- Becomes hard:
- Becomes expensive to reverse:

## Revisit when
<observable condition>

Reviewing someone else's design

Ask, in order:

1. What breaks first as this grows? At what number?
2. What happens when each dependency is slow, then unavailable?
3. Where is the state, and who owns it? Two owners is the bug.
4. What is the migration path from what exists today?
5. What is the simplest thing that would work, and what does this buy over it?
6. How is it observed, and how is it rolled back?

Question five is the one that most often changes the design. Ask it even when the design is good.

Verification

• The decision is stated as a decision, not a preference or a comparison.
• Constraints include real numbers, not adjectives.
• The rejected option's best argument is written down fairly.
• Consequences include what becomes hard, not only what becomes easy.
• The revisit condition is observable.

Red flags