# kaifalikhan-rgb/codebase-rag-system architecture

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

- Interactive diagram: https://gitdiagram.com/kaifalikhan-rgb/codebase-rag-system
- Repository: https://github.com/kaifalikhan-rgb/codebase-rag-system

## Overview

This is a Python-codebase RAG product: it indexes repositories into searchable semantic chunks, then answers code questions using retrieved chunks as grounded context. The primary workflow starts with a user query and passes through retrieval, context construction, and answer generation; a parallel API workflow accepts repository indexing requests and returns indexing status. Indexing tracks file hashes and repository metadata to support incremental re-indexing. The README also describes metadata-rich results, Top-K search, similarity thresholds, and latency measurement. Edges reflect the sampled calls and documented workflow; unsampled implementation details are not inferred.

Main entry points: [`src/indexing/indexer.py`](https://github.com/kaifalikhan-rgb/codebase-rag-system/blob/main/src/indexing/indexer.py) (Index coordinator), [`src/api/app.py`](https://github.com/kaifalikhan-rgb/codebase-rag-system/blob/main/src/api/app.py) (FastAPI routes), [`src/rag/pipeline.py`](https://github.com/kaifalikhan-rgb/codebase-rag-system/blob/main/src/rag/pipeline.py) (RAG pipeline), [`src/retrieval/retriever.py`](https://github.com/kaifalikhan-rgb/codebase-rag-system/blob/main/src/retrieval/retriever.py) (Query retriever)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and orchestration"]
  node_api_app["FastAPI routes<br/>[app.py]"]
  node_rag["RAG pipeline<br/>[pipeline.py]"]
end

subgraph group_index["Repository indexing"]
  node_indexer["Index coordinator<br/>[indexer.py]"]
  node_loader["Python file loader<br/>[loader.py]"]
  node_reader["Source reader<br/>[reader.py]"]
  node_parser["AST parser<br/>[ast_parser.py]"]
  node_chunker["Semantic chunker<br/>[chunker.py]"]
  node_embedder["Embedding model<br/>[embedder.py]"]
  node_chunk_file["Chunk export<br/>[storage.py]"]
  node_hashing["File hashing<br/>[file_hash.py]"]
end

subgraph group_retrieve["Semantic retrieval"]
  node_retriever["Query retriever<br/>[retriever.py]"]
end

subgraph group_answer["Grounded answers"]
  node_context["Context builder<br/>[context_builder.py]"]
  node_llm["Answer generator<br/>[llm_client.py]"]
end

subgraph group_state["Persistent state"]
  node_vector_store[("ChromaDB chunks<br/>[chroma_store.py]")]
  node_index_state["Index state<br/>[index_state.py]"]
  node_schema["Schema version<br/>[schema_version.py]"]
  node_repo_registry["Repository registry<br/>[repositories.py]"]
  node_index_status["Index status<br/>[index_status.py]"]
end

node_user(("User"))
node_gemini["Gemini service"]

node_user -->|"submits request"| node_api_app
node_api_app -->|"starts indexing"| node_indexer
node_api_app -->|"routes query"| node_rag
node_api_app -->|"checks repositories"| node_repo_registry
node_api_app -->|"deletes chunks"| node_vector_store
node_api_app -->|"deletes state"| node_index_state
node_api_app -->|"reads status"| node_index_status
node_indexer -->|"loads files"| node_loader
node_indexer -->|"reads source"| node_reader
node_indexer -->|"parses source"| node_parser
node_indexer -->|"extracts chunks"| node_chunker
node_indexer -->|"hashes files"| node_hashing
node_indexer -->|"checks schema"| node_schema
node_indexer -->|"loads and saves"| node_index_state
node_indexer -->|"sets status"| node_index_status
node_indexer -->|"registers repository"| node_repo_registry
node_indexer -->|"saves chunks"| node_chunk_file
node_indexer -->|"embeds chunks"| node_embedder
node_indexer -->|"upserts chunks"| node_vector_store
node_retriever -->|"embeds query"| node_embedder
node_retriever -->|"queries vectors"| node_vector_store
node_rag -->|"retrieves chunks"| node_retriever
node_rag -->|"builds context"| node_context
node_rag -->|"generates answer"| node_llm
node_llm -->|"requests completion"| node_gemini

click node_api_app "https://github.com/kaifalikhan-rgb/codebase-rag-system/blob/main/src/api/app.py"
click node_indexer "https://github.com/kaifalikhan-rgb/codebase-rag-system/blob/main/src/indexing/indexer.py"
click node_loader "https://github.com/kaifalikhan-rgb/codebase-rag-system/blob/main/src/ingestion/loader.py"
click node_reader "https://github.com/kaifalikhan-rgb/codebase-rag-system/blob/main/src/ingestion/reader.py"
click node_parser "https://github.com/kaifalikhan-rgb/codebase-rag-system/blob/main/src/parser/ast_parser.py"
click node_chunker "https://github.com/kaifalikhan-rgb/codebase-rag-system/blob/main/src/chunking/chunker.py"
click node_embedder "https://github.com/kaifalikhan-rgb/codebase-rag-system/blob/main/src/embeddings/embedder.py"
click node_chunk_file "https://github.com/kaifalikhan-rgb/codebase-rag-system/blob/main/src/utils/storage.py"
click node_vector_store "https://github.com/kaifalikhan-rgb/codebase-rag-system/blob/main/src/storage/chroma_store.py"
click node_hashing "https://github.com/kaifalikhan-rgb/codebase-rag-system/blob/main/src/utils/file_hash.py"
click node_index_state "https://github.com/kaifalikhan-rgb/codebase-rag-system/blob/main/src/utils/index_state.py"
click node_schema "https://github.com/kaifalikhan-rgb/codebase-rag-system/blob/main/src/utils/schema_version.py"
click node_repo_registry "https://github.com/kaifalikhan-rgb/codebase-rag-system/blob/main/src/utils/repositories.py"
click node_index_status "https://github.com/kaifalikhan-rgb/codebase-rag-system/blob/main/src/utils/index_status.py"
click node_retriever "https://github.com/kaifalikhan-rgb/codebase-rag-system/blob/main/src/retrieval/retriever.py"
click node_context "https://github.com/kaifalikhan-rgb/codebase-rag-system/blob/main/src/generation/context_builder.py"
click node_rag "https://github.com/kaifalikhan-rgb/codebase-rag-system/blob/main/src/rag/pipeline.py"
click node_llm "https://github.com/kaifalikhan-rgb/codebase-rag-system/blob/main/src/generation/llm_client.py"

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_api_app,node_rag,node_user toneBlue
class node_indexer,node_loader,node_reader,node_parser,node_chunker,node_embedder,node_chunk_file,node_hashing toneAmber
class node_retriever toneMint
class node_context,node_llm toneRose
class node_vector_store,node_index_state,node_schema,node_repo_registry,node_index_status,node_gemini toneIndigo
```

## Components

### API and orchestration

- [FastAPI routes](https://github.com/kaifalikhan-rgb/codebase-rag-system/blob/main/src/api/app.py): `src/api/app.py`
- [RAG pipeline](https://github.com/kaifalikhan-rgb/codebase-rag-system/blob/main/src/rag/pipeline.py): `src/rag/pipeline.py`

### Repository indexing

- [Index coordinator](https://github.com/kaifalikhan-rgb/codebase-rag-system/blob/main/src/indexing/indexer.py): `src/indexing/indexer.py`
- [Python file loader](https://github.com/kaifalikhan-rgb/codebase-rag-system/blob/main/src/ingestion/loader.py): `src/ingestion/loader.py`
- [Source reader](https://github.com/kaifalikhan-rgb/codebase-rag-system/blob/main/src/ingestion/reader.py): `src/ingestion/reader.py`
- [AST parser](https://github.com/kaifalikhan-rgb/codebase-rag-system/blob/main/src/parser/ast_parser.py): `src/parser/ast_parser.py`
- [Semantic chunker](https://github.com/kaifalikhan-rgb/codebase-rag-system/blob/main/src/chunking/chunker.py): `src/chunking/chunker.py`
- [Embedding model](https://github.com/kaifalikhan-rgb/codebase-rag-system/blob/main/src/embeddings/embedder.py): `src/embeddings/embedder.py`
- [Chunk export](https://github.com/kaifalikhan-rgb/codebase-rag-system/blob/main/src/utils/storage.py): `src/utils/storage.py`
- [File hashing](https://github.com/kaifalikhan-rgb/codebase-rag-system/blob/main/src/utils/file_hash.py): `src/utils/file_hash.py`

### Semantic retrieval

- [Query retriever](https://github.com/kaifalikhan-rgb/codebase-rag-system/blob/main/src/retrieval/retriever.py): `src/retrieval/retriever.py`

### Grounded answers

- [Context builder](https://github.com/kaifalikhan-rgb/codebase-rag-system/blob/main/src/generation/context_builder.py): `src/generation/context_builder.py`
- [Answer generator](https://github.com/kaifalikhan-rgb/codebase-rag-system/blob/main/src/generation/llm_client.py): `src/generation/llm_client.py`

### Persistent state

- [ChromaDB chunks](https://github.com/kaifalikhan-rgb/codebase-rag-system/blob/main/src/storage/chroma_store.py): `src/storage/chroma_store.py`
- [Index state](https://github.com/kaifalikhan-rgb/codebase-rag-system/blob/main/src/utils/index_state.py): `src/utils/index_state.py`
- [Schema version](https://github.com/kaifalikhan-rgb/codebase-rag-system/blob/main/src/utils/schema_version.py): `src/utils/schema_version.py`
- [Repository registry](https://github.com/kaifalikhan-rgb/codebase-rag-system/blob/main/src/utils/repositories.py): `src/utils/repositories.py`
- [Index status](https://github.com/kaifalikhan-rgb/codebase-rag-system/blob/main/src/utils/index_status.py): `src/utils/index_status.py`

### Other components

- **User**
- **Gemini service**

## Connections

- User → FastAPI routes: submits request (evidence: `src/api/app.py`)
- FastAPI routes → Index coordinator: starts indexing (evidence: `src/api/app.py`)
- FastAPI routes → RAG pipeline: routes query (evidence: `src/api/app.py`)
- FastAPI routes → Repository registry: checks repositories (evidence: `src/api/app.py`)
- FastAPI routes → ChromaDB chunks: deletes chunks (evidence: `src/api/app.py`)
- FastAPI routes → Index state: deletes state (evidence: `src/api/app.py`)
- FastAPI routes → Index status: reads status (evidence: `src/api/app.py`)
- Index coordinator → Python file loader: loads files (evidence: `src/indexing/indexer.py`)
- Index coordinator → Source reader: reads source (evidence: `src/indexing/indexer.py`)
- Index coordinator → AST parser: parses source (evidence: `src/indexing/indexer.py`)
- Index coordinator → Semantic chunker: extracts chunks (evidence: `src/indexing/indexer.py`)
- Index coordinator → File hashing: hashes files (evidence: `src/indexing/indexer.py`)
- Index coordinator → Schema version: checks schema (evidence: `src/indexing/indexer.py`)
- Index coordinator → Index state: loads and saves (evidence: `src/indexing/indexer.py`)
- Index coordinator → Index status: sets status (evidence: `src/indexing/indexer.py`)
- Index coordinator → Repository registry: registers repository (evidence: `src/indexing/indexer.py`)
- Index coordinator → Chunk export: saves chunks (evidence: `src/indexing/indexer.py`)
- Index coordinator → Embedding model: embeds chunks (evidence: `src/indexing/indexer.py`)
- Index coordinator → ChromaDB chunks: upserts chunks (evidence: `src/indexing/indexer.py`)
- Query retriever → Embedding model: embeds query (evidence: `src/retrieval/retriever.py`)
- Query retriever → ChromaDB chunks: queries vectors (evidence: `src/retrieval/retriever.py`)
- RAG pipeline → Query retriever: retrieves chunks (evidence: `src/rag/pipeline.py`)
- RAG pipeline → Context builder: builds context (evidence: `src/rag/pipeline.py`)
- RAG pipeline → Answer generator: generates answer (evidence: `src/rag/pipeline.py`)
- Answer generator → Gemini service: requests completion (evidence: `src/generation/llm_client.py`)
