# giripsr769/hybrid_rag architecture

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

- Interactive diagram: https://gitdiagram.com/giripsr769/hybrid_rag
- Repository: https://github.com/giripsr769/hybrid_rag

## Overview

This is a PDF-grounded hybrid RAG application: users upload a PDF, then ask questions through Streamlit and receive answers from a FastAPI backend. Ingestion extracts and separately chunks the PDF for FAISS and Neo4j; querying combines vector and graph evidence, uses conversational history to contextualize follow-ups, and checks input and answer grounding. DeepEval is exposed as an evaluation capability. The main orchestration and retrieval/service files were excerpted; some documented capabilities, including the alternate custom evaluator, have limited implementation evidence here.

Main entry points: [`backend/main.py`](https://github.com/giripsr769/hybrid_rag/blob/main/backend/main.py) (FastAPI API), [`backend/app/services/rag_service.py`](https://github.com/giripsr769/hybrid_rag/blob/main/backend/app/services/rag_service.py) (RAG Service), [`backend/app/ingestion/vector_indexer.py`](https://github.com/giripsr769/hybrid_rag/blob/main/backend/app/ingestion/vector_indexer.py) (Vector Indexer), [`backend/app/ingestion/graph_builder.py`](https://github.com/giripsr769/hybrid_rag/blob/main/backend/app/ingestion/graph_builder.py) (Graph Builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User Interface"]
  node_frontend["Streamlit UI<br/>[app.py]"]
end

subgraph group_api["API Orchestration"]
  node_api["FastAPI API<br/>[main.py]"]
  node_pdfstore["Uploaded PDFs<br/>[main.py]"]
end

subgraph group_ingest["PDF Ingestion"]
  node_pdf["PDF Loader<br/>[pdf_loader.py]"]
  node_chunker["Text Chunker<br/>[text_chunker.py]"]
  node_vectorindex["Vector Indexer<br/>[vector_indexer.py]"]
  node_faiss[("FAISS Index<br/>[vector_indexer.py]")]
  node_graphbuild["Graph Builder<br/>[graph_builder.py]"]
  node_neo4j[("Neo4j Graph<br/>[graph_builder.py]")]
end

subgraph group_retrieval["Hybrid Retrieval"]
  node_hybrid["Hybrid Retriever"]
  node_vectorretrieve["Vector Retriever"]
  node_graphretrieve["Graph Retriever<br/>[graph_retriever.py]"]
end

subgraph group_answer["Answering and Evaluation"]
  node_rag["RAG Service<br/>[rag_service.py]"]
  node_guardrails["Guardrail Service"]
  node_evaluator["RAG Evaluator<br/>[rag_evaluator.py]"]
  node_custom_eval["Custom Evaluator"]
end

node_user(("User"))
node_openai{{"OpenAI Models"}}

node_user -->|"asks or uploads"| node_frontend
node_frontend -->|"calls API"| node_api
node_api -->|"saves upload"| node_pdfstore
node_api -->|"loads PDF"| node_pdf
node_pdf -->|"provides documents"| node_chunker
node_api -->|"splits documents"| node_chunker
node_api -->|"indexes chunks"| node_vectorindex
node_vectorindex -->|"writes index"| node_faiss
node_api -->|"builds graph"| node_graphbuild
node_graphbuild -->|"writes graph"| node_neo4j
node_vectorindex -->|"embeds chunks"| node_openai
node_graphbuild -->|"extracts relations"| node_openai
node_api -->|"routes chat"| node_rag
node_rag -->|"validates and checks"| node_guardrails
node_rag -->|"retrieves evidence"| node_hybrid
node_hybrid -->|"retrieves vectors"| node_vectorretrieve
node_hybrid -->|"retrieves relations"| node_graphretrieve
node_vectorretrieve -->|"searches index"| node_faiss
node_graphretrieve -->|"queries graph"| node_neo4j
node_graphretrieve -->|"extracts entities"| node_openai
node_rag -->|"rewrites and answers"| node_openai
node_guardrails -->|"classifies and grounds"| node_openai
node_rag -.->|"returns answer"| node_frontend
node_api -->|"runs evaluation"| node_evaluator
node_evaluator -.->|"scores responses"| node_openai

click node_frontend "https://github.com/giripsr769/hybrid_rag/blob/main/frontend/app.py"
click node_api "https://github.com/giripsr769/hybrid_rag/blob/main/backend/main.py"
click node_pdfstore "https://github.com/giripsr769/hybrid_rag/blob/main/backend/main.py"
click node_pdf "https://github.com/giripsr769/hybrid_rag/blob/main/backend/app/ingestion/pdf_loader.py"
click node_chunker "https://github.com/giripsr769/hybrid_rag/blob/main/backend/app/ingestion/text_chunker.py"
click node_vectorindex "https://github.com/giripsr769/hybrid_rag/blob/main/backend/app/ingestion/vector_indexer.py"
click node_faiss "https://github.com/giripsr769/hybrid_rag/blob/main/backend/app/ingestion/vector_indexer.py"
click node_graphbuild "https://github.com/giripsr769/hybrid_rag/blob/main/backend/app/ingestion/graph_builder.py"
click node_neo4j "https://github.com/giripsr769/hybrid_rag/blob/main/backend/app/ingestion/graph_builder.py"
click node_hybrid "https://github.com/giripsr769/hybrid_rag/blob/main/backend/app/retrieval/hybrid_retriever.py"
click node_vectorretrieve "https://github.com/giripsr769/hybrid_rag/blob/main/backend/app/retrieval/vector_retriever.py"
click node_graphretrieve "https://github.com/giripsr769/hybrid_rag/blob/main/backend/app/retrieval/graph_retriever.py"
click node_rag "https://github.com/giripsr769/hybrid_rag/blob/main/backend/app/services/rag_service.py"
click node_guardrails "https://github.com/giripsr769/hybrid_rag/blob/main/backend/app/guardrails/guardrail_service.py"
click node_evaluator "https://github.com/giripsr769/hybrid_rag/blob/main/backend/app/evaluation/rag_evaluator.py"
click node_custom_eval "https://github.com/giripsr769/hybrid_rag/blob/main/backend/app/evaluation/custom_rag_evaluator.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_frontend,node_user toneBlue
class node_api,node_pdfstore toneAmber
class node_pdf,node_chunker,node_vectorindex,node_faiss,node_graphbuild,node_neo4j toneMint
class node_hybrid,node_vectorretrieve,node_graphretrieve toneRose
class node_rag,node_guardrails,node_evaluator,node_custom_eval,node_openai toneIndigo
```

## Components

### User Interface

- [Streamlit UI](https://github.com/giripsr769/hybrid_rag/blob/main/frontend/app.py): `frontend/app.py`

### API Orchestration

- [FastAPI API](https://github.com/giripsr769/hybrid_rag/blob/main/backend/main.py): `backend/main.py`
- [Uploaded PDFs](https://github.com/giripsr769/hybrid_rag/blob/main/backend/main.py): `backend/main.py`

### PDF Ingestion

- [PDF Loader](https://github.com/giripsr769/hybrid_rag/blob/main/backend/app/ingestion/pdf_loader.py): `backend/app/ingestion/pdf_loader.py`
- [Text Chunker](https://github.com/giripsr769/hybrid_rag/blob/main/backend/app/ingestion/text_chunker.py): `backend/app/ingestion/text_chunker.py`
- [Vector Indexer](https://github.com/giripsr769/hybrid_rag/blob/main/backend/app/ingestion/vector_indexer.py): `backend/app/ingestion/vector_indexer.py`
- [FAISS Index](https://github.com/giripsr769/hybrid_rag/blob/main/backend/app/ingestion/vector_indexer.py): `backend/app/ingestion/vector_indexer.py`
- [Graph Builder](https://github.com/giripsr769/hybrid_rag/blob/main/backend/app/ingestion/graph_builder.py): `backend/app/ingestion/graph_builder.py`
- [Neo4j Graph](https://github.com/giripsr769/hybrid_rag/blob/main/backend/app/ingestion/graph_builder.py): `backend/app/ingestion/graph_builder.py`

### Hybrid Retrieval

- [Hybrid Retriever](https://github.com/giripsr769/hybrid_rag/blob/main/backend/app/retrieval/hybrid_retriever.py): `backend/app/retrieval/hybrid_retriever.py`
- [Vector Retriever](https://github.com/giripsr769/hybrid_rag/blob/main/backend/app/retrieval/vector_retriever.py): `backend/app/retrieval/vector_retriever.py`
- [Graph Retriever](https://github.com/giripsr769/hybrid_rag/blob/main/backend/app/retrieval/graph_retriever.py): `backend/app/retrieval/graph_retriever.py`

### Answering and Evaluation

- [RAG Service](https://github.com/giripsr769/hybrid_rag/blob/main/backend/app/services/rag_service.py): `backend/app/services/rag_service.py`
- [Guardrail Service](https://github.com/giripsr769/hybrid_rag/blob/main/backend/app/guardrails/guardrail_service.py): `backend/app/guardrails/guardrail_service.py`
- [RAG Evaluator](https://github.com/giripsr769/hybrid_rag/blob/main/backend/app/evaluation/rag_evaluator.py): `backend/app/evaluation/rag_evaluator.py`
- [Custom Evaluator](https://github.com/giripsr769/hybrid_rag/blob/main/backend/app/evaluation/custom_rag_evaluator.py): `backend/app/evaluation/custom_rag_evaluator.py`

### Other components

- **User**
- **OpenAI Models**

## Connections

- User → Streamlit UI: asks or uploads (evidence: `README.md`)
- Streamlit UI → FastAPI API: calls API (evidence: `README.md`)
- FastAPI API → Uploaded PDFs: saves upload (evidence: `backend/main.py`)
- FastAPI API → PDF Loader: loads PDF (evidence: `backend/main.py`)
- PDF Loader → Text Chunker: provides documents (evidence: `README.md`)
- FastAPI API → Text Chunker: splits documents (evidence: `backend/main.py`)
- FastAPI API → Vector Indexer: indexes chunks (evidence: `backend/main.py`)
- Vector Indexer → FAISS Index: writes index (evidence: `backend/app/ingestion/vector_indexer.py`)
- FastAPI API → Graph Builder: builds graph (evidence: `backend/main.py`)
- Graph Builder → Neo4j Graph: writes graph (evidence: `backend/app/ingestion/graph_builder.py`)
- Vector Indexer → OpenAI Models: embeds chunks (evidence: `backend/app/ingestion/vector_indexer.py`)
- Graph Builder → OpenAI Models: extracts relations (evidence: `backend/app/ingestion/graph_builder.py`)
- FastAPI API → RAG Service: routes chat (evidence: `backend/main.py`)
- RAG Service → Guardrail Service: validates and checks (evidence: `backend/app/services/rag_service.py`)
- RAG Service → Hybrid Retriever: retrieves evidence (evidence: `backend/app/services/rag_service.py`)
- Hybrid Retriever → Vector Retriever: retrieves vectors (evidence: `backend/app/retrieval/hybrid_retriever.py`)
- Hybrid Retriever → Graph Retriever: retrieves relations (evidence: `backend/app/retrieval/hybrid_retriever.py`)
- Vector Retriever → FAISS Index: searches index (evidence: `backend/app/retrieval/vector_retriever.py`)
- Graph Retriever → Neo4j Graph: queries graph (evidence: `backend/app/retrieval/graph_retriever.py`)
- Graph Retriever → OpenAI Models: extracts entities (evidence: `backend/app/retrieval/graph_retriever.py`)
- RAG Service → OpenAI Models: rewrites and answers (evidence: `backend/app/services/rag_service.py`)
- Guardrail Service → OpenAI Models: classifies and grounds (evidence: `backend/app/guardrails/guardrail_service.py`)
- RAG Service → Streamlit UI: returns answer (evidence: `README.md`)
- FastAPI API → RAG Evaluator: runs evaluation (evidence: `backend/main.py`)
- RAG Evaluator → OpenAI Models: scores responses (evidence: `README.md`)
