# Architecture Decision Record (ADR)

# Architecture Decision Record — ADR-{{NUMBER}}

> **Project:** {{PROJECT_NAME}}
> **ADR Number:** ADR-{{NUMBER}}
> **Title:** {{SHORT_DECISION_TITLE}}
> **Version:** 1.0
> **Date:** {{DATE}}
> **Author:** {{AUTHOR}}
> **Status:** Proposed | Accepted | Deprecated | Superseded by [ADR-{{NEW_NUMBER}}](./ADR-{{NEW_NUMBER}}.md)
> **Reviewers:** {{REVIEWERS}}

## Document History
| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 0.1     | {{DATE}} | {{AUTHOR}} | Initial draft |
| 1.0     | {{DATE}} | {{AUTHOR}} | Accepted after review |

---

## ADR Numbering Scheme

<!-- GUIDANCE: ADRs are numbered sequentially per project: ADR-001, ADR-002, etc. Never reuse numbers. Use leading zeros for up to 3 digits. Store in: docs/architecture/decisions/ or ARCHITECTURE/adr/. -->

**Convention:** `ADR-{NNN}-{short-slug}.md` — e.g., `ADR-001-use-postgresql.md`

---

## 1. Context

<!-- GUIDANCE: Describe the situation that forces this decision. Include: technical constraints, business requirements, team context, existing decisions that constrain options. Be factual, not prescriptive. Do NOT state the decision here — only the forces that require a decision. -->

### 1.1 Situation

{{DESCRIBE_THE_SITUATION_REQUIRING_A_DECISION}}

### 1.2 Forces & Constraints

**Technical forces:**
- {{TECHNICAL_FORCE_1}} — e.g., "We need horizontal scalability for 100K+ concurrent users"
- {{TECHNICAL_FORCE_2}} — e.g., "The team has strong expertise in TypeScript but limited Go experience"
- {{TECHNICAL_FORCE_3}}

**Business forces:**
- {{BUSINESS_FORCE_1}} — e.g., "Time-to-market is critical; MVP must launch in 3 months"
- {{BUSINESS_FORCE_2}} — e.g., "Budget limits managed services to under $2K/month"

**Compliance & regulatory:**
- {{COMPLIANCE_FORCE}} — e.g., "GDPR requires data residency in EEA"

**Existing decisions that constrain this:**
- [ADR-{{PARENT_NUMBER}}](./ADR-{{PARENT_NUMBER}}.md): {{PARENT_DECISION}} — constrains us to {{CONSTRAINT}}
- Existing infrastructure: {{EXISTING_SYSTEM}}

### 1.3 Problem Statement

> **We need to decide:** {{CLEAR_ONE_SENTENCE_PROBLEM_STATEMENT}}

---

## 2. Decision

<!-- GUIDANCE: State the decision clearly and unambiguously. One or two sentences. Start with "We will..." -->

**We will:** {{CLEAR_DECISION_STATEMENT}}

**Rationale (summary):** {{ONE_PARAGRAPH_WHY}}

---

## 3. Alternatives Considered

<!-- GUIDANCE: Minimum 2 alternatives (not including the chosen option). Be intellectually honest — include the genuine pros and cons of each. A weak alternatives section undermines trust in the decision. -->

### Option A: {{OPTION_A_NAME}} ← Selected

<!-- GUIDANCE: Include the chosen option in the alternatives for comparison. -->

**Description:** {{OPTION_A_DESCRIPTION}}

**Pros:**
- {{PRO_1}}: {{EXPLANATION}}
- {{PRO_2}}: {{EXPLANATION}}
- {{PRO_3}}: {{EXPLANATION}}

**Cons:**
- {{CON_1}}: {{EXPLANATION}}
- {{CON_2}}: {{EXPLANATION}}

**Cost/Effort:** {{ESTIMATE}} — {{NOTES}}

**Risk:** {{RISK_LEVEL}} — {{RISK_DESCRIPTION}}

---

### Option B: {{OPTION_B_NAME}}

**Description:** {{OPTION_B_DESCRIPTION}}

**Pros:**
- {{PRO_1}}: {{EXPLANATION}}
- {{PRO_2}}: {{EXPLANATION}}

**Cons:**
- {{CON_1}}: {{EXPLANATION}}
- {{CON_2}}: {{EXPLANATION}}
- {{CON_3}}: {{EXPLANATION}}

**Cost/Effort:** {{ESTIMATE}} — {{NOTES}}

**Risk:** {{RISK_LEVEL}} — {{RISK_DESCRIPTION}}

**Why not chosen:** {{SPECIFIC_REASON_REJECTED}}

---

### Option C: {{OPTION_C_NAME}}

**Description:** {{OPTION_C_DESCRIPTION}}

**Pros:**
- {{PRO_1}}: {{EXPLANATION}}

**Cons:**
- {{CON_1}}: {{EXPLANATION}}
- {{CON_2}}: {{EXPLANATION}}

**Cost/Effort:** {{ESTIMATE}}

**Why not chosen:** {{SPECIFIC_REASON_REJECTED}}

---

### Comparison Matrix

| Criterion | Weight | Option A (Selected) | Option B | Option C |
|-----------|--------|--------------------|---------|---------|
| {{CRITERION_1}} | {{1-5}} | {{SCORE}} | {{SCORE}} | {{SCORE}} |
| {{CRITERION_2}} | {{1-5}} | {{SCORE}} | {{SCORE}} | {{SCORE}} |
| {{CRITERION_3}} | {{1-5}} | {{SCORE}} | {{SCORE}} | {{SCORE}} |
| Team expertise | 4 | {{SCORE}} | {{SCORE}} | {{SCORE}} |
| Operational complexity | 3 | {{SCORE}} | {{SCORE}} | {{SCORE}} |
| Cost (3-year TCO) | 4 | {{SCORE}} | {{SCORE}} | {{SCORE}} |
| Community/support | 2 | {{SCORE}} | {{SCORE}} | {{SCORE}} |
| **Weighted Total** | | **{{TOTAL_A}}** | **{{TOTAL_B}}** | **{{TOTAL_C}}** |

