# ikramelhattab/rag_chatbot architecture

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

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

## Overview

This repository is a document-grounded question-answering chatbot, with OpenAI-generated answers in its primary version and a local, retrieval-only alternative. The main workflow accepts PDF/TXT documents through the web or CLI, loads and chunks them, indexes chunks in persistent Chroma storage, then retrieves relevant passages to answer questions and expose sources. The local web app uses free embeddings and returns matching context without generation. The README documents both interfaces and source attribution; sampled code confirms their distinct wiring.

Main entry points: [`rag_chain.py`](https://github.com/ikramelhattab/rag_chatbot/blob/main/rag_chain.py) (RAG chain), [`document_processor.py`](https://github.com/ikramelhattab/rag_chatbot/blob/main/document_processor.py) (Document processor), [`app.py`](https://github.com/ikramelhattab/rag_chatbot/blob/main/app.py) (Web chatbot), [`cli_chat.py`](https://github.com/ikramelhattab/rag_chatbot/blob/main/cli_chat.py) (CLI chatbot)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_web["Web chatbot<br/>[app.py]"]
  node_cli["CLI chatbot<br/>[cli_chat.py]"]
  node_local_web["Local web chatbot<br/>[app_local.py]"]
end

subgraph group_ingestion["Document ingestion"]
  node_processor["Document processor"]
  node_loaders["PDF/TXT loaders"]
  node_chunker["Chunk splitter"]
end

subgraph group_answering["Retrieval and answering"]
  node_rag["RAG chain<br/>[rag_chain.py]"]
  node_retriever["Retriever<br/>[vector_store.py]"]
  node_context_search["Context search<br/>[app_local.py]"]
end

subgraph group_storage["Index and storage"]
  node_standard_store["Vector store<br/>[vector_store.py]"]
  node_local_store["Free vector store"]
  node_chroma[("Chroma database")]
  node_standard_embeddings["Embedding model<br/>[vector_store.py]"]
  node_free_embeddings["Local embeddings"]
end

node_user(("User"))
node_documents["PDF/TXT documents"]
node_openai["OpenAI API"]

node_user -->|"uploads and asks"| node_web
node_user -->|"provides path and asks"| node_cli
node_user -->|"uploads and asks"| node_local_web
node_documents -->|"loads from path"| node_processor
node_web -->|"processes uploads"| node_processor
node_cli -->|"processes path"| node_processor
node_local_web -->|"processes uploads"| node_processor
node_processor -->|"loads files"| node_loaders
node_processor -->|"splits documents"| node_chunker
node_web -->|"indexes chunks"| node_standard_store
node_cli -->|"indexes chunks"| node_standard_store
node_local_web -->|"indexes chunks"| node_local_store
node_standard_store -->|"embeds chunks"| node_standard_embeddings
node_local_store -->|"embeds chunks"| node_free_embeddings
node_standard_store -->|"persists and loads"| node_chroma
node_local_store -->|"persists and loads"| node_chroma
node_web -->|"queries"| node_rag
node_cli -->|"queries"| node_rag
node_rag -->|"sets up and queries"| node_retriever
node_retriever -->|"searches chunks"| node_standard_store
node_rag -->|"generates answer"| node_openai
node_rag -->|"returns answer and sources"| node_web
node_rag -->|"returns answer and sources"| node_cli
node_local_web -->|"searches question"| node_context_search
node_context_search -->|"requests similar passages"| node_local_store
node_local_store -->|"returns passages"| node_context_search
node_context_search -->|"returns context"| node_local_web

click node_web "https://github.com/ikramelhattab/rag_chatbot/blob/main/app.py"
click node_cli "https://github.com/ikramelhattab/rag_chatbot/blob/main/cli_chat.py"
click node_local_web "https://github.com/ikramelhattab/rag_chatbot/blob/main/app_local.py"
click node_documents "https://github.com/ikramelhattab/rag_chatbot/tree/main/documents"
click node_processor "https://github.com/ikramelhattab/rag_chatbot/blob/main/document_processor.py"
click node_loaders "https://github.com/ikramelhattab/rag_chatbot/blob/main/document_processor.py"
click node_chunker "https://github.com/ikramelhattab/rag_chatbot/blob/main/document_processor.py"
click node_standard_store "https://github.com/ikramelhattab/rag_chatbot/blob/main/vector_store.py"
click node_local_store "https://github.com/ikramelhattab/rag_chatbot/blob/main/vector_store_completely_free.py"
click node_chroma "https://github.com/ikramelhattab/rag_chatbot/tree/main/chroma_db"
click node_standard_embeddings "https://github.com/ikramelhattab/rag_chatbot/blob/main/vector_store.py"
click node_free_embeddings "https://github.com/ikramelhattab/rag_chatbot/blob/main/vector_store_completely_free.py"
click node_rag "https://github.com/ikramelhattab/rag_chatbot/blob/main/rag_chain.py"
click node_retriever "https://github.com/ikramelhattab/rag_chatbot/blob/main/vector_store.py"
click node_context_search "https://github.com/ikramelhattab/rag_chatbot/blob/main/app_local.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_web,node_cli,node_local_web,node_user toneBlue
class node_processor,node_loaders,node_chunker toneAmber
class node_rag,node_retriever,node_context_search,node_openai toneMint
class node_standard_store,node_local_store,node_chroma,node_standard_embeddings,node_free_embeddings toneRose
class node_documents toneTeal
```

## Components

### User interfaces

- [Web chatbot](https://github.com/ikramelhattab/rag_chatbot/blob/main/app.py): `app.py`
- [CLI chatbot](https://github.com/ikramelhattab/rag_chatbot/blob/main/cli_chat.py): `cli_chat.py`
- [Local web chatbot](https://github.com/ikramelhattab/rag_chatbot/blob/main/app_local.py): `app_local.py`

### Document ingestion

- [Document processor](https://github.com/ikramelhattab/rag_chatbot/blob/main/document_processor.py): `document_processor.py`
- [PDF/TXT loaders](https://github.com/ikramelhattab/rag_chatbot/blob/main/document_processor.py): `document_processor.py`
- [Chunk splitter](https://github.com/ikramelhattab/rag_chatbot/blob/main/document_processor.py): `document_processor.py`

### Retrieval and answering

- [RAG chain](https://github.com/ikramelhattab/rag_chatbot/blob/main/rag_chain.py): `rag_chain.py`
- [Retriever](https://github.com/ikramelhattab/rag_chatbot/blob/main/vector_store.py): `vector_store.py`
- [Context search](https://github.com/ikramelhattab/rag_chatbot/blob/main/app_local.py): `app_local.py`

### Index and storage

- [Vector store](https://github.com/ikramelhattab/rag_chatbot/blob/main/vector_store.py): `vector_store.py`
- [Free vector store](https://github.com/ikramelhattab/rag_chatbot/blob/main/vector_store_completely_free.py): `vector_store_completely_free.py`
- [Chroma database](https://github.com/ikramelhattab/rag_chatbot/tree/main/chroma_db): `chroma_db`
- [Embedding model](https://github.com/ikramelhattab/rag_chatbot/blob/main/vector_store.py): `vector_store.py`
- [Local embeddings](https://github.com/ikramelhattab/rag_chatbot/blob/main/vector_store_completely_free.py): `vector_store_completely_free.py`

### Other components

- **User**
- [PDF/TXT documents](https://github.com/ikramelhattab/rag_chatbot/tree/main/documents): `documents`
- **OpenAI API**

## Connections

- User → Web chatbot: uploads and asks
- User → CLI chatbot: provides path and asks
- User → Local web chatbot: uploads and asks
- PDF/TXT documents → Document processor: loads from path
- Web chatbot → Document processor: processes uploads
- CLI chatbot → Document processor: processes path
- Local web chatbot → Document processor: processes uploads
- Document processor → PDF/TXT loaders: loads files
- Document processor → Chunk splitter: splits documents
- Web chatbot → Vector store: indexes chunks
- CLI chatbot → Vector store: indexes chunks
- Local web chatbot → Free vector store: indexes chunks
- Vector store → Embedding model: embeds chunks
- Free vector store → Local embeddings: embeds chunks
- Vector store → Chroma database: persists and loads
- Free vector store → Chroma database: persists and loads
- Web chatbot → RAG chain: queries
- CLI chatbot → RAG chain: queries
- RAG chain → Retriever: sets up and queries
- Retriever → Vector store: searches chunks
- RAG chain → OpenAI API: generates answer
- RAG chain → Web chatbot: returns answer and sources
- RAG chain → CLI chatbot: returns answer and sources
- Local web chatbot → Context search: searches question
- Context search → Free vector store: requests similar passages
- Free vector store → Context search: returns passages
- Context search → Local web chatbot: returns context