45 lines
1.2 KiB
Markdown
45 lines
1.2 KiB
Markdown
# Architecture Decision Records (ADR)
|
||
|
||
ADRs are short, versioned documents that capture **why** we made a major architectural/product decision.
|
||
They prevent “tribal knowledge” and make reversals/migrations explicit.
|
||
|
||
---
|
||
**Last Updated:** 2025-12-12
|
||
**Phase:** Phase 0 (Planning)
|
||
**Status:** Draft — adopt in Phase 1
|
||
**Owner:** Tech Leads
|
||
---
|
||
|
||
## When to write an ADR
|
||
Create an ADR whenever a decision is:
|
||
- hard to reverse later,
|
||
- affects multiple modules/teams,
|
||
- has meaningful trade‑offs,
|
||
- changes default recommendations in `/docs`.
|
||
|
||
Examples:
|
||
- modular monolith vs microservices,
|
||
- Postgres + `pgvector` vs external vector DB,
|
||
- billing model (subscription vs usage),
|
||
- RAG vs non‑RAG architecture,
|
||
- auth provider choice.
|
||
|
||
## Where ADRs live
|
||
One file per decision in `docs/adr/`.
|
||
|
||
Naming convention:
|
||
- `0001-short-title.md`
|
||
- `0002-another-decision.md`
|
||
|
||
Status lifecycle:
|
||
`proposed` → `accepted` → (`superseded` | `rejected`)
|
||
|
||
## How ADRs relate to `RECOMMENDATIONS.md`
|
||
- `RECOMMENDATIONS.md` is the **current snapshot** of locked decisions and constraints.
|
||
- ADRs are the **history and rationale** behind those decisions.
|
||
Link every ADR from `RECOMMENDATIONS.md` once accepted.
|
||
|
||
## Template
|
||
Start from `docs/adr/0000-template.md`.
|
||
|