# raianrashidrimon/rag-chatbot architecture

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

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

## Overview

1. **Project type and entrypoint**
   - This is a single-user **Streamlit** application built as a **RAG chatbot for PDFs**.
   - The main runtime entrypoint is `rag-chatbot/app.py`, which likely wires together the UI and the retrieval/generation pipeline.

2. **Top-level separation of concerns**
   - The repository is split into three clear layers:
     - `ui/` for the chat interface
     - `core/` for the retrieval-augmented generation logic
     - `utils/` for shared helpers
   - This separation is important for architecture because the UI should stay thin while the RAG logic stays reusable and testable.

3. **User interaction layer**
   - `rag-chatbot/ui/chat.py` appears to own the Streamlit chat experience:
     - PDF upload controls
     - question input
     - answer display
     - citation rendering
   - This layer is the boundary between the user and the backend pipeline.

4. **RAG orchestration layer**
   - `rag-chatbot/core/chain.py` is the central backend component.
   - Based on the README, it likely orchestrates:
     - loading and parsing PDF content
     - chunking text
     - embedding chunks
     - storing/retrieving chunks from Chroma
     - sending retrieved context to the LLM
   - In architecture terms, this is the application’s core workflow engine.

5. **Document ingestion flow**
   - The README says users can upload PDFs, and the tech stack mentions **PyPDFLoader**.
   - The ingestion path is therefore:
     - PDF upload from the UI
     - PDF text extraction
     - chunking into retrievable segments
     - indexing into the vector store
   - This is the “indexing” side of the RAG system.

6. **Retrieval layer**
   - The repo uses **Chroma** as the vector database and **HuggingFace al-MiniLM-L6-v2** for embeddings.
   - At query time, the user question is embedded and used to retrieve semantically similar document chunks.
   - This retrieval boundary is what constrains answers to the uploaded PDF rather than general model knowledge.

7. **Generation layer**
   - The LLM is **Google Gemini 2.5 Flash**, according to the README.
   - The model receives the user question plus retrieved context and is expected to answer only from the provided document content.
   - The architecture goal is grounded generation rather than open-ended chat.

8. **Citation / source traceability**
   - A core product feature is showing **source page and text**.
   - That means the pipeline preserves metadata from the PDF chunks, likely including page numbers and excerpt text, then attaches them to the final response.
   - This is an important architectural constraint because traceability is part of the user-facing output, not just an internal debug detail.

9. **External dependencies and runtime**
   - The app depends on several external systems/libraries that materially affect architecture:
     - Streamlit for the UI runtime
     - LangChain as the orchestration framework
     - Chroma for persistence/retrieval of embeddings
     - Gemini API for text generation
     - HuggingFace embeddings model for semantic search
     - PyPDFLoader for document parsing
   - This means the app is a hybrid of local Python execution plus remote LLM API calls.

10. **Configuration boundary**
   - The README indicates API key configuration via a `.env` file.
   - That makes secrets and model-provider selection runtime configuration rather than code-level constants.
   - The app is therefore portable across providers in principle, but the current documented setup is tied to Gemini.

11. **Likely request lifecycle**
   - End-to-end flow is:
     - user opens Streamlit app
     - uploads a PDF
     - the document is indexed into Chroma
     - user asks a question
     - the system retrieves relevant chunks
     - the LLM generates a grounded response
     - the UI displays the answer with citations
   - This is the main data path an architecture diagram should show.

12. **What is not present**
   - There is no evidence of a separate web server, database, auth system, or multi-tenant backend.
   - The architecture appears to be a compact local application with an interactive UI and an internal RAG pipeline, not a distributed service.

13. **Diagramming suggestion**
   - A clear diagram would show three boxes:
     - **Streamlit UI**
     - **RAG Core / LangChain pipeline**
     - **External services**: PDF loader, embeddings model, Chroma, Gemini API
   - The key arrows are:
     - PDF upload into ingestion/indexing
     - question input into retrieval + generation
     - answer + citations back to the UI

