# nampham13/rag architecture

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

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

## Overview

This repository implements a PDF-focused retrieval-augmented generation system, with a Streamlit chat interface and supporting evaluation tools. Its documented document workflow extracts and normalizes PDF content, chunks it, embeds chunks, and stores searchable FAISS indexes with metadata and summaries; queries retrieve and may rerank results before chat generation. The graph also preserves query routing, verification, and evaluation capabilities. Some source was unsampled, so uncertain internal connections are omitted or marked dashed.

Main entry points: [`pipeline/rag_pipeline.py`](https://github.com/nampham13/rag/blob/main/pipeline/rag_pipeline.py) (RAG pipeline), [`pipeline/pipeline_qa.py`](https://github.com/nampham13/rag/blob/main/pipeline/pipeline_qa.py) (Retrieval service), [`llm/LLM_FE.py`](https://github.com/nampham13/rag/blob/main/llm/LLM_FE.py) (Chat UI), [`loaders/pdf_loader.py`](https://github.com/nampham13/rag/blob/main/loaders/pdf_loader.py) (PDF loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Document ingestion"]
  node_pdf_loader["PDF loader<br/>[pdf_loader.py]"]
  node_document_models["Document models<br/>[document.py]"]
  node_block_model["Block normalization<br/>[block.py]"]
  node_chunking["Hybrid chunking<br/>[hybrid_chunker.py]"]
end

subgraph group_retrieval["Retrieval pipeline"]
  node_rag["RAG pipeline<br/>[rag_pipeline.py]"]
  node_vector_store[("FAISS vector store<br/>[vector_store.py]")]
  node_summary["Summary generator"]
  node_retriever["Vector retriever<br/>[retriever.py]"]
  node_qa["Retrieval service<br/>[pipeline_qa.py]"]
  node_query_router["Query router<br/>[query_router.py]"]
  node_query_expander["Query expander<br/>[query_expander.py]"]
  node_verifier["Chunk verifier<br/>[chunk_verifier.py]"]
end

subgraph group_models["Model providers"]
  node_embed_factory["Embedder factory"]
  node_ollama_gemma["Gemma embedder<br/>[gemma_embedder.py]"]
  node_ollama_bge["BGE-M3 embedder<br/>[bge3_embedder.py]"]
  node_reranker_factory["Reranker factory"]
  node_reranker["Reranker providers<br/>[bge_reranker.py]"]
end

subgraph group_experience["Chat experience"]
  node_chat_ui["Chat UI<br/>[LLM_FE.py]"]
  node_chat_handler["Chat formatting<br/>[chat_handler.py]"]
  node_llm_api["LLM API client<br/>[LLM_API.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_evaluator["Evaluation runner<br/>[evaluator.py]"]
  node_ground_truth["Ground truth<br/>[ground_truth.py]"]
  node_metrics["Evaluation metrics<br/>[base_metric.py]"]
  node_dataset["Evaluation datasets<br/>[dataset_loader.py]"]
end

node_user(("User"))
node_pdfs["PDF documents"]
node_llm_service["LLM service"]

node_user -->|"asks"| node_chat_ui
node_chat_ui -->|"retrieves through"| node_qa
node_chat_ui -->|"formats messages"| node_chat_handler
node_chat_ui -->|"calls"| node_llm_api
node_llm_api -.->|"requests completion"| node_llm_service
node_pdfs -->|"loads"| node_pdf_loader
node_rag -->|"loads PDFs"| node_pdf_loader
node_pdf_loader -->|"creates documents"| node_document_models
node_pdf_loader -->|"creates blocks"| node_block_model
node_rag -->|"chunks documents"| node_chunking
node_chunking -->|"consumes documents"| node_document_models
node_rag -->|"creates embedder"| node_embed_factory
node_embed_factory -->|"creates"| node_ollama_gemma
node_embed_factory -->|"creates"| node_ollama_bge
node_rag -->|"stores vectors"| node_vector_store
node_rag -->|"generates summaries"| node_summary
node_rag -->|"uses for search"| node_retriever
node_qa -->|"delegates retrieval"| node_rag
node_qa -->|"delegates reranking"| node_rag
node_rag -->|"creates rerankers"| node_reranker_factory
node_reranker_factory -->|"creates provider"| node_reranker
node_qa -.->|"routes queries"| node_query_router
node_qa -.->|"may expand queries"| node_query_expander
node_rag -->|"uses verification"| node_verifier
node_dataset -.->|"supplies cases"| node_evaluator
node_ground_truth -->|"provides relevance labels"| node_evaluator
node_evaluator -->|"runs metrics"| node_metrics
node_evaluator -.->|"evaluates answers"| node_qa

click node_pdf_loader "https://github.com/nampham13/rag/blob/main/loaders/pdf_loader.py"
click node_document_models "https://github.com/nampham13/rag/blob/main/loaders/model/document.py"
click node_block_model "https://github.com/nampham13/rag/blob/main/loaders/model/block.py"
click node_chunking "https://github.com/nampham13/rag/blob/main/chunkers/hybrid_chunker.py"
click node_rag "https://github.com/nampham13/rag/blob/main/pipeline/rag_pipeline.py"
click node_embed_factory "https://github.com/nampham13/rag/blob/main/embedders/embedder_factory.py"
click node_ollama_gemma "https://github.com/nampham13/rag/blob/main/embedders/providers/ollama/gemma_embedder.py"
click node_ollama_bge "https://github.com/nampham13/rag/blob/main/embedders/providers/ollama/bge3_embedder.py"
click node_vector_store "https://github.com/nampham13/rag/blob/main/pipeline/vector_store.py"
click node_summary "https://github.com/nampham13/rag/blob/main/pipeline/summary_generator.py"
click node_retriever "https://github.com/nampham13/rag/blob/main/pipeline/retriever.py"
click node_qa "https://github.com/nampham13/rag/blob/main/pipeline/pipeline_qa.py"
click node_query_router "https://github.com/nampham13/rag/blob/main/pipeline/query_router.py"
click node_query_expander "https://github.com/nampham13/rag/blob/main/pipeline/query_expander.py"
click node_verifier "https://github.com/nampham13/rag/blob/main/pipeline/chunk_verifier.py"
click node_reranker_factory "https://github.com/nampham13/rag/blob/main/rerankers/reranker_factory.py"
click node_reranker "https://github.com/nampham13/rag/blob/main/rerankers/providers/bge_reranker.py"
click node_chat_ui "https://github.com/nampham13/rag/blob/main/llm/LLM_FE.py"
click node_chat_handler "https://github.com/nampham13/rag/blob/main/llm/chat_handler.py"
click node_llm_api "https://github.com/nampham13/rag/blob/main/llm/LLM_API.py"
click node_evaluator "https://github.com/nampham13/rag/blob/main/evaluate/evaluator.py"
click node_ground_truth "https://github.com/nampham13/rag/blob/main/evaluate/model/ground_truth.py"
click node_metrics "https://github.com/nampham13/rag/blob/main/evaluate/metrics/base_metric.py"
click node_dataset "https://github.com/nampham13/rag/blob/main/evaluate/dataset_loader.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_loader,node_document_models,node_block_model,node_chunking,node_user toneBlue
class node_rag,node_vector_store,node_summary,node_retriever,node_qa,node_query_router,node_query_expander,node_verifier toneAmber
class node_embed_factory,node_ollama_gemma,node_ollama_bge,node_reranker_factory,node_reranker toneMint
class node_chat_ui,node_chat_handler,node_llm_api toneRose
class node_evaluator,node_ground_truth,node_metrics,node_dataset,node_pdfs,node_llm_service toneIndigo
```

## Components

### Document ingestion

- [PDF loader](https://github.com/nampham13/rag/blob/main/loaders/pdf_loader.py): `loaders/pdf_loader.py`
- [Document models](https://github.com/nampham13/rag/blob/main/loaders/model/document.py): `loaders/model/document.py`
- [Block normalization](https://github.com/nampham13/rag/blob/main/loaders/model/block.py): `loaders/model/block.py`
- [Hybrid chunking](https://github.com/nampham13/rag/blob/main/chunkers/hybrid_chunker.py): `chunkers/hybrid_chunker.py`

### Retrieval pipeline

- [RAG pipeline](https://github.com/nampham13/rag/blob/main/pipeline/rag_pipeline.py): `pipeline/rag_pipeline.py`
- [FAISS vector store](https://github.com/nampham13/rag/blob/main/pipeline/vector_store.py): `pipeline/vector_store.py`
- [Summary generator](https://github.com/nampham13/rag/blob/main/pipeline/summary_generator.py): `pipeline/summary_generator.py`
- [Vector retriever](https://github.com/nampham13/rag/blob/main/pipeline/retriever.py): `pipeline/retriever.py`
- [Retrieval service](https://github.com/nampham13/rag/blob/main/pipeline/pipeline_qa.py): `pipeline/pipeline_qa.py`
- [Query router](https://github.com/nampham13/rag/blob/main/pipeline/query_router.py): `pipeline/query_router.py`
- [Query expander](https://github.com/nampham13/rag/blob/main/pipeline/query_expander.py): `pipeline/query_expander.py`
- [Chunk verifier](https://github.com/nampham13/rag/blob/main/pipeline/chunk_verifier.py): `pipeline/chunk_verifier.py`

### Model providers

- [Embedder factory](https://github.com/nampham13/rag/blob/main/embedders/embedder_factory.py): `embedders/embedder_factory.py`
- [Gemma embedder](https://github.com/nampham13/rag/blob/main/embedders/providers/ollama/gemma_embedder.py): `embedders/providers/ollama/gemma_embedder.py`
- [BGE-M3 embedder](https://github.com/nampham13/rag/blob/main/embedders/providers/ollama/bge3_embedder.py): `embedders/providers/ollama/bge3_embedder.py`
- [Reranker factory](https://github.com/nampham13/rag/blob/main/rerankers/reranker_factory.py): `rerankers/reranker_factory.py`
- [Reranker providers](https://github.com/nampham13/rag/blob/main/rerankers/providers/bge_reranker.py): `rerankers/providers/bge_reranker.py`

### Chat experience

- [Chat UI](https://github.com/nampham13/rag/blob/main/llm/LLM_FE.py): `llm/LLM_FE.py`
- [Chat formatting](https://github.com/nampham13/rag/blob/main/llm/chat_handler.py): `llm/chat_handler.py`
- [LLM API client](https://github.com/nampham13/rag/blob/main/llm/LLM_API.py): `llm/LLM_API.py`

### Evaluation

- [Evaluation runner](https://github.com/nampham13/rag/blob/main/evaluate/evaluator.py): `evaluate/evaluator.py`
- [Ground truth](https://github.com/nampham13/rag/blob/main/evaluate/model/ground_truth.py): `evaluate/model/ground_truth.py`
- [Evaluation metrics](https://github.com/nampham13/rag/blob/main/evaluate/metrics/base_metric.py): `evaluate/metrics/base_metric.py`
- [Evaluation datasets](https://github.com/nampham13/rag/blob/main/evaluate/dataset_loader.py): `evaluate/dataset_loader.py`

### Other components

- **User**
- **PDF documents**
- **LLM service**

## Connections

- User → Chat UI: asks (evidence: `llm/LLM_FE.py`)
- Chat UI → Retrieval service: retrieves through (evidence: `llm/LLM_FE.py`)
- Chat UI → Chat formatting: formats messages (evidence: `llm/LLM_FE.py`)
- Chat UI → LLM API client: calls (evidence: `llm/LLM_FE.py`)
- LLM API client → LLM service: requests completion
- PDF documents → PDF loader: loads (evidence: `README.md`)
- RAG pipeline → PDF loader: loads PDFs (evidence: `pipeline/rag_pipeline.py`)
- PDF loader → Document models: creates documents (evidence: `loaders/pdf_loader.py`)
- PDF loader → Block normalization: creates blocks (evidence: `loaders/pdf_loader.py`)
- RAG pipeline → Hybrid chunking: chunks documents (evidence: `pipeline/rag_pipeline.py`)
- Hybrid chunking → Document models: consumes documents (evidence: `chunkers/hybrid_chunker.py`)
- RAG pipeline → Embedder factory: creates embedder (evidence: `pipeline/rag_pipeline.py`)
- Embedder factory → Gemma embedder: creates (evidence: `embedders/embedder_factory.py`)
- Embedder factory → BGE-M3 embedder: creates (evidence: `embedders/embedder_factory.py`)
- RAG pipeline → FAISS vector store: stores vectors (evidence: `pipeline/rag_pipeline.py`)
- RAG pipeline → Summary generator: generates summaries (evidence: `pipeline/rag_pipeline.py`)
- RAG pipeline → Vector retriever: uses for search (evidence: `pipeline/rag_pipeline.py`)
- Retrieval service → RAG pipeline: delegates retrieval (evidence: `pipeline/pipeline_qa.py`)
- Retrieval service → RAG pipeline: delegates reranking (evidence: `pipeline/pipeline_qa.py`)
- RAG pipeline → Reranker factory: creates rerankers (evidence: `pipeline/rag_pipeline.py`)
- Reranker factory → Reranker providers: creates provider (evidence: `rerankers/reranker_factory.py`)
- Retrieval service → Query router: routes queries (evidence: `pipeline/pipeline_qa.py`)
- Retrieval service → Query expander: may expand queries
- RAG pipeline → Chunk verifier: uses verification (evidence: `pipeline/rag_pipeline.py`)
- Evaluation datasets → Evaluation runner: supplies cases
- Ground truth → Evaluation runner: provides relevance labels (evidence: `evaluate/evaluator.py`)
- Evaluation runner → Evaluation metrics: runs metrics (evidence: `evaluate/evaluator.py`)
- Evaluation runner → Retrieval service: evaluates answers
