# csharikrishna/cortexrag architecture

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

- Interactive diagram: https://gitdiagram.com/csharikrishna/cortexrag
- Repository: https://github.com/csharikrishna/cortexrag

## Overview

1. **What this repo is**
   - `processor/` is the main runtime package for a production RAG backend.
   - The system is organized around two primary flows: **document ingestion/indexing** and **query retrieval/answering**.
   - It is designed to run as a containerized service with external storage/search components.

2. **Runtime and deployment boundary**
   - `docker-compose.yml` is the top-level orchestration entrypoint.
   - The backend service is built from the `processor/dockerfile*` images and launched through `processor/entrypoint.py` / `entrypoint.sh`.
   - The README indicates the service depends materially on **Weaviate** for vector search and **Neo4j** for graph storage, with configuration driven by environment variables in `processor/core/config.py`.

3. **API surface**
   - `processor/api_server.py` is the main API layer, exposing document upload and RAG query endpoints.
   - The README calls out `/upload` for ingestion and `/v1/rag` for retrieval/generation.
   - Static/UI assets in `processor/static/` and `processor/templates/` provide a lightweight web interface and sample pages, but the architecture is primarily API-first.

4. **Document ingestion pipeline**
   - Incoming files are handled by `processor/loaders/` with separate loaders for **PDF** and **DOCX**.
   - The extraction layer in `processor/extractors/` breaks documents into structured pieces: section slicing, boundary detection, metadata extraction, and reference extraction.
   - This pipeline converts raw files into normalized document units suitable for chunking and indexing.

5. **Chunking and normalization**
   - `processor/indexing/chunking.py` and related helpers in `processor/utils/` handle chunk formation and cleanup.
   - Utilities such as `chunk_classifier`, `chunk_rewriter`, and `postprocessing` indicate the system does more than naive splitting: it tries to preserve semantic boundaries and improve chunk quality before indexing.
   - This is an important architectural boundary because retrieval quality depends on these normalized chunks, not raw source text.

6. **Embedding and vector storage**
   - `processor/indexing/embedding.py` produces dense embeddings, using the model described in the README (`BAAI/bge-large-en-v1.5`).
   - `processor/databases/weaviate_store.py` is the vector store adapter, and Weaviate is the primary dense retrieval backend.
   - The ingestion flow writes chunk vectors and associated metadata into Weaviate so the retrieval layer can perform semantic search.

7. **Graph storage and relationship modeling**
   - `processor/databases/graphdb.py` connects the pipeline to Neo4j.
   - The readme’s “knowledge graph integration” plus the presence of reference extraction suggests ingestion also materializes document relationships, links, and multi-hop structure into the graph.
   - This creates a second persistence tier alongside the vector index: **Weaviate for similarity search**, **Neo4j for relational traversal**.

8. **Retrieval orchestration**
   - `processor/retrieval/engine.py` is the main coordinator for query-time execution.
   - `query_analyzer.py` classifies queries by complexity, which supports the repo’s low/high/complex routing strategy.
   - `retrieval_store.py`, `cache.py`, and `reranker.py` show the query path is multi-stage: candidate retrieval, optional cache reuse, then cross-encoder-style reranking before final context selection.

9. **Answer assembly**
   - `context_assembler.py` is the boundary where ranked evidence becomes the final prompt/context passed to the model layer.
   - `quality.py` and `evaluator.py` indicate the system measures retrieval or context quality before returning results.
   - The README’s mention of an external LLM provider (`OLLAMA_URL`, `OLLAMA_MODEL`) means generation is delegated to a configurable model service rather than embedded in the API layer.

10. **State, jobs, and lightweight persistence**
   - `processor/databases/jobs.db` suggests local SQLite-backed job or pipeline state tracking.
   - This is separate from the search indexes and likely used for ingestion status, bookkeeping, or operational metadata.
   - It is a small but important boundary: ephemeral/local operational state vs. the durable search stores.

11. **Integration and operational tooling**
   - `check_weaviate.py` and `service_connectivity_test.py` are health/connectivity utilities for external dependencies.
   - `evaluate_retrieval.py`, `load_test_retrieval.py`, and `processor/tests/` provide validation, benchmarking, and regression coverage for the retrieval stack.
   - `processor/mcp_retrieval_tool.py` indicates an additional integration surface for exposing retrieval capabilities to external tooling or agents.