Main entry points: [`rag-chatbot/core/chain.py`](https://github.com/raianrashidrimon/rag-chatbot/blob/main/rag-chatbot/core/chain.py) (RAG Chain), [`rag-chatbot/ui/chat.py`](https://github.com/raianrashidrimon/rag-chatbot/blob/main/rag-chatbot/ui/chat.py) (Chat UI), [`rag-chatbot/app.py`](https://github.com/raianrashidrimon/rag-chatbot/blob/main/rag-chatbot/app.py) (App), [`rag-chatbot/utils/__init__.py`](https://github.com/raianrashidrimon/rag-chatbot/blob/main/rag-chatbot/utils/__init__.py) (Helpers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_app["Entry"]
  node_n_app["App<br/>streamlit entrypoint<br/>[app.py]"]
end

subgraph group_grp_ui["UI"]
  node_n_chat["Chat UI<br/>streamlit interface<br/>[chat.py]"]
  node_n_ingest_ui["Upload Flow<br/>ui ingestion trigger"]
  node_n_answer_ui["Answer View<br/>ui rendering"]
end

subgraph group_grp_core["Core"]
  node_n_chain{{"RAG Chain<br/>orchestration<br/>[chain.py]"}}
  node_n_pdf_parse["PDF Parse<br/>document loader"]
  node_n_chunk["Chunking<br/>text segmentation"]
  node_n_embed["Embeddings<br/>vector encoding"]
  node_n_index[("Vector Store<br/>retrieval index")]
  node_n_retrieve["Retriever<br/>similarity search"]
  node_n_prompt["Context Pack<br/>prompt assembly"]
  node_n_generate["LLM Answer<br/>generation"]
  node_n_cite["Citations<br/>source traceability"]
end

subgraph group_grp_utils["Utils"]
  node_n_helpers["Helpers<br/>shared utilities<br/>[__init__.py]"]
end

subgraph group_grp_ext["External"]
  node_n_streamlit["Streamlit<br/>ui runtime"]
  node_n_langchain["LangChain<br/>orchestration library"]
  node_n_chroma[("Chroma<br/>vector database")]
  node_n_gemini["Gemini API<br/>llm service"]
  node_n_hf["HF Embeddings<br/>embedding model"]
  node_n_pypdf["PyPDFLoader<br/>pdf parser"]
  node_n_env[".env Config<br/>runtime config"]
end

node_n_app -->|"renders"| node_n_chat
node_n_app -->|"initializes"| node_n_chain
node_n_chat -->|"starts"| node_n_ingest_ui
node_n_chat -->|"displays"| node_n_answer_ui
node_n_ingest_ui -->|"ingest"| node_n_chain
node_n_chain -->|"loads"| node_n_pdf_parse
node_n_chain -->|"splits"| node_n_chunk
node_n_chain -->|"encodes"| node_n_embed
node_n_embed -->|"uses"| node_n_hf
node_n_chain -->|"indexes"| node_n_index
node_n_index -->|"persists"| node_n_chroma
node_n_chain -->|"queries"| node_n_retrieve
node_n_retrieve -->|"searches"| node_n_index
node_n_chain -->|"assembles"| node_n_prompt
node_n_prompt -->|"feeds"| node_n_generate
node_n_generate -->|"calls"| node_n_gemini
node_n_chain -->|"preserves"| node_n_cite
node_n_cite -->|"renders"| node_n_answer_ui
node_n_app -->|"runs on"| node_n_streamlit
node_n_chain -->|"orchestrated by"| node_n_langchain
node_n_chat -->|"configured by"| node_n_env
node_n_chain -->|"shares"| node_n_helpers

click node_n_app "https://github.com/raianrashidrimon/rag-chatbot/blob/main/rag-chatbot/app.py"
click node_n_chat "https://github.com/raianrashidrimon/rag-chatbot/blob/main/rag-chatbot/ui/chat.py"
click node_n_chain "https://github.com/raianrashidrimon/rag-chatbot/blob/main/rag-chatbot/core/chain.py"
click node_n_helpers "https://github.com/raianrashidrimon/rag-chatbot/blob/main/rag-chatbot/utils/__init__.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_n_app toneBlue
class node_n_chat,node_n_ingest_ui,node_n_answer_ui toneAmber
class node_n_chain,node_n_pdf_parse,node_n_chunk,node_n_embed,node_n_index,node_n_retrieve,node_n_prompt,node_n_generate,node_n_cite toneMint
class node_n_helpers toneRose
class node_n_streamlit,node_n_langchain,node_n_chroma,node_n_gemini,node_n_hf,node_n_pypdf,node_n_env toneIndigo
```

## Components

### Entry

Streamlit application entrypoint and wiring.

- [App](https://github.com/raianrashidrimon/rag-chatbot/blob/main/rag-chatbot/app.py): streamlit entrypoint · Main application bootstrap that wires UI and core pipeline. · `rag-chatbot/app.py`

### UI

User interaction layer for chat and document upload.

- [Chat UI](https://github.com/raianrashidrimon/rag-chatbot/blob/main/rag-chatbot/ui/chat.py): streamlit interface · Chat experience, upload controls, question input, answer display, and citations. · `rag-chatbot/ui/chat.py`
- **Upload Flow**: ui ingestion trigger · User-facing path that starts PDF ingestion from the chat interface.
- **Answer View**: ui rendering · Displays grounded responses and source citations to the user.

### Core

RAG orchestration and document-answer pipeline.

- [RAG Chain](https://github.com/raianrashidrimon/rag-chatbot/blob/main/rag-chatbot/core/chain.py): orchestration · Central pipeline coordinating ingestion, retrieval, and grounded generation. · `rag-chatbot/core/chain.py`
- **PDF Parse**: document loader · Extracts text and metadata from uploaded PDFs.
- **Chunking**: text segmentation · Splits parsed document text into retrievable segments.
- **Embeddings**: vector encoding · Converts chunks and questions into semantic vectors.
- **Vector Store**: retrieval index · Persists embedded chunks for semantic search over uploaded PDFs.
- **Retriever**: similarity search · Finds relevant chunks for a user question.
- **Context Pack**: prompt assembly · Combines question and retrieved context into a grounded prompt.
- **LLM Answer**: generation · Produces the final response constrained by retrieved document context.
- **Citations**: source traceability · Carries page numbers and text excerpts into the final response.

### Utils

Shared helper layer.

- [Helpers](https://github.com/raianrashidrimon/rag-chatbot/blob/main/rag-chatbot/utils/__init__.py): shared utilities · Common utility code used across the app. · `rag-chatbot/utils/__init__.py`

### External

Third-party services and libraries used by the app.

- **Streamlit**: ui runtime · Interactive Python UI runtime for the chatbot.
- **LangChain**: orchestration library · Framework used to compose the RAG workflow.
- **Chroma**: vector database · Stores and retrieves embedded document chunks.
- **Gemini API**: llm service · Remote model used for grounded answer generation.
- **HF Embeddings**: embedding model · HuggingFace model used to embed PDFs and queries.
- **PyPDFLoader**: pdf parser · Library used to load and parse PDF documents.
- **.env Config**: runtime config · Secrets and provider settings supplied at runtime.

## Connections

- App → Chat UI: renders · Entrypoint loads the chat interface.
- App → RAG Chain: initializes · Entrypoint wires the RAG pipeline.
- Chat UI → Upload Flow: starts · Upload controls initiate document ingestion.
- Chat UI → Answer View: displays · Chat UI shows generated answers and citations.
- Upload Flow → RAG Chain: ingest · Uploaded PDF is sent into the backend pipeline.
- RAG Chain → PDF Parse: loads · Pipeline extracts text and metadata from PDFs.
- RAG Chain → Chunking: splits · Parsed text is chunked for retrieval.
- RAG Chain → Embeddings: encodes · Chunks and queries are embedded into vectors.
- Embeddings → HF Embeddings: uses · Embeddings are produced by the HuggingFace model.
- RAG Chain → Vector Store: indexes · Embedded chunks are stored for later search.
- Vector Store → Chroma: persists · Vector data is held in Chroma.
- RAG Chain → Retriever: queries · User questions trigger semantic retrieval.
- Retriever → Vector Store: searches · Retriever searches the vector store.
- RAG Chain → Context Pack: assembles · Relevant chunks and question are packed into context.
- Context Pack → LLM Answer: feeds · Constructed prompt is sent to the LLM.
- LLM Answer → Gemini API: calls · Answer generation is handled by Gemini.
- RAG Chain → Citations: preserves · Source metadata is kept for traceability.
- Citations → Answer View: renders · Citations are surfaced in the UI.
- App → Streamlit: runs on · The application is hosted in the Streamlit runtime.
- RAG Chain → LangChain: orchestrated by · Core workflow is composed with LangChain.
- Chat UI → .env Config: configured by · Runtime secrets and provider settings are loaded from environment configuration.
- RAG Chain → Helpers: shares · Common helpers support the backend and UI layers.