# al1abdullah/rag-chatbot architecture

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

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

## Overview

1. **Overall shape**
   - This repo is a single Python application organized around a RAG chatbot pipeline.
   - The main boundaries are: **web UI**, **FastAPI backend**, **RAG orchestration**, and **offline ingestion/indexing**.

2. **User-facing interface**
   - The frontend lives under `app/static/`:
     - `templates/index.html` is the chat page.
     - `css/style.css` handles theming, layout, and light/dark mode.
     - `js/chat.js` handles user interaction, message submission, textarea growth, and client-side chat behavior.
   - The UI is server-rendered/static-assets based, not a separate SPA framework.

3. **API entrypoint**
   - The runtime entrypoint is the FastAPI app in `app/index.py` (the README refers to `main.py`, but the tree shows `index.py`).
   - This layer serves the HTML/assets and exposes the chat endpoint(s) that the browser calls.
   - It is the boundary between HTTP requests and the RAG chain.

4. **RAG orchestration core**
   - `app/chain.py` is the central controller for question answering.
   - It combines:
     - retrieved documents from Qdrant,
     - recent conversation history,
     - the prompt template,
     - and the LLM.
   - The README indicates a parallelized retrieval/memory assembly flow, so this file is likely where the main request-time data flow converges.

5. **Prompt/persona subsystem**
   - `app/Prompt/Prompt.py` defines the chatbot persona and answer-format rules.
   - This is a key architectural boundary because it shapes model behavior independently of retrieval and model choice.
   - The prompt is designed to make the assistant sound like an authoritative human representative for atomcamp.

6. **Model adapter**
   - `app/LLM/LLM.py` encapsulates the Groq-backed LLM configuration.
   - This isolates provider-specific settings from the rest of the chain.
   - The README identifies the model as `openai/gpt-oss-120b` via Groq.

7. **Embeddings subsystem**
   - `app/embeddings/embedding.py` configures the sentence-transformers/Hugging Face embedding model.
   - The README says the embedding model is `all-mpnet-base-v2`.
   - This module is used both during ingestion and when querying the vector store, so it is a shared dependency across offline and online paths.

8. **Vector database boundary**
   - `app/VectorStores/Vectorstores.py` manages the Qdrant connection and collection access.
   - This is the persistence/search layer for semantic retrieval.
   - The architecture depends on Qdrant Cloud as an external service, so retrieval quality and availability are tied to that boundary.

9. **Offline ingestion pipeline**
   - `app/ingest.py` is the indexing job that prepares the knowledge base before chat runtime.
   - It crawls or loads atomcamp website content, chunks it, generates embeddings, and stores vectors plus metadata in Qdrant.
   - This is a separate flow from chat serving; it updates the retrieval corpus rather than answering users directly.

10. **Configuration and secrets**
    - `app/config/config.py` centralizes environment-variable loading.
    - The runtime depends on external credentials for Hugging Face, Groq, and Qdrant, typically supplied through `.env`.
    - This keeps secrets and deployment-specific settings out of the chain and UI code.

11. **Request-time data flow**
    - Browser submits a question from `chat.js` to FastAPI.
    - FastAPI passes it to `chain.py`.
    - The chain retrieves relevant chunks from Qdrant, adds conversation context, formats the prompt, and calls the Groq LLM.
    - The generated answer returns through FastAPI to the UI for rendering.

12. **External services that matter architecturally**
    - **Groq**: inference/runtime model execution.
    - **Qdrant Cloud**: semantic storage and retrieval.
    - **Hugging Face**: embedding generation.
    - These services define the system’s performance, grounding quality, and operational dependencies.

13. **What to diagram as separate boxes**
    - A good architecture diagram should show four main boxes:
      - **Frontend UI**
      - **FastAPI app**
      - **RAG chain / orchestration**
      - **External knowledge and model services**
    - Then show a distinct offline path from `ingest.py` into Qdrant, separate from the live chat path.

14. **Key architectural takeaway**
    - This is not just a chatbot UI; it is a **two-path system**:
      - an **indexing pipeline** that builds the knowledge base,
      - and a **serving pipeline** that retrieves from that knowledge base and generates grounded answers.

