Skip to content

Architecture Decision Records

Canonical home for every ADR. The PRD copies in prd.md §19 and prd-v2.1.md §C.8 / §B.15 carry "Canonical: see [docs/adrs/ADR-XXX.md]" pointers and remain for narrative continuity, but edits land here only. Per the documentation discipline rules in CLAUDE.md: ADRs land as new files in docs/adrs/ — never as new headings buried in a PRD.

Status table

ID Title Status Source Touches
ADR-001 Postgres + Redis instead of GCP Pub/Sub + BigQuery Accepted prd.md §19 infra
ADR-002 LLM provider for rationale generation Accepted (silent-fallback semantics superseded by ADR-008) prd.md §19 LLM
ADR-003 LLM rationale fallback Accepted prd.md §19 LLM, decisions
ADR-004 Single-scenario MVP Accepted prd.md §19 scope
ADR-005 Widget Builder via LangGraph Clarifier Accepted prd.md §19 Clarifier, frontend
ADR-006 WidgetSpec gains a custom variant; in-browser TSX evaluation Accepted prd.md §19 Clarifier, frontend, security
ADR-007 Metric-aware Clarifier with first-class metric catalog Accepted prd.md §19 Clarifier, metrics, frontend
ADR-008 Mocks are opt-in, never silent fallback Accepted prd.md §19 LLM, ops
ADR-009 Drag-reorder dashboard layout via a single JSONB layout doc Accepted prd.md §19 dashboard, frontend
ADR-010 Icon library injection (lucide-react via sealed Icon global) Accepted prd.md §19 frontend, security
ADR-011 Two-tier Bedrock model selection (fast vs reasoning) Accepted new (2026-05-06 model probe + lessons-learned) LLM, ops
ADR-PROTO-001 Defer Kafka to architecture diagram only Accepted prd-v2.1.md §C.8 infra, scope
ADR-PROTO-002 SQL generator anchored to metrics_catalog Accepted prd-v2.1.md §C.8 sql_gen, safety
ADR-PROTO-003 SQL generator runs in FastAPI, not API Gateway + Lambda Accepted prd-v2.1.md §C.8 sql_gen, infra
ADR-PROTO-004 Data dictionary in prompt context, not vector DB Accepted prd-v2.1.md §C.8 sql_gen
ADR-PROTO-005 Hybrid in-prototype (Postgres + Databricks per metric) Accepted prd-v2.1.md §C.8 sql_gen, routing
ADR-V2-001 Hybrid Kafka + Lakehouse architecture (production target) Accepted (proposed) prd-v2.1.md §B.15 infra, production

Conventions

  • One file per ADR, four sections: Status / Context / Decision / Consequences (plus Cross-references). See _template.md.
  • ID prefix is permanent. ADR-NNN for shipped product decisions in v1, ADR-PROTO-NNN for prototype-scoped Part C decisions, ADR-V2-NNN for proposed v2 production decisions. ADR-PROTO-NNN graduates to ADR-NNN only when the prototype work is complete and the underlying decision becomes a permanent product decision.
  • Status transitions are append-only. Mark superseding (Superseded by ADR-XXX) instead of editing the original decision body.
  • Cross-references go both ways. When ADR-X supersedes ADR-Y, both files mention the relationship.

Adding a new ADR

  1. Pick the next NNN in the appropriate prefix family (ADR-011, ADR-PROTO-006, etc.).
  2. Copy _template.md → ADR-NNN.md.
  3. Fill in the four sections.
  4. Add a row to the Status table above (in this README).
  5. If superseding, update the superseded ADR's Status field with Superseded by ADR-NNN.
  6. Update CLAUDE.md reading order if the ADR is foundational.

ADRs are not added to the PRDs anymore — they live here only.