How al1abdullah/rag-chatbot works
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: chain.py RAG chain · ingest.py Ingest job · index.html Chat page · embedding.py Embeddings
Components 16
Frontend UI
Static server-rendered chat interface and browser behavior
FastAPI Backend
HTTP entrypoint and RAG orchestration
- FastAPI app · Serves the UI and exposes chat endpoints
app/index.py - RAG chain · Coordinates retrieval, history, prompt, and generation
app/chain.py - Persona prompt · Assistant persona and answer-format instructions
app/Prompt/Prompt.py - Groq LLM · Provider-specific LLM configuration and call layer
app/LLM/LLM.py - Embeddings · Sentence-transformer embedding configuration
app/embeddings/embedding.py - Qdrant store · Collection access and semantic retrieval boundary
app/VectorStores/Vectorstores.py - Config · Environment-variable and secret loading
app/config/config.py
Ingestion Pipeline
Offline indexing flow that builds the vector knowledge base
- Ingest job · Offline crawling, chunking, embedding, and indexing
app/ingest.py - Atomcamp site · Website content ingested into the knowledge base
External Services
Hosted model, embedding, and vector storage dependencies
- Hugging Face · External embedding provider
- Groq · External LLM inference provider
- Qdrant Cloud · External semantic storage and retrieval service
Connections 17
- 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