# shubhamharkare/codesearch-ai architecture

> Architecture diagram of the GitHub repository shubhamharkare/codesearch-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shubhamharkare/codesearch-ai
- Repository: https://github.com/shubhamharkare/codesearch-ai

## Overview

CodeSearch AI answers questions about React documentation, grounding responses in retrievable sections and declining unsupported questions. The user workflow runs from the Streamlit client through the FastAPI ask route into the answer pipeline: optional follow-up condensation and cache lookup, retrieval/reranking, abstention, then local LLM generation and citation validation. A separate ingestion workflow fetches and chunks the documentation into a versioned dense/BM25 index. Admin endpoints expose health and index status. The README documents these main flows; monitoring and explanation modules are present, but their runtime wiring was not sampled.

Main entry points: [`codesearch/pipeline.py`](https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/pipeline.py) (Answer pipeline), [`codesearch/ingest/build.py`](https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/ingest/build.py) (Index builder), [`codesearch/index/handle.py`](https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/index/handle.py) (Live index handle), [`codesearch/api/routes_admin.py`](https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/api/routes_admin.py) (Admin routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client and API"]
  node_ui["Streamlit UI<br/>[streamlit_app.py]"]
  node_api_client["HTTP client<br/>[api_client.py]"]
  node_api["FastAPI routes<br/>[routes_ask.py]"]
end

subgraph group_answer["Answer workflow"]
  node_pipeline["Answer pipeline<br/>[pipeline.py]"]
  node_condense["Follow-up rewrite<br/>[condense.py]"]
  node_cache["Tiered answer cache<br/>[tiered.py]"]
  node_exact_cache["Exact cache<br/>[exact.py]"]
  node_redis[("Redis")]
  node_retriever["Hybrid retrieval<br/>[hybrid.py]"]
  node_reranker["Reranking<br/>[rerank.py]"]
  node_abstain["Abstention gate<br/>[abstain.py]"]
  node_llm["Ollama generation<br/>[llm.py]"]
  node_citations["Citation validation<br/>[citations.py]"]
end

subgraph group_indexing["Ingestion and index"]
  node_index_handle["Live index handle<br/>[handle.py]"]
  node_vector[("Chroma vectors<br/>[vector_store.py]")]
  node_bm25[("BM25 index<br/>[bm25.py]")]
  node_fetch["Documentation fetch<br/>[fetch.py]"]
  node_chunker["Section chunking<br/>[chunker.py]"]
  node_build["Index builder<br/>[build.py]"]
  node_manifest["Index manifest<br/>[manifest.py]"]
end

subgraph group_operations["Operations and observability"]
  node_admin["Admin routes<br/>[routes_admin.py]"]
  node_explain["Answer explanations"]
  node_monitoring["Monitoring"]
end

subgraph group_contracts["Shared contracts"]
  node_schemas["Answer and chunk data<br/>[schemas.py]"]
end

node_user(("Question asker"))

node_user -->|"asks"| node_ui
node_ui -->|"sends request"| node_api_client
node_api_client -->|"calls HTTP"| node_api
node_api -->|"invokes"| node_pipeline
node_pipeline -->|"rewrites follow-up"| node_condense
node_pipeline -->|"checks and stores"| node_cache
node_cache -->|"uses exact tier"| node_exact_cache
node_exact_cache -->|"reads and writes"| node_redis
node_pipeline -->|"retrieves chunks"| node_retriever
node_retriever -->|"reads snapshot"| node_index_handle
node_index_handle -->|"opens store"| node_vector
node_index_handle -->|"opens index"| node_bm25
node_pipeline -->|"reranks candidates"| node_reranker
node_pipeline -->|"checks scope"| node_abstain
node_pipeline -->|"generates answer"| node_llm
node_pipeline -->|"validates citations"| node_citations
node_fetch -->|"supplies documents"| node_chunker
node_chunker -->|"provides chunks"| node_build
node_build -->|"builds dense index"| node_vector
node_build -->|"builds lexical index"| node_bm25
node_build -->|"writes version metadata"| node_manifest
node_admin -->|"reports readiness"| node_index_handle
node_admin -->|"returns index metadata"| node_manifest
node_pipeline -.-> node_explain
node_pipeline -.-> node_monitoring
node_pipeline -->|"returns answer data"| node_schemas

click node_ui "https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/ui/streamlit_app.py"
click node_api_client "https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/ui/api_client.py"
click node_api "https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/api/routes_ask.py"
click node_admin "https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/api/routes_admin.py"
click node_pipeline "https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/pipeline.py"
click node_condense "https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/retrieval/condense.py"
click node_cache "https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/cache/tiered.py"
click node_exact_cache "https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/cache/exact.py"
click node_retriever "https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/retrieval/hybrid.py"
click node_reranker "https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/retrieval/rerank.py"
click node_abstain "https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/retrieval/abstain.py"
click node_llm "https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/generation/llm.py"
click node_citations "https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/generation/citations.py"
click node_index_handle "https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/index/handle.py"
click node_vector "https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/index/vector_store.py"
click node_bm25 "https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/index/bm25.py"
click node_fetch "https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/ingest/fetch.py"
click node_chunker "https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/ingest/chunker.py"
click node_build "https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/ingest/build.py"
click node_manifest "https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/ingest/manifest.py"
click node_explain "https://github.com/shubhamharkare/codesearch-ai/tree/main/codesearch/explain"
click node_monitoring "https://github.com/shubhamharkare/codesearch-ai/tree/main/codesearch/monitoring"
click node_schemas "https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/schemas.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_ui,node_api_client,node_api toneBlue
class node_pipeline,node_condense,node_cache,node_exact_cache,node_redis,node_retriever,node_reranker,node_abstain,node_llm,node_citations toneAmber
class node_index_handle,node_vector,node_bm25,node_fetch,node_chunker,node_build,node_manifest toneMint
class node_admin,node_explain,node_monitoring toneRose
class node_schemas,node_user toneIndigo
```

## Components

### Client and API

- [Streamlit UI](https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/ui/streamlit_app.py): `codesearch/ui/streamlit_app.py`
- [HTTP client](https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/ui/api_client.py): `codesearch/ui/api_client.py`
- [FastAPI routes](https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/api/routes_ask.py): `codesearch/api/routes_ask.py`

### Answer workflow

- [Answer pipeline](https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/pipeline.py): `codesearch/pipeline.py`
- [Follow-up rewrite](https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/retrieval/condense.py): `codesearch/retrieval/condense.py`
- [Tiered answer cache](https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/cache/tiered.py): `codesearch/cache/tiered.py`
- [Exact cache](https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/cache/exact.py): `codesearch/cache/exact.py`
- **Redis**
- [Hybrid retrieval](https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/retrieval/hybrid.py): `codesearch/retrieval/hybrid.py`
- [Reranking](https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/retrieval/rerank.py): `codesearch/retrieval/rerank.py`
- [Abstention gate](https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/retrieval/abstain.py): `codesearch/retrieval/abstain.py`
- [Ollama generation](https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/generation/llm.py): `codesearch/generation/llm.py`
- [Citation validation](https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/generation/citations.py): `codesearch/generation/citations.py`

### Ingestion and index

- [Live index handle](https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/index/handle.py): `codesearch/index/handle.py`
- [Chroma vectors](https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/index/vector_store.py): `codesearch/index/vector_store.py`
- [BM25 index](https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/index/bm25.py): `codesearch/index/bm25.py`
- [Documentation fetch](https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/ingest/fetch.py): `codesearch/ingest/fetch.py`
- [Section chunking](https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/ingest/chunker.py): `codesearch/ingest/chunker.py`
- [Index builder](https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/ingest/build.py): `codesearch/ingest/build.py`
- [Index manifest](https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/ingest/manifest.py): `codesearch/ingest/manifest.py`

### Operations and observability

- [Admin routes](https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/api/routes_admin.py): `codesearch/api/routes_admin.py`
- [Answer explanations](https://github.com/shubhamharkare/codesearch-ai/tree/main/codesearch/explain): `codesearch/explain`
- [Monitoring](https://github.com/shubhamharkare/codesearch-ai/tree/main/codesearch/monitoring): `codesearch/monitoring`

### Shared contracts

- [Answer and chunk data](https://github.com/shubhamharkare/codesearch-ai/blob/main/codesearch/schemas.py): `codesearch/schemas.py`

### Other components

- **Question asker**

## Connections

- Question asker → Streamlit UI: asks (evidence: `README.md`)
- Streamlit UI → HTTP client: sends request (evidence: `codesearch/ui/streamlit_app.py`)
- HTTP client → FastAPI routes: calls HTTP (evidence: `README.md`)
- FastAPI routes → Answer pipeline: invokes (evidence: `codesearch/api/main.py`)
- Answer pipeline → Follow-up rewrite: rewrites follow-up (evidence: `codesearch/pipeline.py`)
- Answer pipeline → Tiered answer cache: checks and stores (evidence: `codesearch/pipeline.py`)
- Tiered answer cache → Exact cache: uses exact tier (evidence: `codesearch/cache/tiered.py`)
- Exact cache → Redis: reads and writes (evidence: `codesearch/cache/exact.py`)
- Answer pipeline → Hybrid retrieval: retrieves chunks (evidence: `codesearch/pipeline.py`)
- Hybrid retrieval → Live index handle: reads snapshot (evidence: `codesearch/retrieval/hybrid.py`)
- Live index handle → Chroma vectors: opens store (evidence: `codesearch/index/handle.py`)
- Live index handle → BM25 index: opens index (evidence: `codesearch/index/handle.py`)
- Answer pipeline → Reranking: reranks candidates (evidence: `codesearch/pipeline.py`)
- Answer pipeline → Abstention gate: checks scope (evidence: `codesearch/pipeline.py`)
- Answer pipeline → Ollama generation: generates answer (evidence: `codesearch/pipeline.py`)
- Answer pipeline → Citation validation: validates citations (evidence: `codesearch/pipeline.py`)
- Documentation fetch → Section chunking: supplies documents (evidence: `codesearch/ingest/build.py`)
- Section chunking → Index builder: provides chunks (evidence: `codesearch/ingest/build.py`)
- Index builder → Chroma vectors: builds dense index (evidence: `codesearch/ingest/build.py`)
- Index builder → BM25 index: builds lexical index (evidence: `codesearch/ingest/build.py`)
- Index builder → Index manifest: writes version metadata (evidence: `codesearch/ingest/build.py`)
- Admin routes → Live index handle: reports readiness (evidence: `codesearch/api/routes_admin.py`)
- Admin routes → Index manifest: returns index metadata (evidence: `codesearch/api/routes_admin.py`)
- Answer pipeline → Answer explanations
- Answer pipeline → Monitoring
- Answer pipeline → Answer and chunk data: returns answer data (evidence: `codesearch/pipeline.py`)