# renganathan077/hybrid-rag-system architecture

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

- Interactive diagram: https://gitdiagram.com/renganathan077/hybrid-rag-system
- Repository: https://github.com/renganathan077/hybrid-rag-system

## Overview

This is a hybrid retrieval-augmented question-answering service. Users submit questions through the CLI or OpenAI-compatible API; the hybrid workflow retrieves role-filtered document chunks, chooses local context or DuckDuckGo results based on relevance, and generates an answer with Ollama. The documented ingestion and indexing stages prepare PDF chunks and metadata in Milvus. The separate basic RAG graph and direct-query scripts are also represented. Runtime relationships are based on excerpts and README statements; unsampled subsystems are not inferred.

Main entry points: [`hybrid_rag.py`](https://github.com/renganathan077/hybrid-rag-system/blob/main/hybrid_rag.py) (Hybrid CLI), [`build_index.py`](https://github.com/renganathan077/hybrid-rag-system/blob/main/build_index.py) (Embedding and indexing), [`rag_graph.py`](https://github.com/renganathan077/hybrid-rag-system/blob/main/rag_graph.py) (Basic RAG graph), [`rag_answer.py`](https://github.com/renganathan077/hybrid-rag-system/blob/main/rag_answer.py) (Direct RAG answer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prep["Document preparation"]
  node_pdfs["Source PDFs"]
  node_ingest["PDF chunk extraction<br/>[ingest_docs.py]"]
  node_chunk_demo["Chunking example<br/>[chunk_text.py]"]
  node_chunk_json["Chunk records"]
end

subgraph group_store["Vector storage"]
  node_index["Embedding and indexing<br/>[build_index.py]"]
  node_milvus[("Milvus collections")]
  node_reset["Milvus reset utility<br/>[reset_milvus.py]"]
end

subgraph group_runtime["Hybrid answering"]
  node_loader["Collection readiness<br/>[hybrid_rag.py]"]
  node_retrieval["Role-filtered retrieval<br/>[hybrid_rag.py]"]
  node_router["Relevance routing<br/>[hybrid_rag.py]"]
  node_web["DuckDuckGo search<br/>[hybrid_rag.py]"]
  node_answer["Context answer generation<br/>[hybrid_rag.py]"]
  node_ollama{{"Ollama models"}}
  node_langfuse{{"Langfuse monitoring"}}
  node_basic_graph["Basic RAG graph<br/>[rag_graph.py]"]
  node_basic_answer["Direct RAG answer<br/>[rag_answer.py]"]
  node_query_tool["Direct chunk query<br/>[query_docs.py]"]
end

subgraph group_interfaces["User interfaces"]
  node_hybrid_cli["Hybrid CLI<br/>[hybrid_rag.py]"]
  node_api["Chat completions API<br/>[api.py]"]
end

node_user(("Question asker"))

node_pdfs -->|"extracts chunks"| node_ingest
node_ingest -->|"writes records"| node_chunk_json
node_chunk_json -->|"loads records"| node_index
node_index -->|"embeds documents"| node_ollama
node_index -->|"creates and fills"| node_milvus
node_user -->|"asks question"| node_hybrid_cli
node_user -->|"sends chat request"| node_api
node_api -->|"calls workflow"| node_hybrid_cli
node_hybrid_cli -->|"checks collection"| node_loader
node_loader -->|"checks and loads"| node_milvus
node_hybrid_cli -->|"starts graph"| node_retrieval
node_retrieval -->|"embeds query"| node_ollama
node_retrieval -->|"searches chunks"| node_milvus
node_retrieval -->|"provides context"| node_router
node_router -->|"routes low relevance"| node_web
node_router -->|"routes relevant docs"| node_answer
node_web -->|"provides results"| node_answer
node_answer -->|"generates response"| node_ollama
node_hybrid_cli -->|"sends traces"| node_langfuse
node_basic_graph -->|"searches chunks"| node_milvus
node_basic_graph -->|"embeds and answers"| node_ollama
node_basic_answer -->|"searches chunks"| node_milvus
node_basic_answer -->|"embeds and answers"| node_ollama
node_query_tool -->|"searches by role"| node_milvus
node_query_tool -->|"embeds query"| node_ollama
node_reset -->|"drops collections"| node_milvus
node_chunk_demo -->|"reads example PDF"| node_pdfs

click node_pdfs "https://github.com/renganathan077/hybrid-rag-system/tree/main/data/docs"
click node_ingest "https://github.com/renganathan077/hybrid-rag-system/blob/main/ingest_docs.py"
click node_chunk_demo "https://github.com/renganathan077/hybrid-rag-system/blob/main/chunk_text.py"
click node_index "https://github.com/renganathan077/hybrid-rag-system/blob/main/build_index.py"
click node_loader "https://github.com/renganathan077/hybrid-rag-system/blob/main/hybrid_rag.py"
click node_retrieval "https://github.com/renganathan077/hybrid-rag-system/blob/main/hybrid_rag.py"
click node_router "https://github.com/renganathan077/hybrid-rag-system/blob/main/hybrid_rag.py"
click node_web "https://github.com/renganathan077/hybrid-rag-system/blob/main/hybrid_rag.py"
click node_answer "https://github.com/renganathan077/hybrid-rag-system/blob/main/hybrid_rag.py"
click node_hybrid_cli "https://github.com/renganathan077/hybrid-rag-system/blob/main/hybrid_rag.py"
click node_api "https://github.com/renganathan077/hybrid-rag-system/blob/main/api.py"
click node_basic_graph "https://github.com/renganathan077/hybrid-rag-system/blob/main/rag_graph.py"
click node_basic_answer "https://github.com/renganathan077/hybrid-rag-system/blob/main/rag_answer.py"
click node_query_tool "https://github.com/renganathan077/hybrid-rag-system/blob/main/query_docs.py"
click node_reset "https://github.com/renganathan077/hybrid-rag-system/blob/main/reset_milvus.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_pdfs,node_ingest,node_chunk_demo,node_chunk_json toneBlue
class node_index,node_milvus,node_reset toneAmber
class node_loader,node_retrieval,node_router,node_web,node_answer,node_ollama,node_langfuse,node_basic_graph,node_basic_answer,node_query_tool toneMint
class node_hybrid_cli,node_api toneRose
class node_user toneIndigo
```

## Components

### Document preparation

- [Source PDFs](https://github.com/renganathan077/hybrid-rag-system/tree/main/data/docs): `data/docs`
- [PDF chunk extraction](https://github.com/renganathan077/hybrid-rag-system/blob/main/ingest_docs.py): `ingest_docs.py`
- [Chunking example](https://github.com/renganathan077/hybrid-rag-system/blob/main/chunk_text.py): `chunk_text.py`
- **Chunk records**

### Vector storage

- [Embedding and indexing](https://github.com/renganathan077/hybrid-rag-system/blob/main/build_index.py): `build_index.py`
- **Milvus collections**
- [Milvus reset utility](https://github.com/renganathan077/hybrid-rag-system/blob/main/reset_milvus.py): `reset_milvus.py`

### Hybrid answering

- [Collection readiness](https://github.com/renganathan077/hybrid-rag-system/blob/main/hybrid_rag.py): `hybrid_rag.py`
- [Role-filtered retrieval](https://github.com/renganathan077/hybrid-rag-system/blob/main/hybrid_rag.py): `hybrid_rag.py`
- [Relevance routing](https://github.com/renganathan077/hybrid-rag-system/blob/main/hybrid_rag.py): `hybrid_rag.py`
- [DuckDuckGo search](https://github.com/renganathan077/hybrid-rag-system/blob/main/hybrid_rag.py): `hybrid_rag.py`
- [Context answer generation](https://github.com/renganathan077/hybrid-rag-system/blob/main/hybrid_rag.py): `hybrid_rag.py`
- **Ollama models**
- **Langfuse monitoring**
- [Basic RAG graph](https://github.com/renganathan077/hybrid-rag-system/blob/main/rag_graph.py): `rag_graph.py`
- [Direct RAG answer](https://github.com/renganathan077/hybrid-rag-system/blob/main/rag_answer.py): `rag_answer.py`
- [Direct chunk query](https://github.com/renganathan077/hybrid-rag-system/blob/main/query_docs.py): `query_docs.py`

### User interfaces

- [Hybrid CLI](https://github.com/renganathan077/hybrid-rag-system/blob/main/hybrid_rag.py): `hybrid_rag.py`
- [Chat completions API](https://github.com/renganathan077/hybrid-rag-system/blob/main/api.py): `api.py`

### Other components

- **Question asker**

## Connections

- Source PDFs → PDF chunk extraction: extracts chunks (evidence: `ingest_docs.py`)
- PDF chunk extraction → Chunk records: writes records (evidence: `ingest_docs.py`)
- Chunk records → Embedding and indexing: loads records (evidence: `build_index.py`)
- Embedding and indexing → Ollama models: embeds documents (evidence: `build_index.py`)
- Embedding and indexing → Milvus collections: creates and fills (evidence: `build_index.py`)
- Question asker → Hybrid CLI: asks question (evidence: `hybrid_rag.py`)
- Question asker → Chat completions API: sends chat request (evidence: `README.md`)
- Chat completions API → Hybrid CLI: calls workflow (evidence: `api.py`)
- Hybrid CLI → Collection readiness: checks collection (evidence: `hybrid_rag.py`)
- Collection readiness → Milvus collections: checks and loads (evidence: `hybrid_rag.py`)
- Hybrid CLI → Role-filtered retrieval: starts graph (evidence: `hybrid_rag.py`)
- Role-filtered retrieval → Ollama models: embeds query (evidence: `hybrid_rag.py`)
- Role-filtered retrieval → Milvus collections: searches chunks (evidence: `hybrid_rag.py`)
- Role-filtered retrieval → Relevance routing: provides context (evidence: `hybrid_rag.py`)
- Relevance routing → DuckDuckGo search: routes low relevance (evidence: `hybrid_rag.py`)
- Relevance routing → Context answer generation: routes relevant docs (evidence: `hybrid_rag.py`)
- DuckDuckGo search → Context answer generation: provides results (evidence: `hybrid_rag.py`)
- Context answer generation → Ollama models: generates response (evidence: `hybrid_rag.py`)
- Hybrid CLI → Langfuse monitoring: sends traces (evidence: `hybrid_rag.py`)
- Basic RAG graph → Milvus collections: searches chunks (evidence: `rag_graph.py`)
- Basic RAG graph → Ollama models: embeds and answers (evidence: `rag_graph.py`)
- Direct RAG answer → Milvus collections: searches chunks (evidence: `rag_answer.py`)
- Direct RAG answer → Ollama models: embeds and answers (evidence: `rag_answer.py`)
- Direct chunk query → Milvus collections: searches by role (evidence: `query_docs.py`)
- Direct chunk query → Ollama models: embeds query (evidence: `query_docs.py`)
- Milvus reset utility → Milvus collections: drops collections (evidence: `reset_milvus.py`)
- Chunking example → Source PDFs: reads example PDF (evidence: `chunk_text.py`)
