# b1a-z3/rag_chatbot architecture

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

- Interactive diagram: https://gitdiagram.com/b1a-z3/rag_chatbot
- Repository: https://github.com/b1a-z3/rag_chatbot

## Overview

This is a local documentation RAG assistant. Documents are loaded and chunked, embedded into a persistent Chroma index, then user questions retrieve relevant chunks for a locally hosted Ollama model; the Streamlit UI presents answers, citations, and per-query metrics. The graph also shows the README-documented ingestion stages and evaluation capability. Evaluation is ancillary to the user workflow. Source excerpts support the shown calls; the underlying Chroma and Ollama services are external dependencies.

Main entry points: [`src/rag.py`](https://github.com/b1a-z3/rag_chatbot/blob/main/src/rag.py) (Answer orchestrator), [`eval/evaluate.py`](https://github.com/b1a-z3/rag_chatbot/blob/main/eval/evaluate.py) (Retrieval and answer evaluator), [`src/ingest.py`](https://github.com/b1a-z3/rag_chatbot/blob/main/src/ingest.py) (Document loader), [`src/app.py`](https://github.com/b1a-z3/rag_chatbot/blob/main/src/app.py) (Streamlit chat)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Document indexing"]
  node_loader["Document loader<br/>[ingest.py]"]
  node_chunker["Text chunker<br/>[ingest.py]"]
  node_embedindex["Embed and index<br/>[ingest.py]"]
  node_vectorstore[("Persistent vector store")]
end

subgraph group_answering["Question answering"]
  node_rag["Answer orchestrator<br/>[rag.py]"]
  node_retrieval["Chunk retrieval<br/>[rag.py]"]
  node_prompt["Context prompt<br/>[rag.py]"]
  node_metrics["Answer citations and metrics<br/>[rag.py]"]
end

subgraph group_interface["User interface"]
  node_ui["Streamlit chat<br/>[app.py]"]
end

subgraph group_evaluation["Quality evaluation"]
  node_testset["Hand-labeled Q&amp;A<br/>[qa_testset.json]"]
  node_evaluator["Retrieval and answer evaluator<br/>[evaluate.py]"]
end

node_user(("Documentation user"))
node_docs["PDF / Markdown docs"]
node_ollama{{"Ollama LLM"}}

node_docs -->|"loads"| node_loader
node_loader -->|"chunks text"| node_chunker
node_chunker -->|"embeds chunks"| node_embedindex
node_embedindex -->|"writes index"| node_vectorstore
node_user -->|"asks question"| node_ui
node_ui -->|"calls"| node_rag
node_rag -->|"retrieves chunks"| node_retrieval
node_retrieval -->|"queries"| node_vectorstore
node_rag -->|"builds context"| node_prompt
node_rag -->|"generates answer"| node_ollama
node_rag -->|"returns citations and metrics"| node_metrics
node_rag -->|"retrieves for evaluation"| node_retrieval
node_evaluator -->|"loads cases"| node_testset
node_evaluator -->|"evaluates answers"| node_rag

click node_loader "https://github.com/b1a-z3/rag_chatbot/blob/main/src/ingest.py"
click node_chunker "https://github.com/b1a-z3/rag_chatbot/blob/main/src/ingest.py"
click node_embedindex "https://github.com/b1a-z3/rag_chatbot/blob/main/src/ingest.py"
click node_vectorstore "https://github.com/b1a-z3/rag_chatbot/tree/main/chroma_db"
click node_ui "https://github.com/b1a-z3/rag_chatbot/blob/main/src/app.py"
click node_rag "https://github.com/b1a-z3/rag_chatbot/blob/main/src/rag.py"
click node_retrieval "https://github.com/b1a-z3/rag_chatbot/blob/main/src/rag.py"
click node_prompt "https://github.com/b1a-z3/rag_chatbot/blob/main/src/rag.py"
click node_metrics "https://github.com/b1a-z3/rag_chatbot/blob/main/src/rag.py"
click node_testset "https://github.com/b1a-z3/rag_chatbot/blob/main/eval/qa_testset.json"
click node_evaluator "https://github.com/b1a-z3/rag_chatbot/blob/main/eval/evaluate.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_loader,node_chunker,node_embedindex,node_vectorstore,node_user toneBlue
class node_rag,node_retrieval,node_prompt,node_metrics toneAmber
class node_ui toneMint
class node_testset,node_evaluator toneRose
class node_docs,node_ollama toneIndigo
```

## Components

### Document indexing

- [Document loader](https://github.com/b1a-z3/rag_chatbot/blob/main/src/ingest.py): `src/ingest.py`
- [Text chunker](https://github.com/b1a-z3/rag_chatbot/blob/main/src/ingest.py): `src/ingest.py`
- [Embed and index](https://github.com/b1a-z3/rag_chatbot/blob/main/src/ingest.py): `src/ingest.py`
- [Persistent vector store](https://github.com/b1a-z3/rag_chatbot/tree/main/chroma_db): `chroma_db`

### Question answering

- [Answer orchestrator](https://github.com/b1a-z3/rag_chatbot/blob/main/src/rag.py): `src/rag.py`
- [Chunk retrieval](https://github.com/b1a-z3/rag_chatbot/blob/main/src/rag.py): `src/rag.py`
- [Context prompt](https://github.com/b1a-z3/rag_chatbot/blob/main/src/rag.py): `src/rag.py`
- [Answer citations and metrics](https://github.com/b1a-z3/rag_chatbot/blob/main/src/rag.py): `src/rag.py`

### User interface

- [Streamlit chat](https://github.com/b1a-z3/rag_chatbot/blob/main/src/app.py): `src/app.py`

### Quality evaluation

- [Hand-labeled Q&A](https://github.com/b1a-z3/rag_chatbot/blob/main/eval/qa_testset.json): `eval/qa_testset.json`
- [Retrieval and answer evaluator](https://github.com/b1a-z3/rag_chatbot/blob/main/eval/evaluate.py): `eval/evaluate.py`

### Other components

- **Documentation user**
- **PDF / Markdown docs**
- **Ollama LLM**

## Connections

- PDF / Markdown docs → Document loader: loads (evidence: `src/ingest.py`)
- Document loader → Text chunker: chunks text (evidence: `src/ingest.py`)
- Text chunker → Embed and index: embeds chunks (evidence: `src/ingest.py`)
- Embed and index → Persistent vector store: writes index (evidence: `src/ingest.py`)
- Documentation user → Streamlit chat: asks question (evidence: `src/app.py`)
- Streamlit chat → Answer orchestrator: calls (evidence: `src/app.py`)
- Answer orchestrator → Chunk retrieval: retrieves chunks (evidence: `src/rag.py`)
- Chunk retrieval → Persistent vector store: queries (evidence: `src/rag.py`)
- Answer orchestrator → Context prompt: builds context (evidence: `src/rag.py`)
- Answer orchestrator → Ollama LLM: generates answer (evidence: `src/rag.py`)
- Answer orchestrator → Answer citations and metrics: returns citations and metrics (evidence: `src/rag.py`)
- Answer orchestrator → Chunk retrieval: retrieves for evaluation (evidence: `eval/evaluate.py`)
- Retrieval and answer evaluator → Hand-labeled Q&A: loads cases (evidence: `eval/evaluate.py`)
- Retrieval and answer evaluator → Answer orchestrator: evaluates answers (evidence: `eval/evaluate.py`)
