# fatir002/rag-chatbot architecture

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

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

## Overview

RAG Chatbot lets a user upload one PDF, DOCX, or TXT document, then ask questions grounded in that upload. The browser sends uploads to the FastAPI entry point, which extracts text and delegates chunking, embedding, and storage; queries are classified, retrieved within the supplied document ID, and answered from retrieved context, with source text returned for verification. Casual messages skip retrieval. The README documents Supabase/pgvector and Groq integrations; sampled code confirms their callers. The graph omits deployment details and does not infer unsampled implementation links.

Main entry points: [`app/main.py`](https://github.com/fatir002/rag-chatbot/blob/main/app/main.py) (FastAPI routes), [`app/clients.py`](https://github.com/fatir002/rag-chatbot/blob/main/app/clients.py) (Shared clients), [`app/generate.py`](https://github.com/fatir002/rag-chatbot/blob/main/app/generate.py) (Answer generation), [`app/router.py`](https://github.com/fatir002/rag-chatbot/blob/main/app/router.py) (Message classifier)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Chat interface"]
  node_browser["Browser<br/>[index.html]"]
  node_frontend["Chat client<br/>[script.js]"]
end

subgraph group_api["API orchestration"]
  node_api_main["FastAPI routes<br/>[main.py]"]
  node_contracts["API contracts<br/>[models.py]"]
  node_router["Message classifier<br/>[router.py]"]
  node_generation["Answer generation<br/>[generate.py]"]
end

subgraph group_pipeline["Document pipeline"]
  node_extract["Text extraction<br/>[loaders.py]"]
  node_ingest["Chunk and ingest<br/>[ingest.py]"]
  node_retrieve["Scoped retrieval<br/>[retrieve.py]"]
end

subgraph group_services["Models and services"]
  node_clients["Shared clients<br/>[clients.py]"]
  node_config["Settings<br/>[config.py]"]
  node_embedder["Sentence embeddings<br/>[clients.py]"]
  node_supabase[("Supabase pgvector")]
  node_groq{{"Groq models"}}
end

node_user(("User"))

node_user -->|"uses"| node_browser
node_browser -->|"loads"| node_frontend
node_frontend -->|"uploads / queries"| node_api_main
node_api_main -->|"returns answer and sources"| node_frontend
node_api_main -->|"validates / shapes"| node_contracts
node_api_main -->|"extracts upload text"| node_extract
node_api_main -->|"ingests text"| node_ingest
node_ingest -->|"encodes / stores"| node_clients
node_api_main -->|"classifies question"| node_router
node_router -->|"classifies via"| node_groq
node_api_main -->|"generates casual reply"| node_generation
node_api_main -->|"retrieves document chunks"| node_retrieve
node_retrieve -->|"encodes / searches"| node_clients
node_api_main -->|"generates grounded answer"| node_generation
node_generation -->|"generates via"| node_groq
node_clients -->|"uses"| node_embedder
node_clients -->|"connects to"| node_supabase
node_clients -->|"reads settings"| node_config
node_router -->|"reads settings"| node_config
node_generation -->|"reads settings"| node_config

click node_browser "https://github.com/fatir002/rag-chatbot/blob/main/static/index.html"
click node_frontend "https://github.com/fatir002/rag-chatbot/blob/main/static/script.js"
click node_api_main "https://github.com/fatir002/rag-chatbot/blob/main/app/main.py"
click node_contracts "https://github.com/fatir002/rag-chatbot/blob/main/app/models.py"
click node_extract "https://github.com/fatir002/rag-chatbot/blob/main/app/loaders.py"
click node_ingest "https://github.com/fatir002/rag-chatbot/blob/main/app/ingest.py"
click node_retrieve "https://github.com/fatir002/rag-chatbot/blob/main/app/retrieve.py"
click node_router "https://github.com/fatir002/rag-chatbot/blob/main/app/router.py"
click node_generation "https://github.com/fatir002/rag-chatbot/blob/main/app/generate.py"
click node_clients "https://github.com/fatir002/rag-chatbot/blob/main/app/clients.py"
click node_config "https://github.com/fatir002/rag-chatbot/blob/main/app/config.py"
click node_embedder "https://github.com/fatir002/rag-chatbot/blob/main/app/clients.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_browser,node_frontend,node_user toneBlue
class node_api_main,node_contracts,node_router,node_generation toneAmber
class node_extract,node_ingest,node_retrieve toneMint
class node_clients,node_config,node_embedder,node_supabase,node_groq toneRose
```

## Components

### Chat interface

- [Browser](https://github.com/fatir002/rag-chatbot/blob/main/static/index.html): `static/index.html`
- [Chat client](https://github.com/fatir002/rag-chatbot/blob/main/static/script.js): `static/script.js`

### API orchestration

- [FastAPI routes](https://github.com/fatir002/rag-chatbot/blob/main/app/main.py): `app/main.py`
- [API contracts](https://github.com/fatir002/rag-chatbot/blob/main/app/models.py): `app/models.py`
- [Message classifier](https://github.com/fatir002/rag-chatbot/blob/main/app/router.py): `app/router.py`
- [Answer generation](https://github.com/fatir002/rag-chatbot/blob/main/app/generate.py): `app/generate.py`

### Document pipeline

- [Text extraction](https://github.com/fatir002/rag-chatbot/blob/main/app/loaders.py): `app/loaders.py`
- [Chunk and ingest](https://github.com/fatir002/rag-chatbot/blob/main/app/ingest.py): `app/ingest.py`
- [Scoped retrieval](https://github.com/fatir002/rag-chatbot/blob/main/app/retrieve.py): `app/retrieve.py`

### Models and services

- [Shared clients](https://github.com/fatir002/rag-chatbot/blob/main/app/clients.py): `app/clients.py`
- [Settings](https://github.com/fatir002/rag-chatbot/blob/main/app/config.py): `app/config.py`
- [Sentence embeddings](https://github.com/fatir002/rag-chatbot/blob/main/app/clients.py): `app/clients.py`
- **Supabase pgvector**
- **Groq models**

### Other components

- **User**

## Connections

- User → Browser: uses
- Browser → Chat client: loads
- Chat client → FastAPI routes: uploads / queries
- FastAPI routes → Chat client: returns answer and sources
- FastAPI routes → API contracts: validates / shapes
- FastAPI routes → Text extraction: extracts upload text
- FastAPI routes → Chunk and ingest: ingests text
- Chunk and ingest → Shared clients: encodes / stores
- FastAPI routes → Message classifier: classifies question
- Message classifier → Groq models: classifies via
- FastAPI routes → Answer generation: generates casual reply
- FastAPI routes → Scoped retrieval: retrieves document chunks
- Scoped retrieval → Shared clients: encodes / searches
- FastAPI routes → Answer generation: generates grounded answer
- Answer generation → Groq models: generates via
- Shared clients → Sentence embeddings: uses
- Shared clients → Supabase pgvector: connects to
- Shared clients → Settings: reads settings
- Message classifier → Settings: reads settings
- Answer generation → Settings: reads settings