*Score: 1 (poor) to 5 (excellent)*

---

## 4. Consequences

<!-- GUIDANCE: Honest assessment of what this decision entails — positive, negative, and neutral. Consider: code changes required, operational changes, team impact, future flexibility. -->

### 4.1 Positive Consequences
- {{POSITIVE_1}}: {{DETAIL}}
- {{POSITIVE_2}}: {{DETAIL}}
- {{POSITIVE_3}}: {{DETAIL}}

### 4.2 Negative Consequences
- {{NEGATIVE_1}}: {{DETAIL}} — *Mitigation: {{MITIGATION}}*
- {{NEGATIVE_2}}: {{DETAIL}} — *Mitigation: {{MITIGATION}}*

### 4.3 Neutral / Secondary Effects
- {{NEUTRAL_1}}: {{DETAIL}}
- {{NEUTRAL_2}}: {{DETAIL}}

### 4.4 Technical Debt Created
<!-- GUIDANCE: Be honest about shortcuts or limitations introduced. -->
- {{DEBT_ITEM}}: {{PLAN_TO_ADDRESS}}
- *Acceptable because:* {{REASON}}

---

## 5. Compliance Impact

<!-- GUIDANCE: Does this decision affect regulatory compliance? GDPR, HIPAA, PCI-DSS, SOC2, etc. -->

| Regulation | Impact | Notes |
|-----------|--------|-------|
| GDPR | {{NONE/LOW/MEDIUM/HIGH}} | {{DETAILS}} |
| PCI-DSS | {{NONE/LOW/MEDIUM/HIGH}} | {{DETAILS}} |
| HIPAA | {{NONE/LOW/MEDIUM/HIGH}} | {{DETAILS}} |
| SOC2 | {{NONE/LOW/MEDIUM/HIGH}} | {{DETAILS}} |

**Data residency implications:** {{NONE / DATA_MUST_STAY_IN_REGION}}

---

## 6. Performance Impact

<!-- GUIDANCE: Quantify where possible. Use measurements from benchmarks or production data from similar systems. -->

| Metric | Before | After (Expected) | Source |
|--------|--------|-----------------|--------|
| Latency (p99) | {{BEFORE}} | {{AFTER}} | {{BENCHMARK_SOURCE}} |
| Throughput | {{BEFORE}} | {{AFTER}} | {{BENCHMARK_SOURCE}} |
| Memory footprint | {{BEFORE}} | {{AFTER}} | {{BENCHMARK_SOURCE}} |
| Cost (monthly) | {{BEFORE}} | {{AFTER}} | {{ESTIMATE_SOURCE}} |

**Performance testing plan:** {{HOW_WILL_WE_VALIDATE}}

---

## 7. Migration / Implementation Notes

<!-- GUIDANCE: How do we get from current state to this decision? What needs to change? What's the rollout plan? -->

### 7.1 Migration Plan

```
Phase 1 ({{DURATION}}): {{PHASE_1_DESCRIPTION}}
  - [ ] {{TASK_1}}
  - [ ] {{TASK_2}}

Phase 2 ({{DURATION}}): {{PHASE_2_DESCRIPTION}}
  - [ ] {{TASK_3}}
  - [ ] {{TASK_4}}

Phase 3 ({{DURATION}}): {{PHASE_3_DESCRIPTION}} (if needed)
  - [ ] {{TASK_5}}
```

### 7.2 Rollback Strategy

**Can we roll back?** {{YES/NO/PARTIAL}} — {{EXPLANATION}}

If yes: {{ROLLBACK_STEPS}}

### 7.3 Feature Flags

<!-- GUIDANCE: Use feature flags for risky migrations to allow gradual rollout and instant rollback. -->

| Flag | Purpose | Default |
|------|---------|---------|
| `{{FLAG_NAME}}` | {{PURPOSE}} | `{{DEFAULT_VALUE}}` |

---

## 8. Related ADRs

<!-- GUIDANCE: Link to ADRs that influenced this decision or that this decision affects. -->

| ADR | Relationship | Notes |
|-----|-------------|-------|
| [ADR-{{N}}](./ADR-{{N}}.md) | Prerequisite | {{HOW_IT_RELATES}} |
| [ADR-{{N}}](./ADR-{{N}}.md) | Supersedes | This decision replaces {{OLD_DECISION}} |
| [ADR-{{N}}](./ADR-{{N}}.md) | Affected | This decision impacts {{HOW}} |

---

## 9. Review Date

<!-- GUIDANCE: ADRs should be reviewed if the context changes significantly. Set a review date, especially for decisions with high uncertainty. -->

**Next review:** {{REVIEW_DATE}} or when {{TRIGGER_CONDITION}}

**Review trigger conditions:**
- {{TRIGGER_1}} — e.g., "If load exceeds 500K req/day, revisit caching strategy"
- {{TRIGGER_2}} — e.g., "If vendor pricing changes by more than 50%"
- {{TRIGGER_3}} — e.g., "After 6 months in production"

**Superseded by:** — *(fill in if this ADR is later superseded)*

---

## Approval
| Role | Name | Date | Signature |
|------|------|------|-----------|
| Author | | | |
| Tech Lead | | | |
| Security (if compliance impact) | | | |
| CTO / Architect | | | |