163 lines
3.5 KiB
Markdown
163 lines
3.5 KiB
Markdown
# 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
|