This directory contains Architecture Decision Records for Project RAG, documenting key design decisions and their rationale.
| ADR | Title | Status | Date |
|---|---|---|---|
| 001 | LanceDB as Default Vector Database | Accepted | 2024-11 |
| 002 | Hybrid Search with Reciprocal Rank Fusion | Accepted | 2024-11 |
| 003 | Smart Indexing with Auto-Detection | Accepted | 2024-11 |
An Architecture Decision Record (ADR) captures an important architectural decision made along with its context and consequences.
Each ADR follows this structure:
- Status: Proposed, Accepted, Deprecated, Superseded
- Context: The situation that led to the decision
- Decision: What we decided to do
- Rationale: Why we made this choice
- Consequences: The impact (positive, negative, neutral)
- Alternatives Considered: What else we evaluated
- References: Links to code, docs, papers
ADRs provide:
- Historical Context: Understand why decisions were made
- Onboarding: Help new contributors understand the system
- Prevent Revisiting: Document why alternatives were rejected
- Architectural Visibility: Make implicit decisions explicit
Vector Database Choice (ADR 001)
Decision: Use LanceDB as default embedded database instead of requiring external Qdrant server.
Impact: Zero-setup experience, faster local development, reduced operational complexity.
Hybrid Search Strategy (ADR 002)
Decision: Combine vector similarity with BM25 keyword search using Reciprocal Rank Fusion.
Impact: Better search quality for code (exact matches + semantic understanding), minimal performance overhead.
Smart Indexing (ADR 003)
Decision: Auto-detect whether to do full or incremental indexing based on persistent cache.
Impact: Seamless UX (no manual mode selection), 7-30x faster subsequent indexing.
When making significant architectural decisions:
- Create a new ADR with next number (004, 005, etc.)
- Follow the existing format
- Update this README index
- Link to relevant code and related ADRs