How i-hmzakhan/ueas-chatbot works
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: llm_manager.py LLM manager · main.py FastAPI API · firewall.py Firewall · embedder.py Embedder
Components 16
Backend service
FastAPI application and internal processing pipeline.
- FastAPI API · HTTP surface that routes chat and admin requests.
Backend/main.py - Firewall · Validates inputs and applies request constraints before deeper processing.
Backend/core/firewall.py - Chat API · Public question-answering surface with conversation context.
Backend/main.py - Admin API · Protected surface for uploads and engine configuration.
Backend/main.py - Document parser · Extracts text from PDF, DOCX, TXT, and image inputs.
Backend/core/document_parser.py - Text chunker · Splits extracted text into retrieval-friendly chunks.
Backend/core/text_chunker.py - Embedder · Converts text chunks into embeddings for indexing and retrieval.
Backend/core/embedder.py - LLM manager · Selects Gemini or Groq and coordinates prompts, checks, and answer generation.
Backend/core/llm_manager.py - Ingest flow · End-to-end document ingestion path from upload to indexed vectors.
- Query flow · Retrieval and generation path for answering user questions.
- Upload area · Transient holding area for incoming files before parsing.
External services
Cloud dependencies for storage, embeddings, and generation.
- Supabase · External persistence and similarity retrieval layer for knowledge chunks.
- Gemini API · Provides embeddings and may participate in runtime model routing.
- Groq API · Alternative generation backend selected at runtime.
Other components
- Client · Browser or other caller sending chat and admin requests.
- Docker image · Container packaging for running the API service.
Backend/Dockerfile
Connections 16
- 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.