# i-hmzakhan/ueas-chatbot architecture

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

- Interactive diagram: https://gitdiagram.com/i-hmzakhan/ueas-chatbot
- Repository: https://github.com/i-hmzakhan/ueas-chatbot

## Overview

1. **Overall shape**
   - This repository is a single Python backend service, built with **FastAPI**, that exposes an HTTP API for chatbot ingestion and question answering.
   - The architecture is centered around a **corrective RAG pipeline**: ingest documents, store embeddings in Supabase, retrieve relevant context at query time, then generate an answer through an external LLM.

2. **API boundary**
   - `Backend/main.py` is the entry point and request orchestration layer.
   - It likely defines two major surface areas: a **public chat endpoint** and **admin endpoints** for document ingestion and engine configuration.
   - This file is the boundary between external clients and the internal core modules.

3. **Document ingestion path**
   - Admin uploads enter the system as files, are temporarily held in the backend’s upload area, then passed through the parsing pipeline.
   - `core/document_parser.py` handles extracting usable text from **PDF, DOCX, TXT, and image inputs**.
   - `core/text_chunker.py` then splits the extracted content into smaller semantic chunks for retrieval.

4. **Embedding and indexing**
   - `core/embedder.py` converts text chunks into **768-dimensional embeddings** using the Gemini embedding API.
   - Those vectors are stored externally in **Supabase**, which serves as the persistence and retrieval layer for the knowledge base.
   - This means the backend itself is not a long-term document store; it depends on Supabase for indexed knowledge.

5. **Chat/query path**
   - A user query arrives at the chat endpoint, is validated, then routed into the retrieval-and-generation flow.
   - The system fetches relevant chunks from Supabase based on embeddings similarity and combines them with the user’s question and conversation history.
   - The retrieved context is then forwarded to the LLM orchestration layer for final answer generation.

6. **LLM orchestration**
   - `core/llm_manager.py` is the abstraction for model selection and prompt handling.
   - The backend can switch between **Gemini** and **Groq** at runtime, which makes model choice a configurable concern rather than a hardcoded dependency.
   - The README indicates this layer also performs **evaluation/relevance/confidence checks**, so it is not just a simple pass-through to an LLM.

7. **Guardrails and request policy**
   - `core/firewall.py` provides the safety and control boundary for incoming requests.
   - Its role is to validate inputs and apply basic abuse/off-topic controls before the request reaches retrieval or generation.
   - In the architecture diagram, this belongs upstream of both ingestion and chat execution, because it protects the whole service.

8. **External service dependencies**
   - The backend depends materially on three external systems: **Supabase** for storage/vector retrieval, **Gemini** for embeddings and some routing/inference, and **Groq** for alternative inference.
   - These are configured entirely through environment variables, so the service is cloud-connected and stateless apart from temporary file handling.
   - `ADMIN_PASSCODE` gates the protected admin endpoints.

9. **Data lifecycle**
   - Uploaded files are transient: they flow through parsing and chunking, are turned into vectors, and the meaningful knowledge is persisted externally.
   - The chat path is also mostly stateless, with conversation history supplied by the client and context assembled on demand.
   - This makes the backend easy to scale horizontally, since state is not stored in-process.

10. **Runtime and deployment**
   - The project is designed to run as a standalone Python service or inside a **Docker** container (`Backend/Dockerfile`).
   - It is meant to expose the API on port 8000 and serve FastAPI’s interactive docs at `/docs`.
   - The architecture is therefore “API server + external AI/data services,” not a monolithic application with embedded models.

11. **Module responsibilities**
   - `document_parser.py`: extract content from different file types.
   - `text_chunker.py`: break text into retrieval-friendly segments.
   - `embedder.py`: generate vector representations.
   - `llm_manager.py`: choose and coordinate LLM backends.
   - `firewall.py`: validate and constrain requests.
   - `main.py`: assemble these pieces into the HTTP API.

12. **Key architectural diagram takeaway**
   - The clearest diagram is a flow from **client → FastAPI → firewall/validation → ingestion or retrieval pipeline → Supabase / LLM providers → response**.
   - The main seams are between request handling, document processing, vector storage, and model orchestration.
   - Those seams are the important boundaries in this codebase.

