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}} Reviewers: {{REVIEWERS}}

Document History

Version	Date	Author	Changes
0.1	{{DATE}}	{{AUTHOR}}	Initial draft
1.0	{{DATE}}	{{AUTHOR}}	Accepted after review

---

ADR Numbering Scheme

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

---

1. Context

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}}: {{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

We will: {{CLEAR_DECISION_STATEMENT}}

Rationale (summary): {{ONE_PARAGRAPH_WHY}}

---

3. Alternatives Considered

Option A: {{OPTION_A_NAME}} ← Selected

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

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

• {{DEBT_ITEM}}: {{PLAN_TO_ADDRESS}}
• Acceptable because: {{REASON}}

---

5. Compliance Impact

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

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

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

Flag	Purpose	Default
{{FLAG_NAME}}	{{PURPOSE}}	{{DEFAULT_VALUE}}

---

8. Related ADRs

ADR	Relationship	Notes
ADR-{{N}}	Prerequisite	{{HOW_IT_RELATES}}
ADR-{{N}}	Supersedes	This decision replaces {{OLD_DECISION}}
ADR-{{N}}	Affected	This decision impacts {{HOW}}

---

9. Review Date

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