# brainwires/project-rag architecture

> Architecture diagram of the GitHub repository brainwires/project-rag, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/brainwires/project-rag
- Repository: https://github.com/brainwires/project-rag

## Overview

Project RAG is a local-first codebase indexing and retrieval system, exposed as both a Rust client library and an MCP server. The principal workflow is an assistant request routed through the MCP server to RagClient, which indexes project files into chunks, embeds and stores them, then serves hybrid search results. Separate capabilities cover git-history search and code navigation (definitions, references, and call graphs). The graph follows documented capabilities and sampled ownership; wiring inside unsampled client and server methods is shown only where the README describes it.

Main entry points: [`src/client/mod.rs`](https://github.com/brainwires/project-rag/blob/main/src/client/mod.rs) (RagClient), [`src/indexer/file_walker/mod.rs`](https://github.com/brainwires/project-rag/blob/main/src/indexer/file_walker/mod.rs) (File Walker), [`src/mcp_server.rs`](https://github.com/brainwires/project-rag/blob/main/src/mcp_server.rs) (MCP Server), [`src/vector_db/mod.rs`](https://github.com/brainwires/project-rag/blob/main/src/vector_db/mod.rs) (Vector Database API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Assistant Interface"]
  node_mcp["MCP Server<br/>[mcp_server.rs]"]
  node_client["RagClient<br/>[mod.rs]"]
  node_requests["Request Types<br/>[mod.rs]"]
  node_config["Configuration<br/>[mod.rs]"]
end

subgraph group_indexing["Code Indexing"]
  node_walker["File Walker<br/>[mod.rs]"]
  node_language["Language Detection<br/>[language.rs]"]
  node_ast["AST Chunking<br/>[ast_parser.rs]"]
  node_chunker["Chunking<br/>[chunker.rs]"]
  node_pdf["PDF Extraction<br/>[pdf_extractor.rs]"]
end

subgraph group_retrieval["Search and Storage"]
  node_embedding["Local Embeddings"]
  node_vector_trait["Vector Database API<br/>[mod.rs]"]
  node_lance[("LanceDB Backend<br/>[mod.rs]")]
  node_qdrant[("Qdrant Backend<br/>[qdrant_client.rs]")]
  node_bm25[("BM25 Search<br/>[mod.rs]")]
  node_hash_cache[("File Hash Cache<br/>[cache.rs]")]
end

subgraph group_analysis["History and Navigation"]
  node_git_walker["Git Walker<br/>[walker.rs]"]
  node_git_chunker["Commit Chunking<br/>[chunker.rs]"]
  node_git_cache[("Git Cache<br/>[git_cache.rs]")]
  node_relations["Relations Provider<br/>[mod.rs]"]
  node_repomap["RepoMap Analysis<br/>[mod.rs]"]
  node_relation_store[("Relations Store<br/>[lance_store.rs]")]
end

node_assistant(("AI Assistant"))
node_qdrant_service[("Qdrant Service")]

node_assistant -->|"sends MCP requests"| node_mcp
node_mcp -->|"dispatches tools"| node_client
node_mcp -->|"uses schemas"| node_requests
node_client -->|"loads settings"| node_config
node_client -->|"indexes files"| node_walker
node_walker -->|"detects language"| node_language
node_walker -->|"parses code"| node_ast
node_walker -->|"chunks content"| node_chunker
node_walker -->|"extracts PDFs"| node_pdf
node_client -->|"embeds chunks"| node_embedding
node_client -->|"stores and searches"| node_vector_trait
node_vector_trait -->|"uses default backend"| node_lance
node_vector_trait -.->|"uses optional backend"| node_qdrant
node_qdrant -.->|"reads and writes"| node_qdrant_service
node_client -->|"performs keyword search"| node_bm25
node_client -->|"tracks file changes"| node_hash_cache
node_client -->|"indexes commit history"| node_git_walker
node_git_walker -->|"chunks commits"| node_git_chunker
node_client -->|"tracks indexed commits"| node_git_cache
node_client -->|"finds code relationships"| node_relations
node_relations -->|"uses fallback analysis"| node_repomap
node_client -->|"persists relations"| node_relation_store

click node_mcp "https://github.com/brainwires/project-rag/blob/main/src/mcp_server.rs"
click node_client "https://github.com/brainwires/project-rag/blob/main/src/client/mod.rs"
click node_requests "https://github.com/brainwires/project-rag/blob/main/src/types/mod.rs"
click node_config "https://github.com/brainwires/project-rag/blob/main/src/config/mod.rs"
click node_walker "https://github.com/brainwires/project-rag/blob/main/src/indexer/file_walker/mod.rs"
click node_language "https://github.com/brainwires/project-rag/blob/main/src/indexer/language.rs"
click node_ast "https://github.com/brainwires/project-rag/blob/main/src/indexer/ast_parser.rs"
click node_chunker "https://github.com/brainwires/project-rag/blob/main/src/indexer/chunker.rs"
click node_pdf "https://github.com/brainwires/project-rag/blob/main/src/indexer/pdf_extractor.rs"
click node_embedding "https://github.com/brainwires/project-rag/blob/main/src/embedding/fastembed_manager.rs"
click node_vector_trait "https://github.com/brainwires/project-rag/blob/main/src/vector_db/mod.rs"
click node_lance "https://github.com/brainwires/project-rag/blob/main/src/vector_db/lance_client/mod.rs"
click node_qdrant "https://github.com/brainwires/project-rag/blob/main/src/vector_db/qdrant_client.rs"
click node_bm25 "https://github.com/brainwires/project-rag/blob/main/src/bm25_search/mod.rs"
click node_hash_cache "https://github.com/brainwires/project-rag/blob/main/src/cache.rs"
click node_git_walker "https://github.com/brainwires/project-rag/blob/main/src/git/walker.rs"
click node_git_chunker "https://github.com/brainwires/project-rag/blob/main/src/git/chunker.rs"
click node_git_cache "https://github.com/brainwires/project-rag/blob/main/src/git_cache.rs"
click node_relations "https://github.com/brainwires/project-rag/blob/main/src/relations/mod.rs"
click node_repomap "https://github.com/brainwires/project-rag/blob/main/src/relations/repomap/mod.rs"
click node_relation_store "https://github.com/brainwires/project-rag/blob/main/src/relations/storage/lance_store.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mcp,node_client,node_requests,node_config toneBlue
class node_walker,node_language,node_ast,node_chunker,node_pdf,node_qdrant_service toneAmber
class node_embedding,node_vector_trait,node_lance,node_qdrant,node_bm25,node_hash_cache toneMint
class node_git_walker,node_git_chunker,node_git_cache,node_relations,node_repomap,node_relation_store toneRose
class node_assistant toneIndigo
```

## Components

### Assistant Interface

- [MCP Server](https://github.com/brainwires/project-rag/blob/main/src/mcp_server.rs): `src/mcp_server.rs`
- [RagClient](https://github.com/brainwires/project-rag/blob/main/src/client/mod.rs): `src/client/mod.rs`
- [Request Types](https://github.com/brainwires/project-rag/blob/main/src/types/mod.rs): `src/types/mod.rs`
- [Configuration](https://github.com/brainwires/project-rag/blob/main/src/config/mod.rs): `src/config/mod.rs`

### Code Indexing

- [File Walker](https://github.com/brainwires/project-rag/blob/main/src/indexer/file_walker/mod.rs): `src/indexer/file_walker/mod.rs`
- [Language Detection](https://github.com/brainwires/project-rag/blob/main/src/indexer/language.rs): `src/indexer/language.rs`
- [AST Chunking](https://github.com/brainwires/project-rag/blob/main/src/indexer/ast_parser.rs): `src/indexer/ast_parser.rs`
- [Chunking](https://github.com/brainwires/project-rag/blob/main/src/indexer/chunker.rs): `src/indexer/chunker.rs`
- [PDF Extraction](https://github.com/brainwires/project-rag/blob/main/src/indexer/pdf_extractor.rs): `src/indexer/pdf_extractor.rs`

### Search and Storage

- [Local Embeddings](https://github.com/brainwires/project-rag/blob/main/src/embedding/fastembed_manager.rs): `src/embedding/fastembed_manager.rs`
- [Vector Database API](https://github.com/brainwires/project-rag/blob/main/src/vector_db/mod.rs): `src/vector_db/mod.rs`
- [LanceDB Backend](https://github.com/brainwires/project-rag/blob/main/src/vector_db/lance_client/mod.rs): `src/vector_db/lance_client/mod.rs`
- [Qdrant Backend](https://github.com/brainwires/project-rag/blob/main/src/vector_db/qdrant_client.rs): `src/vector_db/qdrant_client.rs`
- [BM25 Search](https://github.com/brainwires/project-rag/blob/main/src/bm25_search/mod.rs): `src/bm25_search/mod.rs`
- [File Hash Cache](https://github.com/brainwires/project-rag/blob/main/src/cache.rs): `src/cache.rs`

### History and Navigation

- [Git Walker](https://github.com/brainwires/project-rag/blob/main/src/git/walker.rs): `src/git/walker.rs`
- [Commit Chunking](https://github.com/brainwires/project-rag/blob/main/src/git/chunker.rs): `src/git/chunker.rs`
- [Git Cache](https://github.com/brainwires/project-rag/blob/main/src/git_cache.rs): `src/git_cache.rs`
- [Relations Provider](https://github.com/brainwires/project-rag/blob/main/src/relations/mod.rs): `src/relations/mod.rs`
- [RepoMap Analysis](https://github.com/brainwires/project-rag/blob/main/src/relations/repomap/mod.rs): `src/relations/repomap/mod.rs`
- [Relations Store](https://github.com/brainwires/project-rag/blob/main/src/relations/storage/lance_store.rs): `src/relations/storage/lance_store.rs`

### Other components

- **AI Assistant**
- **Qdrant Service**

## Connections

- AI Assistant → MCP Server: sends MCP requests
- MCP Server → RagClient: dispatches tools
- MCP Server → Request Types: uses schemas
- RagClient → Configuration: loads settings
- RagClient → File Walker: indexes files
- File Walker → Language Detection: detects language
- File Walker → AST Chunking: parses code
- File Walker → Chunking: chunks content
- File Walker → PDF Extraction: extracts PDFs
- RagClient → Local Embeddings: embeds chunks
- RagClient → Vector Database API: stores and searches
- Vector Database API → LanceDB Backend: uses default backend
- Vector Database API → Qdrant Backend: uses optional backend
- Qdrant Backend → Qdrant Service: reads and writes
- RagClient → BM25 Search: performs keyword search
- RagClient → File Hash Cache: tracks file changes
- RagClient → Git Walker: indexes commit history
- Git Walker → Commit Chunking: chunks commits
- RagClient → Git Cache: tracks indexed commits
- RagClient → Relations Provider: finds code relationships
- Relations Provider → RepoMap Analysis: uses fallback analysis
- RagClient → Relations Store: persists relations