12. **Architectural summary**
   - The core diagram should show: **Client/UI → API server → ingestion pipeline → loaders/extractors/chunking → Weaviate + Neo4j + local job state**.
   - For queries: **Client/UI → API server → query analyzer → retrieval engine → Weaviate/Neo4j/cache → reranker → context assembler → LLM provider**.
   - The main architectural theme is a **dual-store RAG system** where vector similarity and graph relationships are both first-class retrieval signals.

Main entry points: [`processor/api_server.py`](https://github.com/csharikrishna/cortexrag/blob/main/processor/api_server.py) (API Server), [`processor/retrieval/engine.py`](https://github.com/csharikrishna/cortexrag/blob/main/processor/retrieval/engine.py) (Retrieval Engine), [`processor/extractors/data_extractor.py`](https://github.com/csharikrishna/cortexrag/blob/main/processor/extractors/data_extractor.py) (Extractors), [`processor/retrieval/retrieval_store.py`](https://github.com/csharikrishna/cortexrag/blob/main/processor/retrieval/retrieval_store.py) (Retrieval Store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime & API"]
  node_docker_compose["Compose<br/>orchestration<br/>[docker-compose.yml]"]
  node_api_server["API Server<br/>http api<br/>[api_server.py]"]
  node_entrypoint["Entrypoint<br/>service boot<br/>[entrypoint.py]"]
  node_config["Config<br/>settings<br/>[config.py]"]
  node_ui["UI Assets<br/>web assets<br/>[rag_ui.html]"]
end

subgraph group_ingestion["Ingestion Pipeline"]
  node_loaders["Loaders<br/>file intake<br/>[loader.py]"]
  node_extractors["Extractors<br/>document parse<br/>[data_extractor.py]"]
  node_chunking["Chunking<br/>text segmentation<br/>[chunking.py]"]
  node_embedder["Embeddings<br/>vector encode<br/>[embedding.py]"]
end

subgraph group_retrieval["Query & Answering"]
  node_query_analyzer["Analyzer<br/>query routing<br/>[query_analyzer.py]"]
  node_retrieval_engine["Retrieval Engine<br/>orchestrator<br/>[engine.py]"]
  node_retrieval_store["Retrieval Store<br/>candidate fetch<br/>[retrieval_store.py]"]
  node_cache["Cache<br/>[cache.py]"]
  node_reranker["Reranker<br/>[reranker.py]"]
  node_context_assembler["Context Assembler<br/>prompt assembly"]
  node_quality{{"Quality Checks<br/>evaluation<br/>[quality.py]"}}
end

subgraph group_storage["Storage & Integrations"]
  node_weaviate[("Weaviate Store<br/>vector db adapter<br/>[weaviate_store.py]")]
  node_graphdb[("Graph DB<br/>graph adapter<br/>[graphdb.py]")]
  node_jobsdb[("Jobs DB<br/>local sqlite<br/>[jobs.db]")]
  node_ollama[("LLM Provider<br/>generation backend")]
end

node_docker_compose -->|"starts"| node_entrypoint
node_entrypoint -->|"launches"| node_api_server
node_api_server -->|"reads"| node_config
node_api_server -->|"ingests"| node_loaders
node_loaders -->|"passes"| node_extractors
node_extractors -->|"segments"| node_chunking
node_chunking -->|"encodes"| node_embedder
node_embedder -->|"stores"| node_weaviate
node_extractors -->|"links"| node_graphdb
node_api_server -->|"tracks"| node_jobsdb
node_api_server -->|"routes"| node_query_analyzer
node_query_analyzer -->|"selects"| node_retrieval_engine
node_retrieval_engine -->|"fetches"| node_retrieval_store
node_retrieval_store -->|"searches"| node_weaviate
node_retrieval_store -->|"traverses"| node_graphdb
node_retrieval_engine -->|"reuses"| node_cache
node_retrieval_engine -->|"ranks"| node_reranker
node_reranker -->|"feeds"| node_context_assembler
node_context_assembler -->|"checks"| node_quality
node_context_assembler -->|"prompts"| node_ollama
node_api_server -->|"serves"| node_ui

click node_docker_compose "https://github.com/csharikrishna/cortexrag/blob/main/docker-compose.yml"
click node_api_server "https://github.com/csharikrishna/cortexrag/blob/main/processor/api_server.py"
click node_entrypoint "https://github.com/csharikrishna/cortexrag/blob/main/processor/entrypoint.py"
click node_config "https://github.com/csharikrishna/cortexrag/blob/main/processor/core/config.py"
click node_loaders "https://github.com/csharikrishna/cortexrag/blob/main/processor/loaders/loader.py"
click node_extractors "https://github.com/csharikrishna/cortexrag/blob/main/processor/extractors/data_extractor.py"
click node_chunking "https://github.com/csharikrishna/cortexrag/blob/main/processor/indexing/chunking.py"
click node_embedder "https://github.com/csharikrishna/cortexrag/blob/main/processor/indexing/embedding.py"
click node_weaviate "https://github.com/csharikrishna/cortexrag/blob/main/processor/databases/weaviate_store.py"
click node_graphdb "https://github.com/csharikrishna/cortexrag/blob/main/processor/databases/graphdb.py"
click node_jobsdb "https://github.com/csharikrishna/cortexrag/blob/main/processor/databases/jobs.db"
click node_query_analyzer "https://github.com/csharikrishna/cortexrag/blob/main/processor/retrieval/query_analyzer.py"
click node_retrieval_engine "https://github.com/csharikrishna/cortexrag/blob/main/processor/retrieval/engine.py"
click node_retrieval_store "https://github.com/csharikrishna/cortexrag/blob/main/processor/retrieval/retrieval_store.py"
click node_cache "https://github.com/csharikrishna/cortexrag/blob/main/processor/retrieval/cache.py"
click node_reranker "https://github.com/csharikrishna/cortexrag/blob/main/processor/retrieval/reranker.py"
click node_context_assembler "https://github.com/csharikrishna/cortexrag/blob/main/processor/retrieval/context_assembler.py"
click node_quality "https://github.com/csharikrishna/cortexrag/blob/main/processor/retrieval/quality.py"
click node_ui "https://github.com/csharikrishna/cortexrag/blob/main/processor/static/rag_ui.html"

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_docker_compose,node_api_server,node_entrypoint,node_config,node_ui toneBlue
class node_loaders,node_extractors,node_chunking,node_embedder toneAmber
class node_query_analyzer,node_retrieval_engine,node_retrieval_store,node_cache,node_reranker,node_context_assembler,node_quality toneMint
class node_weaviate,node_graphdb,node_jobsdb,node_ollama toneRose
```

## Components

### Runtime & API

Container entrypoint and API surface for the RAG service.

- [Compose](https://github.com/csharikrishna/cortexrag/blob/main/docker-compose.yml): orchestration · Top-level service orchestration entrypoint. · `docker-compose.yml`
- [API Server](https://github.com/csharikrishna/cortexrag/blob/main/processor/api_server.py): http api · Main ingestion and RAG query API layer. · `processor/api_server.py`
- [Entrypoint](https://github.com/csharikrishna/cortexrag/blob/main/processor/entrypoint.py): service boot · Container startup and process launch. · `processor/entrypoint.py`
- [Config](https://github.com/csharikrishna/cortexrag/blob/main/processor/core/config.py): settings · Environment-driven runtime and integration configuration. · `processor/core/config.py`
- [UI Assets](https://github.com/csharikrishna/cortexrag/blob/main/processor/static/rag_ui.html): web assets · Lightweight web interface and sample pages. · `processor/static/rag_ui.html`

### Ingestion Pipeline

Document loading, extraction, chunking, embedding, and indexing.

- [Loaders](https://github.com/csharikrishna/cortexrag/blob/main/processor/loaders/loader.py): file intake · Document type adapters for incoming files. · `processor/loaders/loader.py`
- [Extractors](https://github.com/csharikrishna/cortexrag/blob/main/processor/extractors/data_extractor.py): document parse · Structured document parsing and reference extraction. · `processor/extractors/data_extractor.py`
- [Chunking](https://github.com/csharikrishna/cortexrag/blob/main/processor/indexing/chunking.py): text segmentation · Forms normalized semantic chunks from extracted content. · `processor/indexing/chunking.py`
- [Embeddings](https://github.com/csharikrishna/cortexrag/blob/main/processor/indexing/embedding.py): vector encode · Produces dense embeddings for indexed chunks. · `processor/indexing/embedding.py`

### Query & Answering

Query-time routing, retrieval, reranking, and context assembly.

- [Analyzer](https://github.com/csharikrishna/cortexrag/blob/main/processor/retrieval/query_analyzer.py): query routing · Classifies query complexity and selects retrieval strategy. · `processor/retrieval/query_analyzer.py`
- [Retrieval Engine](https://github.com/csharikrishna/cortexrag/blob/main/processor/retrieval/engine.py): orchestrator · Coordinates query-time retrieval and answer preparation. · `processor/retrieval/engine.py`
- [Retrieval Store](https://github.com/csharikrishna/cortexrag/blob/main/processor/retrieval/retrieval_store.py): candidate fetch · Retrieves candidates from search backends. · `processor/retrieval/retrieval_store.py`
- [Cache](https://github.com/csharikrishna/cortexrag/blob/main/processor/retrieval/cache.py): query cache · Reusable intermediate retrieval results. · `processor/retrieval/cache.py`
- [Reranker](https://github.com/csharikrishna/cortexrag/blob/main/processor/retrieval/reranker.py): ranker · Re-scores retrieved candidates before final selection. · `processor/retrieval/reranker.py`
- [Context Assembler](https://github.com/csharikrishna/cortexrag/blob/main/processor/retrieval/context_assembler.py): prompt assembly · Builds the final evidence context for generation. · `processor/retrieval/context_assembler.py`
- [Quality Checks](https://github.com/csharikrishna/cortexrag/blob/main/processor/retrieval/quality.py): evaluation · Measures retrieval or context quality. · `processor/retrieval/quality.py`

### Storage & Integrations

External and local persistence used by the system.

- [Weaviate Store](https://github.com/csharikrishna/cortexrag/blob/main/processor/databases/weaviate_store.py): vector db adapter · Primary semantic retrieval and vector persistence layer. · `processor/databases/weaviate_store.py`
- [Graph DB](https://github.com/csharikrishna/cortexrag/blob/main/processor/databases/graphdb.py): graph adapter · Neo4j integration for document relationships and traversal. · `processor/databases/graphdb.py`
- [Jobs DB](https://github.com/csharikrishna/cortexrag/blob/main/processor/databases/jobs.db): local sqlite · Operational job and pipeline state tracking. · `processor/databases/jobs.db`
- **LLM Provider**: generation backend · External model service used for answer generation.

## Connections

- Compose → Entrypoint: starts · Orchestrates the service container.
- Entrypoint → API Server: launches · Boots the main API process.
- API Server → Config: reads · Loads runtime settings and provider endpoints.
- API Server → Loaders: ingests · Accepts uploaded documents for processing.
- Loaders → Extractors: passes · Raw files are normalized into structured content.
- Extractors → Chunking: segments · Document structure is converted into chunks.
- Chunking → Embeddings: encodes · Chunks are prepared for vector embedding.
- Embeddings → Weaviate Store: stores · Writes dense vectors and metadata to the vector index.
- Extractors → Graph DB: links · Extracted references and relationships are materialized in the graph.
- API Server → Jobs DB: tracks · Records ingestion status and operational state.
- API Server → Analyzer: routes · Classifies inbound questions by complexity.
- Analyzer → Retrieval Engine: selects · Hands off to the appropriate retrieval strategy.
- Retrieval Engine → Retrieval Store: fetches · Pulls candidate evidence from search backends.
- Retrieval Store → Weaviate Store: searches · Uses semantic similarity search.
- Retrieval Store → Graph DB: traverses · Uses graph relationships for multi-hop evidence.
- Retrieval Engine → Cache: reuses · Checks for reusable query artifacts.
- Retrieval Engine → Reranker: ranks · Refines candidate ordering before answer assembly.
- Reranker → Context Assembler: feeds · Top evidence is assembled into final context.
- Context Assembler → Quality Checks: checks · Context quality is evaluated before returning results.
- Context Assembler → LLM Provider: prompts · Final context is sent to the external LLM provider.
- API Server → UI Assets: serves · Exposes a lightweight browser interface.
