3.5 KiB
3.5 KiB
Architecture Decision Record (ADR)
ADR ID: ADR-YYYY-MM-DD-XXX
Title: [Short decision title]
Status: Proposed | Accepted | Rejected | Superseded (link)
Date: YYYY-MM-DD
Owner: [Team / person]
Deciders: [Names / roles]
Scope: [Service / domain / product area]
Core
1. Context
Problem statement: What are we deciding, and why now?
Goals:
- [Goal 1]
- [Goal 2]
Non-goals:
- [Non-goal 1]
- [Non-goal 2]
Constraints (REQUIRED):
- Regulatory/compliance:
- Latency/SLO:
- Data residency:
- Platform/runtime:
- Team/operational maturity:
Assumptions (mark unvalidated):
- [Assumption] ([Inference] if not verified)
2. Decision Drivers (What Matters Most)
Rank the drivers to make tradeoffs explicit.
| Priority | Driver | Why it matters | How we measure |
|---|---|---|---|
| 1 | Reliability | SLO, error budget | |
| 2 | Security | Threat model, control coverage | |
| 3 | Cost | Unit cost, infra spend | |
| 4 | Delivery speed | Lead time, deployment frequency | |
| 5 | Operability | On-call load, MTTR |
3. Options Considered
| Option | Summary | Pros | Cons | Reversibility |
|---|---|---|---|---|
| A | Easy / Medium / Hard | |||
| B | Easy / Medium / Hard | |||
| C | Easy / Medium / Hard |
4. Decision
We choose: [Option X]
Why (1–5 bullets max):
- [Reason]
5. Architecture Impact (Implementation-Ready)
Boundaries and contracts
- Public APIs/contracts affected:
- Backward compatibility plan:
- Schema evolution strategy:
Data and consistency
- Source of truth:
- Consistency model (strong/eventual/mixed):
- Migration strategy (expand/contract, dual writes, backfill):
Failure modes and resilience
- Known failure modes:
- Timeouts/retries/backoff policy:
- Idempotency strategy:
- Degradation plan (what still works when dependencies fail):
Security
- Threat model summary:
- AuthN/AuthZ model:
- Secret and key management:
- Audit logging requirements:
Observability
- SLIs/SLOs:
- Metrics/traces/logs to add:
- Dashboards and alerts:
Cost and capacity
- Expected traffic/load:
- Cost model (drivers, main spend areas):
- Capacity plan (limits, scaling triggers):
6. Rollout, Validation, and Rollback
Rollout plan
- Feature flag / staged rollout:
- Data migration steps:
- Runbook updates:
Validation plan
- Tests to add (unit/integration/contract):
- Load/perf tests:
- Chaos/failure injection (if applicable):
Rollback plan
- How to revert code:
- How to revert data (or forward-fix):
- Timebox for rollback decision:
7. Consequences
Positive
- [Benefit]
Negative / tradeoffs
- [Cost or risk]
Follow-ups
- [Task] (owner, due date)
8. Links
- Design doc:
- Diagram(s):
- Tickets/epics:
- Related ADRs:
Optional: AI/Automation
Include only if this ADR affects AI/automation features or AI-assisted workflows.
AI Risk and Safety
- User impact of wrong output (harm model):
- Human override path and audit trail:
- Data handling (PII/PHI, retention, residency):
- Abuse cases (prompt injection, data exfiltration) [Inference]
Evaluation and Quality Gates
- Offline evaluation set definition:
- Online metrics and guardrails:
- Rollback triggers for quality regression:
Operations and Cost
- Latency/cost targets:
- Rate limiting and quotas:
- Observability for model/tool calls:
References
- ADR concept and template rationale: https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions