# alielbaha/rag-pipeline architecture

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

- Interactive diagram: https://gitdiagram.com/alielbaha/rag-pipeline
- Repository: https://github.com/alielbaha/rag-pipeline

## Overview

1. **What this repo is**
   - This is a **local end-to-end RAG application** centered on a single PDF corpus (`data/document1.pdf`).
   - The system follows the classic flow: **document ingestion → chunking/embedding → vector storage → semantic retrieval → prompt construction → LLM answer generation**.

2. **Main runtime boundaries**
   - The repo is organized into a small number of Python modules under `src/`, with two top-level entrypoints:
     - `app.py` for the **Streamlit UI**
     - `cli.py` for **command-line execution**
   - Shared logic lives in `src/`, while UI/entrypoint code stays thin and delegates to those modules.

3. **Ingestion and indexing subsystem**
   - `src/indexer.py` is the document-processing layer.
   - It likely handles extracting text from the PDF, splitting it into chunks, generating embeddings, and writing those vectors to the index.
   - The embedding model called out in the README is `sentence-transformers/all-MiniLM-L6-v2`.

4. **Persistent vector store**
   - The repository includes a local `chroma_db/` directory with `chroma.sqlite3`, which indicates **ChromaDB is used as the persistent vector database**.
   - This is the main durable storage boundary in the architecture: once indexed, the chunks and embeddings are reused across sessions instead of recomputed every time.

5. **Retrieval subsystem**
   - `src/retriever.py` is the semantic search layer.
   - It takes a user query, embeds it with the same embedding model family, and performs **top-k similarity search** against ChromaDB.
   - Its output is a ranked list of relevant text chunks, which becomes the context for generation.

6. **Generation / LLM subsystem**
   - `src/llm_handler.py` is responsible for calling the answer model and assembling the final response.
   - The README identifies the QA model as **Zephyr 7B Beta**.
   - Architecturally, this module is the boundary where retrieved context is turned into a prompt and sent to the LLM.

7. **RAG orchestration path**
   - The core serving flow is: **user question → retriever → retrieved chunks → llm_handler → final answer**.
   - This is the central data flow to capture in a diagram, because it connects the vector store and LLM into one pipeline.

8. **UI and interaction layer**
   - `app.py` provides a **Streamlit interface** for interactive use.
   - It likely wraps the same backend pipeline used by the CLI, but exposes it through a browser-based chat/query experience.
   - The `demo/` video suggests this is the main user-facing experience.

9. **CLI and non-UI entrypoint**
   - `cli.py` provides a headless way to run the same RAG logic.
   - In an architecture diagram, it should be shown as an alternate client path into the same indexing/retrieval/generation backend, not as a separate system.

10. **Evaluation subsystem**
   - `src/evaluator.py` is an auxiliary analysis component.
   - It is likely used for offline assessment of retrieval quality or answer quality, rather than being part of the live query path.
   - This makes it an experimental/supporting module, not a runtime dependency of the user-facing app.

11. **Shared utilities and configuration**
   - `src/utils.py` contains common helpers used across modules, likely for text handling, file operations, or prompt/chunk utilities.
   - `config.yaml` is the central configuration boundary for settings such as model names, chunk sizes, retrieval parameters, and database paths.

12. **Overall architecture to draw**
   - The repo is best diagrammed as a **single-machine RAG stack**:
     - source document(s) in `data/`
     - indexing pipeline in `src/indexer.py`
     - persistent Chroma vector store in `chroma_db/`
     - retrieval in `src/retriever.py`
     - answer generation in `src/llm_handler.py`
     - presentation via `app.py` or `cli.py`
     - evaluation via `src/evaluator.py`
   - There are no obvious external web services in the repo; the key infrastructure is local Python code plus local persistent storage.

