How raianrashidrimon/rag-chatbot works
1. Project type and entrypoint
- This is a single-user Streamlit application built as a RAG chatbot for PDFs.
- The main runtime entrypoint is rag-chatbot/app.py, which likely wires together the UI and the retrieval/generation pipeline.
2. Top-level separation of concerns
- The repository is split into three clear layers:
- ui/ for the chat interface
- core/ for the retrieval-augmented generation logic
- utils/ for shared helpers
- This separation is important for architecture because the UI should stay thin while the RAG logic stays reusable and testable.
3. User interaction layer
- rag-chatbot/ui/chat.py appears to own the Streamlit chat experience:
- PDF upload controls
- question input
- answer display
- citation rendering
- This layer is the boundary between the user and the backend pipeline.
4. RAG orchestration layer
- rag-chatbot/core/chain.py is the central backend component.
- Based on the README, it likely orchestrates:
- loading and parsing PDF content
- chunking text
- embedding chunks
- storing/retrieving chunks from Chroma
- sending retrieved context to the LLM
- In architecture terms, this is the application’s core workflow engine.
5. Document ingestion flow
- The README says users can upload PDFs, and the tech stack mentions PyPDFLoader.
- The ingestion path is therefore:
- PDF upload from the UI
- PDF text extraction
- chunking into retrievable segments
- indexing into the vector store
- This is the “indexing” side of the RAG system.
6. Retrieval layer
- The repo uses Chroma as the vector database and HuggingFace al-MiniLM-L6-v2 for embeddings.
- At query time, the user question is embedded and used to retrieve semantically similar document chunks.
- This retrieval boundary is what constrains answers to the uploaded PDF rather than general model knowledge.
7. Generation layer
- The LLM is Google Gemini 2.5 Flash, according to the README.
- The model receives the user question plus retrieved context and is expected to answer only from the provided document content.
- The architecture goal is grounded generation rather than open-ended chat.
8. Citation / source traceability
- A core product feature is showing source page and text.
- That means the pipeline preserves metadata from the PDF chunks, likely including page numbers and excerpt text, then attaches them to the final response.
- This is an important architectural constraint because traceability is part of the user-facing output, not just an internal debug detail.
9. External dependencies and runtime
- The app depends on several external systems/libraries that materially affect architecture:
- Streamlit for the UI runtime
- LangChain as the orchestration framework
- Chroma for persistence/retrieval of embeddings
- Gemini API for text generation
- HuggingFace embeddings model for semantic search
- PyPDFLoader for document parsing
- This means the app is a hybrid of local Python execution plus remote LLM API calls.
10. Configuration boundary
- The README indicates API key configuration via a .env file.
- That makes secrets and model-provider selection runtime configuration rather than code-level constants.
- The app is therefore portable across providers in principle, but the current documented setup is tied to Gemini.
11. Likely request lifecycle
- End-to-end flow is:
- user opens Streamlit app
- uploads a PDF
- the document is indexed into Chroma
- user asks a question
- the system retrieves relevant chunks
- the LLM generates a grounded response
- the UI displays the answer with citations
- This is the main data path an architecture diagram should show.
12. What is not present
- There is no evidence of a separate web server, database, auth system, or multi-tenant backend.
- The architecture appears to be a compact local application with an interactive UI and an internal RAG pipeline, not a distributed service.
13. Diagramming suggestion
- A clear diagram would show three boxes:
- Streamlit UI
- RAG Core / LangChain pipeline
- External services: PDF loader, embeddings model, Chroma, Gemini API
- The key arrows are:
- PDF upload into ingestion/indexing
- question input into retrieval + generation
- answer + citations back to the UI
Main entry points: chain.py RAG Chain · chat.py Chat UI · app.py App · __init__.py Helpers
Components 21
Entry
Streamlit application entrypoint and wiring.
- App · Main application bootstrap that wires UI and core pipeline.
rag-chatbot/app.py
UI
User interaction layer for chat and document upload.
- Chat UI · Chat experience, upload controls, question input, answer display, and citations.
rag-chatbot/ui/chat.py - Upload Flow · User-facing path that starts PDF ingestion from the chat interface.
- Answer View · Displays grounded responses and source citations to the user.
Core
RAG orchestration and document-answer pipeline.
- RAG Chain · Central pipeline coordinating ingestion, retrieval, and grounded generation.
rag-chatbot/core/chain.py - PDF Parse · Extracts text and metadata from uploaded PDFs.
- Chunking · Splits parsed document text into retrievable segments.
- Embeddings · Converts chunks and questions into semantic vectors.
- Vector Store · Persists embedded chunks for semantic search over uploaded PDFs.
- Retriever · Finds relevant chunks for a user question.
- Context Pack · Combines question and retrieved context into a grounded prompt.
- LLM Answer · Produces the final response constrained by retrieved document context.
- Citations · Carries page numbers and text excerpts into the final response.
Utils
Shared helper layer.
- Helpers · Common utility code used across the app.
rag-chatbot/utils/__init__.py
External
Third-party services and libraries used by the app.
- Streamlit · Interactive Python UI runtime for the chatbot.
- LangChain · Framework used to compose the RAG workflow.
- Chroma · Stores and retrieves embedded document chunks.
- Gemini API · Remote model used for grounded answer generation.
- HF Embeddings · HuggingFace model used to embed PDFs and queries.
- PyPDFLoader · Library used to load and parse PDF documents.
- .env Config · Secrets and provider settings supplied at runtime.
Connections 22
- App → Chat UI: renders · Entrypoint loads the chat interface.
- App → RAG Chain: initializes · Entrypoint wires the RAG pipeline.
- Chat UI → Upload Flow: starts · Upload controls initiate document ingestion.
- Chat UI → Answer View: displays · Chat UI shows generated answers and citations.
- Upload Flow → RAG Chain: ingest · Uploaded PDF is sent into the backend pipeline.
- RAG Chain → PDF Parse: loads · Pipeline extracts text and metadata from PDFs.
- RAG Chain → Chunking: splits · Parsed text is chunked for retrieval.
- RAG Chain → Embeddings: encodes · Chunks and queries are embedded into vectors.
- Embeddings → HF Embeddings: uses · Embeddings are produced by the HuggingFace model.
- RAG Chain → Vector Store: indexes · Embedded chunks are stored for later search.
- Vector Store → Chroma: persists · Vector data is held in Chroma.
- RAG Chain → Retriever: queries · User questions trigger semantic retrieval.
- Retriever → Vector Store: searches · Retriever searches the vector store.
- RAG Chain → Context Pack: assembles · Relevant chunks and question are packed into context.
- Context Pack → LLM Answer: feeds · Constructed prompt is sent to the LLM.
- LLM Answer → Gemini API: calls · Answer generation is handled by Gemini.
- RAG Chain → Citations: preserves · Source metadata is kept for traceability.
- Citations → Answer View: renders · Citations are surfaced in the UI.
- App → Streamlit: runs on · The application is hosted in the Streamlit runtime.
- RAG Chain → LangChain: orchestrated by · Core workflow is composed with LangChain.
- Chat UI → .env Config: configured by · Runtime secrets and provider settings are loaded from environment configuration.
- RAG Chain → Helpers: shares · Common helpers support the backend and UI layers.