# Domain Model: Insurance RAG System

## Glossary

### Collection
A logical partition of documents in the vector database. In the current ChromaDB architecture, documents are spread across ~30 collections, each representing an insurance domain or document category. **Pain point:** The system must classify incoming queries to a single collection before retrieval; misclassification leads to irrelevant results.

### Collection Classifier
The first stage of the retrieval pipeline. Responsible for routing an incoming question to exactly one collection. Current accuracy is unknown but degrades on ambiguous queries and edge cases where insurance domains overlap (e.g., a car accident claim question could belong to "car insurance" or "claims processing").

**Current implementation:** Hybrid keyword-first cascade:
1. Keyword match found → boost similarity score to 98% → route to that collection
2. No keyword match → rely on base embedding similarity + LLM assistance
3. When signals conflict → embedding similarity score dominates

**Blind spots:**
- No metrics on keyword coverage (% of queries with identifiable domain keywords)
- No metrics on classification accuracy
- Similarity score can be misleading for semantically similar domains

### Insurance Domain
A category of insurance business: car, health, fire, life, travel, etc. Domains are semantically similar — many questions could plausibly belong to multiple domains, making classification non-trivial.

### Retrieval Pipeline
Two-stage process:
1. **Collection Classifier** → routes query to one collection
2. **Vector Search** → retrieves relevant chunks within that collection

Current bottleneck: Stage 1 errors are unrecoverable.

## Constraints

### Infrastructure Instability
Iran's internet connectivity is subject to government-imposed blackouts lasting up to 90 days. The system must operate fully offline with zero external API dependencies during these periods.

**Implication:** All components (embedding, LLM, vector DB) must have local fallbacks. Cloud APIs are optional enhancements, not dependencies.

### Bilingual Content
Documents and queries are in Persian (Farsi) and English. Embedding models and LLMs must handle both languages effectively.

## Architecture Decisions

1. **Single collection with metadata filtering** (ADR 0001) — eliminates collection classification problem
2. **Hybrid chunking** (ADR 0002) — semantic for unstructured, row-by-row for tabular, markdown-first
3. **Dual embeddings** (ADR 0003) — OpenAI + Nomic for online/offline resilience
4. **Dual reranking** (ADR 0004) — Cohere + BGE for precision
5. **Evaluation framework** (ADR 0005) — test set + metrics for quality measurement
6. **Qdrant Docker deployment** (ADR 0006) — fully on-prem vector database
7. **Hybrid search** (ADR 0007) — dense + sparse (BM25) for exact term matching
8. **Metadata schema** (ADR 0008) — domain, document_type, language, source, plus tabular extensions
9. **API-based continuous ingestion** (ADR 0009) — real-time document processing
10. **Full-context query pipeline** (ADR 0010) — chunks + metadata + history, citations for admin layer
11. **Ollama inference on RTX 3090** (ADR 0011) — Qwen 2.5 + BGE + Nomic
12. **Langfuse observability + API key auth** (ADR 0012) — full tracing and access control