docs/decisions/README.md

Architecture Decision Records

This directory records the why behind Qx-SmartLedger's architecture — the context that normally gets lost over a project's life. If you're new here (human or a fresh Claude Code session), read this index first, then open the ADRs relevant to what you're about to touch.

Each ADR uses the Michael Nygard format: Context · Decision · Consequences · Rejected alternatives.

How to use

• Adding a decision: copy the format of an existing ADR into the next number (000N-short-title.md), set Status: Accepted (or Proposed), and add a row below.
• Numbering: sequential, never reused or renumbered.
• Superseding: don't delete the old ADR — set its status to Superseded by [000M](000M-title.md) and link forward. History stays intact.
• When: any non-trivial architectural/design decision, a tricky debugging finding worth remembering, or an approach ruled out after real investigation — write it down proactively, don't wait to be asked.

Index

#	Title	Status
0001	Record architecture decisions	Accepted
0002	Route all WhatsApp/Meta egress through a Render relay	Accepted
0003	AI-primary intent routing with a guarded deterministic fast-path	Accepted
0004	Deliver generated media (PDFs, audio) via Firebase Storage links	Accepted
0005	Hard-stop sales that exceed tracked inventory	Superseded by 0008
0006	Capture a multimodal distillation dataset from live traffic	Accepted
0007	Unified cash + receivables/payables money model	Accepted
0008	Service detection via an AI is_service flag + learned registry	Accepted
0009	Preserve raw English input; parse CRUD-by-id before translation	Accepted
0010	Capture the stock-in cost price once, then remember it	Superseded by 0011
0011	Two-price model: cost from the purchase, a prompt for the selling price	Accepted
0012	Language-agnostic customer-name recovery from the raw message	Accepted
0013	Keep an anonymised snapshot when a user resets/nukes their account	Accepted
0014	Classify intent on the original text; keep item/person names in the user's words	Accepted
0015	Dashboards + API read the v2 ledger schema; add a Model-Health layer	Accepted
0016	Gemini-native unified audio understanding; AssemblyAI fallback without language detection	Accepted
0017	Price/cost provenance rules and deterministic money answers	Accepted
0018	AI-primary command routing and a canonical item-price registry	Accepted
0019	Comprehensive admin analytics with AI reports (informal-market science)	Accepted