references/architecture-patterns.md

# RAG architecture decision patterns
## Common pipeline
1. Ingest allowlisted data sources, parse and normalize without losing sections/tables/provenance.
2. Produce stable `source_id`, `document_version`, `chunk_id`, `acl_scope`, `updated_at` and extraction offsets.
3. Index lexical and/or vector representations; reconcile expected documents with indexed chunks.
4. At query time authenticate identity, enforce source/resource ACL, apply metadata filters, retrieve candidates.
5. Optionally rewrite query and rerank only if eval shows gain; pack context by token budget and source precedence.
6. Produce grounded output with explicit claim-source mapping or abstain when evidence insufficient.
7. Log request/trace IDs and non-sensitive version/latency/cost details; test deletion and refresh.

## Alternatives
- Search-only: strong choice when exact source discovery, not synthesized answers, is core.
- Extractive Q&A: for narrow structured facts and traceable quotations.
- Standard RAG: when answering from changing external knowledge and provenance is required.
- Hybrid retrieval: useful for identifiers/entities + semantic paraphrase, but validate candidate fusion and latency.
- Tool-mediated lookup: for fresh structured systems; enforce permissions and confirmations.

## Architecture deliverable
Include data flow, trust boundaries, corpus lifecycle, query flow, auth model, failure modes, PII/logging, eval dataset, rollout and rollback gates. Quantify only supported metrics.