Main entry points: [`Backend/core/llm_manager.py`](https://github.com/i-hmzakhan/ueas-chatbot/blob/master/Backend/core/llm_manager.py) (LLM manager), [`Backend/main.py`](https://github.com/i-hmzakhan/ueas-chatbot/blob/master/Backend/main.py) (FastAPI API), [`Backend/core/firewall.py`](https://github.com/i-hmzakhan/ueas-chatbot/blob/master/Backend/core/firewall.py) (Firewall), [`Backend/core/embedder.py`](https://github.com/i-hmzakhan/ueas-chatbot/blob/master/Backend/core/embedder.py) (Embedder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend service"]
  node_main["FastAPI API<br/>entrypoint<br/>[main.py]"]
  node_firewall{{"Firewall<br/>policy guard<br/>[firewall.py]"}}
  node_chat_api["Chat API<br/>query endpoint<br/>[main.py]"]
  node_admin_api["Admin API<br/>ingest/config endpoint<br/>[main.py]"]
  node_parser["Document parser<br/>content extraction<br/>[document_parser.py]"]
  node_chunker["Text chunker<br/>segmentation<br/>[text_chunker.py]"]
  node_embedder(("Embedder<br/>vectorization<br/>[embedder.py]"))
  node_llm_manager["LLM manager<br/>model orchestration<br/>[llm_manager.py]"]
  node_ingest_flow["Ingest flow<br/>pipeline stage"]
  node_query_flow["Query flow<br/>pipeline stage"]
  node_upload_tmp[("Upload area<br/>temp storage")]
end

subgraph group_external["External services"]
  node_supabase[("Supabase<br/>vector store")]
  node_gemini_embed(("Gemini API<br/>embedding/model service"))
  node_groq(("Groq API<br/>llm service"))
end

node_client(("Client<br/>HTTP consumer"))
node_docker["Docker image<br/>runtime packaging"]

node_client -->|"HTTP requests"| node_main
node_main -->|"validate"| node_firewall
node_firewall -->|"allow chat"| node_chat_api
node_firewall -->|"allow admin"| node_admin_api
node_admin_api -->|"store upload"| node_upload_tmp
node_upload_tmp -->|"parse file"| node_parser
node_parser -->|"clean text"| node_chunker
node_chunker -->|"chunk vectors"| node_embedder
node_embedder -->|"embed"| node_gemini_embed
node_embedder -->|"index"| node_supabase
node_chat_api -->|"retrieve context"| node_supabase
node_chat_api -->|"generate answer"| node_llm_manager
node_llm_manager -->|"route to Gemini"| node_gemini_embed
node_llm_manager -->|"route to Groq"| node_groq
node_admin_api -->|"configure engine"| node_llm_manager
node_main -.->|"package for runtime"| node_docker

click node_main "https://github.com/i-hmzakhan/ueas-chatbot/blob/master/Backend/main.py"
click node_firewall "https://github.com/i-hmzakhan/ueas-chatbot/blob/master/Backend/core/firewall.py"
click node_chat_api "https://github.com/i-hmzakhan/ueas-chatbot/blob/master/Backend/main.py"
click node_admin_api "https://github.com/i-hmzakhan/ueas-chatbot/blob/master/Backend/main.py"
click node_parser "https://github.com/i-hmzakhan/ueas-chatbot/blob/master/Backend/core/document_parser.py"
click node_chunker "https://github.com/i-hmzakhan/ueas-chatbot/blob/master/Backend/core/text_chunker.py"
click node_embedder "https://github.com/i-hmzakhan/ueas-chatbot/blob/master/Backend/core/embedder.py"
click node_llm_manager "https://github.com/i-hmzakhan/ueas-chatbot/blob/master/Backend/core/llm_manager.py"
click node_docker "https://github.com/i-hmzakhan/ueas-chatbot/tree/master/Backend/Dockerfile"

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_main,node_firewall,node_chat_api,node_admin_api,node_parser,node_chunker,node_embedder,node_llm_manager,node_ingest_flow,node_query_flow,node_upload_tmp toneBlue
class node_supabase,node_gemini_embed,node_groq toneAmber
class node_client,node_docker toneNeutral
```

## Components

### Backend service

FastAPI application and internal processing pipeline.

- [FastAPI API](https://github.com/i-hmzakhan/ueas-chatbot/blob/master/Backend/main.py): entrypoint · HTTP surface that routes chat and admin requests. · `Backend/main.py`
- [Firewall](https://github.com/i-hmzakhan/ueas-chatbot/blob/master/Backend/core/firewall.py): policy guard · Validates inputs and applies request constraints before deeper processing. · `Backend/core/firewall.py`
- [Chat API](https://github.com/i-hmzakhan/ueas-chatbot/blob/master/Backend/main.py): query endpoint · Public question-answering surface with conversation context. · `Backend/main.py`
- [Admin API](https://github.com/i-hmzakhan/ueas-chatbot/blob/master/Backend/main.py): ingest/config endpoint · Protected surface for uploads and engine configuration. · `Backend/main.py`
- [Document parser](https://github.com/i-hmzakhan/ueas-chatbot/blob/master/Backend/core/document_parser.py): content extraction · Extracts text from PDF, DOCX, TXT, and image inputs. · `Backend/core/document_parser.py`
- [Text chunker](https://github.com/i-hmzakhan/ueas-chatbot/blob/master/Backend/core/text_chunker.py): segmentation · Splits extracted text into retrieval-friendly chunks. · `Backend/core/text_chunker.py`
- [Embedder](https://github.com/i-hmzakhan/ueas-chatbot/blob/master/Backend/core/embedder.py): vectorization · Converts text chunks into embeddings for indexing and retrieval. · `Backend/core/embedder.py`
- [LLM manager](https://github.com/i-hmzakhan/ueas-chatbot/blob/master/Backend/core/llm_manager.py): model orchestration · Selects Gemini or Groq and coordinates prompts, checks, and answer generation. · `Backend/core/llm_manager.py`
- **Ingest flow**: pipeline stage · End-to-end document ingestion path from upload to indexed vectors.
- **Query flow**: pipeline stage · Retrieval and generation path for answering user questions.
- **Upload area**: temp storage · Transient holding area for incoming files before parsing.

### External services

Cloud dependencies for storage, embeddings, and generation.

- **Supabase**: vector store · External persistence and similarity retrieval layer for knowledge chunks.
- **Gemini API**: embedding/model service · Provides embeddings and may participate in runtime model routing.
- **Groq API**: llm service · Alternative generation backend selected at runtime.

### Other components

- **Client**: HTTP consumer · Browser or other caller sending chat and admin requests.
- [Docker image](https://github.com/i-hmzakhan/ueas-chatbot/tree/master/Backend/Dockerfile): runtime packaging · Container packaging for running the API service. · `Backend/Dockerfile`

## Connections

- Client → FastAPI API: HTTP requests · External callers reach the FastAPI service.
- FastAPI API → Firewall: validate · Requests are screened before processing.
- Firewall → Chat API: allow chat · Validated chat requests proceed to query handling.
- Firewall → Admin API: allow admin · Protected admin operations proceed after policy checks.
- Admin API → Upload area: store upload · Incoming files are held temporarily.
- Upload area → Document parser: parse file · Uploaded content is extracted into text.
- Document parser → Text chunker: clean text · Extracted text is segmented for retrieval.
- Text chunker → Embedder: chunk vectors · Chunks are prepared for embedding.
- Embedder → Gemini API: embed · Embeddings are generated via Gemini.
- Embedder → Supabase: index · Vectorized chunks are persisted externally.
- Chat API → Supabase: retrieve context · Relevant chunks are fetched by similarity.
- Chat API → LLM manager: generate answer · Query, context, and history are sent to model orchestration.
- LLM manager → Gemini API: route to Gemini · Gemini can be selected for inference or routing.
- LLM manager → Groq API: route to Groq · Groq is the alternate runtime LLM backend.
- Admin API → LLM manager: configure engine · Admin controls can affect model selection and behavior.
- FastAPI API → Docker image: package for runtime · The service is intended to run standalone or in a container.