# rohityadav483/swiggy-rag architecture

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

- Interactive diagram: https://gitdiagram.com/rohityadav483/swiggy-rag
- Repository: https://github.com/rohityadav483/swiggy-rag

## Overview

1. **What this repo is**
   - This is a fully local Retrieval-Augmented Generation system for a single document: `data/swiggy_report.pdf`.
   - The architecture is split into two clear phases: **offline ingestion/index building** and **online question answering**.

2. **Entry points**
   - `ingest.py` builds the retrieval indexes from the PDF.
   - `app.py` is the user-facing Streamlit app that handles questions and displays answers.
   - The rest of the logic lives under `src/` as reusable pipeline components.

3. **Document acquisition and extraction boundary**
   - `src/pdf_loader.py` is the first processing layer for the report.
   - It uses **PyMuPDF** for standard text pages and hands scanned pages off to `src/ocr_extractor.py`, which uses **pytesseract + Pillow**.
   - This creates a unified text stream from mixed PDF content types, which is important because the report likely contains both digital and scanned pages.

4. **Text normalization**
   - `src/text_cleaner.py` cleans extracted text before indexing.
   - This layer removes PDF/OCR noise such as whitespace issues, headers, and encoding artifacts so downstream chunking and retrieval operate on cleaner text.

5. **Chunking and document units**
   - `src/chunking.py` splits cleaned text into retrieval-sized chunks.
   - The README indicates chunking around 800 characters with overlap, so each chunk becomes the atomic unit for both vector search and lexical search.
   - Chunk metadata includes page references, which later support citations in answers.

6. **Offline indexing storage**
   - `src/embeddings.py` provides a local embedding model: **BAAI/bge-small-en**.
   - `src/vector_store.py` persists semantic embeddings in **ChromaDB** as the vector index.
   - The same chunk set is also used for keyword retrieval, likely stored as a BM25-ready corpus artifact for fast lexical lookup.

7. **Hybrid retrieval boundary**
   - `src/hybrid_retriever.py` combines two retrieval modes:
     - semantic search from ChromaDB
     - keyword search via **BM25**
   - The two result sets are merged and deduplicated, which improves recall on both paraphrased questions and exact-term queries.

8. **Relevance ranking**
   - `src/reranker.py` applies a cross-encoder reranker, specifically **cross-encoder/ms-marco-MiniLM-L-6-v2**.
   - This is the quality-control layer between retrieval and generation: it scores candidate chunks more precisely than embedding similarity or BM25 alone.
   - The output is a small top-k set of highly relevant context chunks.

9. **Answer generation pipeline**
   - `src/rag_pipeline.py` orchestrates the end-to-end query flow.
   - It compresses the retrieved context by deduplicating and trimming it, then sends it to a local LLM through **Ollama**.
   - The model named in the README is **gemma2:2b**, used with a strict prompt so responses stay grounded in the report.

10. **User-facing behavior**
   - `app.py` exposes the system as a Streamlit UI.
   - The app receives a question, calls the RAG pipeline, and returns an answer with page citations.
   - This means the UI is thin; most architectural complexity lives in the ingestion, retrieval, reranking, and generation layers.

11. **Runtime and infrastructure characteristics**
   - The whole system is intentionally local: no cloud vector DB, no hosted embeddings API, and no external LLM API.
   - The only operational dependency outside Python is **Ollama**, which must be running to serve the local model.
   - This makes the deployment model simple: one offline build step, then a local interactive app.

12. **Main data flow to diagram**
   - PDF → extraction/OCR → cleaning → chunking → embeddings + ChromaDB / BM25 artifact creation.
   - User question → hybrid retrieval → reranking → context compression → local LLM → cited answer.
   - The key boundaries to show are: **ingestion vs serving**, **semantic vs lexical retrieval**, and **retrieval vs generation**.

