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