Main entry points: [`app/chain.py`](https://github.com/al1abdullah/rag-chatbot/blob/main/app/chain.py) (RAG chain), [`app/ingest.py`](https://github.com/al1abdullah/rag-chatbot/blob/main/app/ingest.py) (Ingest job), [`app/static/templates/index.html`](https://github.com/al1abdullah/rag-chatbot/blob/main/app/static/templates/index.html) (Chat page), [`app/embeddings/embedding.py`](https://github.com/al1abdullah/rag-chatbot/blob/main/app/embeddings/embedding.py) (Embeddings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend UI"]
  node_ui_page["Chat page<br/>template<br/>[index.html]"]
  node_ui_style["Styles<br/>css<br/>[style.css]"]
  node_ui_chat["Chat JS<br/>browser script<br/>[chat.js]"]
  node_browser(("Browser<br/>client"))
end

subgraph group_backend["FastAPI Backend"]
  node_api_entry["FastAPI app<br/>http app<br/>[index.py]"]
  node_rag_chain["RAG chain<br/>orchestrator<br/>[chain.py]"]
  node_prompt_core["Persona prompt<br/>prompt rules<br/>[Prompt.py]"]
  node_llm_adapter["Groq LLM<br/>model adapter<br/>[LLM.py]"]
  node_embedder["Embeddings<br/>embedding model<br/>[embedding.py]"]
  node_vector_store[("Qdrant store<br/>vector db client<br/>[Vectorstores.py]")]
  node_config["Config<br/>[config.py]"]
end

subgraph group_offline["Ingestion Pipeline"]
  node_ingest["Ingest job<br/>indexer<br/>[ingest.py]"]
  node_atomcamp(("Atomcamp site<br/>content source"))
end

subgraph group_external["External Services"]
  node_hf_embed(("Hugging Face<br/>embedding service"))
  node_groq(("Groq<br/>inference service"))
  node_qdrant[("Qdrant Cloud<br/>vector service")]
end

node_browser -->|"loads"| node_ui_page
node_ui_page -->|"uses"| node_ui_style
node_ui_page -->|"runs"| node_ui_chat
node_ui_chat -->|"posts chat"| node_api_entry
node_api_entry -->|"calls"| node_rag_chain
node_rag_chain -->|"retrieves"| node_vector_store
node_rag_chain -->|"formats"| node_prompt_core
node_rag_chain -->|"generates"| node_llm_adapter
node_rag_chain -->|"reads settings"| node_config
node_vector_store -->|"queries"| node_qdrant
node_llm_adapter -->|"invokes"| node_groq
node_embedder -->|"uses"| node_hf_embed
node_ingest -->|"crawls"| node_atomcamp
node_ingest -->|"embeds"| node_embedder
node_ingest -->|"writes"| node_vector_store
node_ingest -->|"persists"| node_qdrant
node_rag_chain -.->|"shared embeddings"| node_embedder

click node_ui_page "https://github.com/al1abdullah/rag-chatbot/blob/main/app/static/templates/index.html"
click node_ui_style "https://github.com/al1abdullah/rag-chatbot/blob/main/app/static/css/style.css"
click node_ui_chat "https://github.com/al1abdullah/rag-chatbot/blob/main/app/static/js/chat.js"
click node_api_entry "https://github.com/al1abdullah/rag-chatbot/blob/main/app/index.py"
click node_rag_chain "https://github.com/al1abdullah/rag-chatbot/blob/main/app/chain.py"
click node_prompt_core "https://github.com/al1abdullah/rag-chatbot/blob/main/app/Prompt/Prompt.py"
click node_llm_adapter "https://github.com/al1abdullah/rag-chatbot/blob/main/app/LLM/LLM.py"
click node_embedder "https://github.com/al1abdullah/rag-chatbot/blob/main/app/embeddings/embedding.py"
click node_vector_store "https://github.com/al1abdullah/rag-chatbot/blob/main/app/VectorStores/Vectorstores.py"
click node_config "https://github.com/al1abdullah/rag-chatbot/blob/main/app/config/config.py"
click node_ingest "https://github.com/al1abdullah/rag-chatbot/blob/main/app/ingest.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_ui_page,node_ui_style,node_ui_chat,node_browser toneBlue
class node_api_entry,node_rag_chain,node_prompt_core,node_llm_adapter,node_embedder,node_vector_store,node_config toneAmber
class node_ingest,node_atomcamp toneMint
class node_hf_embed,node_groq,node_qdrant toneRose
```

## Components

### Frontend UI

Static server-rendered chat interface and browser behavior

- [Chat page](https://github.com/al1abdullah/rag-chatbot/blob/main/app/static/templates/index.html): template · Server-rendered chat interface · `app/static/templates/index.html`
- [Styles](https://github.com/al1abdullah/rag-chatbot/blob/main/app/static/css/style.css): css · Layout, theming, and light/dark mode · `app/static/css/style.css`
- [Chat JS](https://github.com/al1abdullah/rag-chatbot/blob/main/app/static/js/chat.js): browser script · Message submission and client-side chat behavior · `app/static/js/chat.js`
- **Browser**: client · User interaction and rendering runtime

### FastAPI Backend

HTTP entrypoint and RAG orchestration

- [FastAPI app](https://github.com/al1abdullah/rag-chatbot/blob/main/app/index.py): http app · Serves the UI and exposes chat endpoints · `app/index.py`
- [RAG chain](https://github.com/al1abdullah/rag-chatbot/blob/main/app/chain.py): orchestrator · Coordinates retrieval, history, prompt, and generation · `app/chain.py`
- [Persona prompt](https://github.com/al1abdullah/rag-chatbot/blob/main/app/Prompt/Prompt.py): prompt rules · Assistant persona and answer-format instructions · `app/Prompt/Prompt.py`
- [Groq LLM](https://github.com/al1abdullah/rag-chatbot/blob/main/app/LLM/LLM.py): model adapter · Provider-specific LLM configuration and call layer · `app/LLM/LLM.py`
- [Embeddings](https://github.com/al1abdullah/rag-chatbot/blob/main/app/embeddings/embedding.py): embedding model · Sentence-transformer embedding configuration · `app/embeddings/embedding.py`
- [Qdrant store](https://github.com/al1abdullah/rag-chatbot/blob/main/app/VectorStores/Vectorstores.py): vector db client · Collection access and semantic retrieval boundary · `app/VectorStores/Vectorstores.py`
- [Config](https://github.com/al1abdullah/rag-chatbot/blob/main/app/config/config.py): env config · Environment-variable and secret loading · `app/config/config.py`

### Ingestion Pipeline

Offline indexing flow that builds the vector knowledge base

- [Ingest job](https://github.com/al1abdullah/rag-chatbot/blob/main/app/ingest.py): indexer · Offline crawling, chunking, embedding, and indexing · `app/ingest.py`
- **Atomcamp site**: content source · Website content ingested into the knowledge base

### External Services

Hosted model, embedding, and vector storage dependencies

- **Hugging Face**: embedding service · External embedding provider
- **Groq**: inference service · External LLM inference provider
- **Qdrant Cloud**: vector service · External semantic storage and retrieval service

## Connections

- Browser → Chat page: loads · Browser requests the chat page
- Chat page → Styles: uses · Page applies styling assets
- Chat page → Chat JS: runs · Page loads client-side chat behavior
- Chat JS → FastAPI app: posts chat · Browser sends user messages to the backend
- FastAPI app → RAG chain: calls · FastAPI delegates questions to the RAG orchestration layer
- RAG chain → Qdrant store: retrieves · Fetches relevant chunks from Qdrant
- RAG chain → Persona prompt: formats · Injects persona and answer rules into the prompt
- RAG chain → Groq LLM: generates · Sends the assembled prompt to the model adapter
- RAG chain → Config: reads settings · Uses runtime configuration and secrets
- Qdrant store → Qdrant Cloud: queries · Retrieval boundary to external vector storage
- Groq LLM → Groq: invokes · Calls the hosted model provider
- Embeddings → Hugging Face: uses · Embedding model is provided externally
- Ingest job → Atomcamp site: crawls · Indexes source content from the website
- Ingest job → Embeddings: embeds · Generates vectors for document chunks
- Ingest job → Qdrant store: writes · Stores chunks and metadata in the vector database
- Ingest job → Qdrant Cloud: persists · Offline indexing updates the external vector store
- RAG chain → Embeddings: shared embeddings · Query-time retrieval depends on the same embedding model
