# Architecture Decision Record

Use this template for consequential architecture decisions. Keep lightweight choices lightweight; use this when the decision has meaningful blast radius, cost, risk, or switching difficulty.

## 1. Decision

**Decision ID:** ADR-___  
**Status:** Proposed / Accepted / Rejected / Superseded  
**Date:** YYYY-MM-DD  
**Decision owner:**  
**Contributors:**  
**Affected teams:**  

### Decision question

Describe the decision without embedding a preferred solution.

> How should we ... ?

## 2. Context

What problem or change created the need for this decision?

- Current state:
- Desired outcome:
- Scope:
- Out of scope:
- Deadline or timing constraint:

## 3. Hard constraints

Conditions every viable option must satisfy.

| Constraint | Why it is hard | Evidence/source |
| --- | --- | --- |
|  |  |  |

## 4. Decision forces

Prioritize only the qualities that materially affect the choice.

| Force | Priority | Why it matters |
| --- | --- | --- |
| Reliability | High / Medium / Low | |
| Security | High / Medium / Low | |
| Performance | High / Medium / Low | |
| Operability | High / Medium / Low | |
| Evolvability | High / Medium / Low | |
| Cost | High / Medium / Low | |
| Delivery speed | High / Medium / Low | |
| Skills / support | High / Medium / Low | |

Add or remove forces rather than scoring irrelevant criteria.

## 5. Viable options

Keep the option set small. Include the status quo when it is genuinely viable.

### Option A — [name]

**What it is:**  
**What becomes easier:**  
**What becomes harder:**  
**New failure modes:**  
**Operational burden:**  
**Migration impact:**  
**Reversibility:** High / Medium / Low  

### Option B — [name]

**What it is:**  
**What becomes easier:**  
**What becomes harder:**  
**New failure modes:**  
**Operational burden:**  
**Migration impact:**  
**Reversibility:** High / Medium / Low  

### Option C — [name, optional]

**What it is:**  
**What becomes easier:**  
**What becomes harder:**  
**New failure modes:**  
**Operational burden:**  
**Migration impact:**  
**Reversibility:** High / Medium / Low  

## 6. Trade-off comparison

Use 1–5 only when scoring helps the discussion. Always add a reason for meaningful scores.

| Decision force | Priority/weight | Option A | Why | Option B | Why | Option C | Why |
| --- | ---: | ---: | --- | ---: | --- | ---: | --- |
|  |  |  |  |  |  |  |  |

Do not let the numeric total override a known architectural concern. The score supports judgment; it does not replace it.

## 7. Assumptions and uncertainty

| Assumption / unknown | Confidence | Could it reverse the decision? | Evidence needed |
| --- | --- | --- | --- |
|  | High / Medium / Low | Yes / No | |

Any low-confidence assumption capable of reversing the decision should become a spike, benchmark, prototype, or explicit follow-up.

## 8. Evidence collected

- Benchmark or load test:
- Prototype / spike:
- Security review:
- Cost model:
- Operational review:
- Migration analysis:
- Other:

## 9. Decision

Write the outcome in one sentence.

> We will use **[option]** for **[scope]** because **[primary reasons]**, accepting **[important trade-off]**.

## 10. Consequences

### Positive

- 

### Negative / accepted trade-offs

- 

### Follow-up work

- [ ] 

## 11. Revisit triggers

Reconsider this decision when one or more of these conditions becomes true:

- 
- 
- 

## 12. Review date

**Next review:** YYYY-MM-DD or event-triggered  
**Supersedes:** ADR-___  
**Superseded by:** ADR-___

---

A strong ADR preserves the reasoning, not just the answer. Someone reading it six months later should understand the forces, uncertainty, trade-offs, and conditions that made the decision reasonable at the time.