Architecture Decision Records

Decisions with lasting consequences, recorded so the why survives the conversation that produced it. Format: Context → Decision → Consequences.

ADR	Decision	Status
ADR-001	PostgreSQL + pgvector as the vector store (Qdrant-GPU dropped)	Accepted
ADR-002	infinity as the embedding service (FastEmbed dropped)	Accepted
ADR-003	Vertical-slice build order + v1 operational choices	Accepted (amended)
ADR-004	EasyOCR as the shipped OCR fallback engine (benchmark-decided)	Accepted
ADR-005	The v2 web GUI + HTTP API stack (Next.js + FastAPI + SSE; single-user)	Accepted
ADR-006	Reranking wired into the query path as a composing retriever (≈67% tier)	Accepted
ADR-007	In-app Prometheus metrics + provisioned Grafana (exporters optional)	Accepted
ADR-008	recursive_character stays the chunking default (benchmark-decided)	Accepted
ADR-009	Office/web modalities via a generalized Docling core (images/audio deferred)	Accepted
ADR-010	Evidence-panel page previews via on-demand server-side locate + render	Accepted
ADR-011	The chat engine registry and Condense + Context (default stays simple — benchmark-decided)	Accepted
ADR-012	Relative-path uploads + the composer's client-side ingest queue	Accepted
ADR-013	Store-derived corpus gauges over ingest-counter arithmetic	Accepted
ADR-014	bun as the package manager, Node as the runtime	Accepted
ADR-015	In-app codebase map (/map + developer mode) — curated TS data, condensed foglamp-style canvas	Accepted (amended)
ADR-016	HyDE as a composing retriever, paired under rerank (default stays hybrid)	Accepted
ADR-017	The GraphRAG engine + its storage/viz/degrade/defaults directives (bake-off-decided: LightRAG)	Accepted (amended)
ADR-018	The codebase map on the docs site — the /map view, Vite-built into a checked-in bundle and framed	Accepted
ADR-019	Corpus backups — one zip per backup in each corpus's reserved varagity-exports/ folder, restored with no model call	Accepted