Main entry points: [`src/hybrid_retriever.py`](https://github.com/rohityadav483/swiggy-rag/blob/main/src/hybrid_retriever.py) (Hybrid retriever), [`src/pdf_loader.py`](https://github.com/rohityadav483/swiggy-rag/blob/main/src/pdf_loader.py) (PDF loader), [`src/chunking.py`](https://github.com/rohityadav483/swiggy-rag/blob/main/src/chunking.py) (Chunking), [`src/rag_pipeline.py`](https://github.com/rohityadav483/swiggy-rag/blob/main/src/rag_pipeline.py) (RAG pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Offline ingestion"]
  node_pdf["PDF report<br/>source document<br/>[swiggy_report.pdf]"]
  node_ingest_entry["Ingest entry<br/>build script<br/>[ingest.py]"]
  node_pdf_loader["PDF loader<br/>document loader<br/>[pdf_loader.py]"]
  node_ocr_extractor["OCR extractor<br/>scan text extraction<br/>[ocr_extractor.py]"]
  node_text_cleaner["Text cleaner<br/>normalization<br/>[text_cleaner.py]"]
  node_chunking["Chunking<br/>text splitter<br/>[chunking.py]"]
  node_embeddings["Embeddings<br/>local encoder<br/>[embeddings.py]"]
  node_vector_store[("Vector store<br/>Chroma index<br/>[vector_store.py]")]
  node_bm25_corpus[("BM25 corpus<br/>lexical index")]
end

subgraph group_serving["Online Q&A"]
  node_app["Streamlit app<br/>UI entry<br/>[app.py]"]
  node_rag_pipeline["RAG pipeline<br/>query orchestrator<br/>[rag_pipeline.py]"]
  node_hybrid_retriever["Hybrid retriever<br/>retrieval combiner"]
  node_reranker["Reranker<br/>cross-encoder<br/>[reranker.py]"]
  node_context_compress["Context compress<br/>prompt prep<br/>[rag_pipeline.py]"]
  node_ollama["Ollama LLM<br/>local model runtime"]
  node_answer["Cited answer<br/>response"]
end

node_pdf -->|"source"| node_pdf_loader
node_ingest_entry -->|"loads"| node_pdf_loader
node_pdf_loader -->|"scanned pages"| node_ocr_extractor
node_pdf_loader -->|"text pages"| node_text_cleaner
node_ocr_extractor -->|"raw OCR text"| node_text_cleaner
node_text_cleaner -->|"clean text"| node_chunking
node_chunking -->|"chunk text"| node_embeddings
node_chunking -->|"chunk corpus"| node_bm25_corpus
node_embeddings -->|"vectors"| node_vector_store
node_app -->|"question"| node_rag_pipeline
node_rag_pipeline -->|"retrieve"| node_hybrid_retriever
node_hybrid_retriever -->|"semantic search"| node_vector_store
node_hybrid_retriever -->|"keyword search"| node_bm25_corpus
node_hybrid_retriever -->|"candidates"| node_reranker
node_reranker -->|"top chunks"| node_context_compress
node_context_compress -->|"prompt"| node_ollama
node_ollama -->|"generation"| node_answer
node_rag_pipeline -->|"returns"| node_answer
node_answer -->|"display"| node_app

click node_pdf "https://github.com/rohityadav483/swiggy-rag/blob/main/data/swiggy_report.pdf"
click node_ingest_entry "https://github.com/rohityadav483/swiggy-rag/blob/main/ingest.py"
click node_pdf_loader "https://github.com/rohityadav483/swiggy-rag/blob/main/src/pdf_loader.py"
click node_ocr_extractor "https://github.com/rohityadav483/swiggy-rag/blob/main/src/ocr_extractor.py"
click node_text_cleaner "https://github.com/rohityadav483/swiggy-rag/blob/main/src/text_cleaner.py"
click node_chunking "https://github.com/rohityadav483/swiggy-rag/blob/main/src/chunking.py"
click node_embeddings "https://github.com/rohityadav483/swiggy-rag/blob/main/src/embeddings.py"
click node_vector_store "https://github.com/rohityadav483/swiggy-rag/blob/main/src/vector_store.py"
click node_app "https://github.com/rohityadav483/swiggy-rag/blob/main/app.py"
click node_rag_pipeline "https://github.com/rohityadav483/swiggy-rag/blob/main/src/rag_pipeline.py"
click node_hybrid_retriever "https://github.com/rohityadav483/swiggy-rag/blob/main/src/hybrid_retriever.py"
click node_reranker "https://github.com/rohityadav483/swiggy-rag/blob/main/src/reranker.py"
click node_context_compress "https://github.com/rohityadav483/swiggy-rag/blob/main/src/rag_pipeline.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_pdf,node_ingest_entry,node_pdf_loader,node_ocr_extractor,node_text_cleaner,node_chunking,node_embeddings,node_vector_store,node_bm25_corpus toneBlue
class node_app,node_rag_pipeline,node_hybrid_retriever,node_reranker,node_context_compress,node_ollama,node_answer toneAmber
```

## Components

### Offline ingestion

Builds cleaned chunks and local retrieval indexes from the PDF.

- [PDF report](https://github.com/rohityadav483/swiggy-rag/blob/main/data/swiggy_report.pdf): source document · Single local report used as the knowledge base. · `data/swiggy_report.pdf`
- [Ingest entry](https://github.com/rohityadav483/swiggy-rag/blob/main/ingest.py): build script · Offline entry point that builds indexes from the report. · `ingest.py`
- [PDF loader](https://github.com/rohityadav483/swiggy-rag/blob/main/src/pdf_loader.py): document loader · Reads the report and routes page content into text extraction. · `src/pdf_loader.py`
- [OCR extractor](https://github.com/rohityadav483/swiggy-rag/blob/main/src/ocr_extractor.py): scan text extraction · Uses OCR for scanned pages to produce text from images. · `src/ocr_extractor.py`
- [Text cleaner](https://github.com/rohityadav483/swiggy-rag/blob/main/src/text_cleaner.py): normalization · Removes PDF and OCR noise before indexing. · `src/text_cleaner.py`
- [Chunking](https://github.com/rohityadav483/swiggy-rag/blob/main/src/chunking.py): text splitter · Splits cleaned text into retrieval-sized chunks with page metadata. · `src/chunking.py`
- [Embeddings](https://github.com/rohityadav483/swiggy-rag/blob/main/src/embeddings.py): local encoder · Local BAAI/bge-small-en model for semantic vectors. · `src/embeddings.py`
- [Vector store](https://github.com/rohityadav483/swiggy-rag/blob/main/src/vector_store.py): Chroma index · Persists semantic chunk embeddings in ChromaDB. · `src/vector_store.py`
- **BM25 corpus**: lexical index · Keyword-searchable chunk corpus used for lexical retrieval.

### Online Q&A

Handles user questions, retrieval, reranking, and answer generation.

- [Streamlit app](https://github.com/rohityadav483/swiggy-rag/blob/main/app.py): UI entry · User-facing interface for asking questions and viewing cited answers. · `app.py`
- [RAG pipeline](https://github.com/rohityadav483/swiggy-rag/blob/main/src/rag_pipeline.py): query orchestrator · Coordinates retrieval, context preparation, and answer generation. · `src/rag_pipeline.py`
- [Hybrid retriever](https://github.com/rohityadav483/swiggy-rag/blob/main/src/hybrid_retriever.py): retrieval combiner · Merges semantic vector search with BM25 keyword search. · `src/hybrid_retriever.py`
- [Reranker](https://github.com/rohityadav483/swiggy-rag/blob/main/src/reranker.py): cross-encoder · Re-scores retrieved chunks with cross-encoder/ms-marco-MiniLM-L-6-v2. · `src/reranker.py`
- [Context compress](https://github.com/rohityadav483/swiggy-rag/blob/main/src/rag_pipeline.py): prompt prep · Deduplicates and trims evidence before it is sent to the model. · `src/rag_pipeline.py`
- **Ollama LLM**: local model runtime · Serves the local Gemma 2B model used for grounded answering.
- **Cited answer**: response · Final answer with page citations returned to the UI.

## Connections

- PDF report → PDF loader: source · The report is the only knowledge source.
- Ingest entry → PDF loader: loads · Offline build starts document ingestion.
- PDF loader → OCR extractor: scanned pages · Image-based pages are routed through OCR.
- PDF loader → Text cleaner: text pages · Extracted text flows into normalization.
- OCR extractor → Text cleaner: raw OCR text · OCR output is normalized with the rest of the document text.
- Text cleaner → Chunking: clean text · Normalized text is split into chunks.
- Chunking → Embeddings: chunk text · Chunks are encoded into semantic vectors.
- Chunking → BM25 corpus: chunk corpus · The same chunks form the lexical retrieval corpus.
- Embeddings → Vector store: vectors · Embedding outputs are persisted in ChromaDB.
- Streamlit app → RAG pipeline: question · The UI forwards user queries to the RAG pipeline.
- RAG pipeline → Hybrid retriever: retrieve · The pipeline first gathers candidate evidence.
- Hybrid retriever → Vector store: semantic search · Retrieves by vector similarity from ChromaDB.
- Hybrid retriever → BM25 corpus: keyword search · Retrieves exact-term matches from the lexical corpus.
- Hybrid retriever → Reranker: candidates · Merged retrieval candidates are sent for re-scoring.
- Reranker → Context compress: top chunks · Highest-scoring chunks become the working context.
- Context compress → Ollama LLM: prompt · Compressed context is passed to the local model.
- Ollama LLM → Cited answer: generation · The model produces the grounded response.
- RAG pipeline → Cited answer: returns · Pipeline returns the final cited answer to the UI.
- Cited answer → Streamlit app: display · The app renders the answer and citations.