Main entry points: [`src/retriever.py`](https://github.com/alielbaha/rag-pipeline/blob/main/src/retriever.py) (Retriever), [`src/llm_handler.py`](https://github.com/alielbaha/rag-pipeline/blob/main/src/llm_handler.py) (LLM handler), [`src/indexer.py`](https://github.com/alielbaha/rag-pipeline/blob/main/src/indexer.py) (Indexer), [`src/utils.py`](https://github.com/alielbaha/rag-pipeline/blob/main/src/utils.py) (Utils)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_app_py["Streamlit app<br/>ui<br/>[app.py]"]
  node_cli_py["CLI<br/>entrypoint<br/>[cli.py]"]
end

subgraph group_core["RAG core"]
  node_indexer_py["Indexer<br/>ingest<br/>[indexer.py]"]
  node_retriever_py["Retriever<br/>search<br/>[retriever.py]"]
  node_llm_handler_py["LLM handler<br/>generation<br/>[llm_handler.py]"]
end

subgraph group_store["Storage"]
  node_chroma_dir[("Chroma DB<br/>vector store")]
  node_chroma_sqlite[("Chroma SQLite<br/>database file<br/>[chroma.sqlite3]")]
end

subgraph group_support["Support"]
  node_evaluator_py["Evaluator<br/>analysis<br/>[evaluator.py]"]
  node_utils_py["Utils<br/>helpers<br/>[utils.py]"]
  node_config_yaml["Config<br/>settings<br/>[config.yaml]"]
  node_pdf_doc["Corpus PDF<br/>source document<br/>[document1.pdf]"]
end

node_app_py -->|"query"| node_retriever_py
node_cli_py -->|"query"| node_retriever_py
node_indexer_py -->|"reads"| node_pdf_doc
node_indexer_py -->|"uses"| node_config_yaml
node_indexer_py -->|"writes"| node_chroma_dir
node_chroma_dir -->|"persists"| node_chroma_sqlite
node_retriever_py -->|"searches"| node_chroma_dir
node_retriever_py -->|"uses"| node_config_yaml
node_retriever_py -->|"passes context"| node_llm_handler_py
node_llm_handler_py -->|"uses"| node_config_yaml
node_app_py -->|"answer"| node_llm_handler_py
node_cli_py -->|"answer"| node_llm_handler_py
node_evaluator_py -.->|"checks"| node_retriever_py
node_evaluator_py -.->|"checks"| node_llm_handler_py
node_utils_py -.->|"supports"| node_indexer_py
node_utils_py -.->|"supports"| node_retriever_py
node_utils_py -.->|"supports"| node_llm_handler_py

click node_app_py "https://github.com/alielbaha/rag-pipeline/blob/main/app.py"
click node_cli_py "https://github.com/alielbaha/rag-pipeline/blob/main/cli.py"
click node_indexer_py "https://github.com/alielbaha/rag-pipeline/blob/main/src/indexer.py"
click node_retriever_py "https://github.com/alielbaha/rag-pipeline/blob/main/src/retriever.py"
click node_llm_handler_py "https://github.com/alielbaha/rag-pipeline/blob/main/src/llm_handler.py"
click node_evaluator_py "https://github.com/alielbaha/rag-pipeline/blob/main/src/evaluator.py"
click node_utils_py "https://github.com/alielbaha/rag-pipeline/blob/main/src/utils.py"
click node_config_yaml "https://github.com/alielbaha/rag-pipeline/blob/main/config.yaml"
click node_pdf_doc "https://github.com/alielbaha/rag-pipeline/blob/main/data/document1.pdf"
click node_chroma_dir "https://github.com/alielbaha/rag-pipeline/tree/main/chroma_db"
click node_chroma_sqlite "https://github.com/alielbaha/rag-pipeline/blob/main/chroma_db/chroma.sqlite3"

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_app_py,node_cli_py toneBlue
class node_indexer_py,node_retriever_py,node_llm_handler_py toneAmber
class node_chroma_dir,node_chroma_sqlite toneMint
class node_evaluator_py,node_utils_py,node_config_yaml,node_pdf_doc toneRose
```

## Components

### Entry points

User-facing runtime entrypoints

- [Streamlit app](https://github.com/alielbaha/rag-pipeline/blob/main/app.py): ui · Interactive browser UI for asking questions · `app.py`
- [CLI](https://github.com/alielbaha/rag-pipeline/blob/main/cli.py): entrypoint · Headless command-line access to the same RAG flow · `cli.py`

### RAG core

Indexing, retrieval, and generation pipeline

- [Indexer](https://github.com/alielbaha/rag-pipeline/blob/main/src/indexer.py): ingest · Loads the PDF, chunks text, and builds embeddings/index entries · `src/indexer.py`
- [Retriever](https://github.com/alielbaha/rag-pipeline/blob/main/src/retriever.py): search · Embeds queries and runs similarity search over the vector store · `src/retriever.py`
- [LLM handler](https://github.com/alielbaha/rag-pipeline/blob/main/src/llm_handler.py): generation · Builds prompts from retrieved context and calls the answer model · `src/llm_handler.py`

### Storage

Persistent local data stores

- [Chroma DB](https://github.com/alielbaha/rag-pipeline/tree/main/chroma_db): vector store · Persistent local vector database for chunks and embeddings · `chroma_db`
- [Chroma SQLite](https://github.com/alielbaha/rag-pipeline/blob/main/chroma_db/chroma.sqlite3): database file · On-disk Chroma metadata and index storage · `chroma_db/chroma.sqlite3`

### Support

Shared config and offline tooling

- [Evaluator](https://github.com/alielbaha/rag-pipeline/blob/main/src/evaluator.py): analysis · Offline evaluation of retrieval or answer quality · `src/evaluator.py`
- [Utils](https://github.com/alielbaha/rag-pipeline/blob/main/src/utils.py): helpers · Shared helper functions used by the core modules · `src/utils.py`
- [Config](https://github.com/alielbaha/rag-pipeline/blob/main/config.yaml): settings · Central configuration for models, chunking, retrieval, and paths · `config.yaml`
- [Corpus PDF](https://github.com/alielbaha/rag-pipeline/blob/main/data/document1.pdf): source document · Primary knowledge source indexed by the pipeline · `data/document1.pdf`

## Connections

- Streamlit app → Retriever: query · Interactive questions are routed into semantic retrieval
- CLI → Retriever: query · CLI requests use the same retrieval path
- Indexer → Corpus PDF: reads · Document ingestion starts from the source PDF
- Indexer → Config: uses · Chunking and model settings come from config
- Indexer → Chroma DB: writes · Indexed chunks and embeddings are persisted locally
- Chroma DB → Chroma SQLite: persists · Chroma uses the local SQLite backing store
- Retriever → Chroma DB: searches · Similarity search runs against the persisted vector store
- Retriever → Config: uses · Retrieval parameters and embedding settings are configured centrally
- Retriever → LLM handler: passes context · Ranked chunks become prompt context for generation
- LLM handler → Config: uses · Model and prompt settings are driven by config
- Streamlit app → LLM handler: answer · The UI surfaces generated responses to the user
- CLI → LLM handler: answer · The CLI prints generated responses to stdout
- Evaluator → Retriever: checks · Offline evaluation can inspect retrieval behavior
- Evaluator → LLM handler: checks · Offline evaluation can also assess generated answers
- Utils → Indexer: supports · Shared helpers are reused during ingestion
- Utils → Retriever: supports · Shared helpers are reused during retrieval
- Utils → LLM handler: supports · Shared helpers are reused during prompt/response handling