# 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.

---
**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`.