Skip to main content

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}}
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
Back to top