How vuthanhnhan2003/ask-pdf-text-only--chatbot works
1. What this repo is
- This is a RAG chatbot for PDF-based study materials.
- The main runtime is a Streamlit app that lets users sign in, pick a subject, ask questions, and get answers grounded in retrieved PDF chunks.
2. Primary user-facing boundary
- src/app_v2.py is the main orchestration point for the UI.
- The UI is split into reusable pieces under components/ and frontend/, including auth and chat screens.
- The Streamlit layer is responsible for session state, user interactions, and calling the backend services; it does not own retrieval or persistence logic.
3. Authentication subsystem
- auth/authentication.py handles sign-up, login, password hashing, and account checks.
- Passwords are stored with bcrypt.
- Authentication state is tracked in Streamlit session state, which means login is app-local rather than a separate auth server.
4. Conversation and persistence layer
- database/database.py manages SQLAlchemy sessions and DB initialization.
- database/models.py defines the persistent entities: users, conversations, messages, shared conversations, and user settings.
- services/conversation_service.py contains business logic for creating, updating, pinning, archiving, deleting, and sharing conversations.
- This is the main boundary between UI actions and PostgreSQL writes.
5. RAG pipeline
- src/processor.py is the core retrieval/generation pipeline.
- It ingests PDFs, chunks text, creates embeddings, stores/searches vectors, and builds the final prompt context.
- The readme shows the flow as: question → embedding → Qdrant retrieval → context assembly with chat history → LLM generation → persist response.
6. Vector retrieval subsystem
- Qdrant is the vector store, exposed as a separate service in Docker on port 6333.
- The embedding model is sentence-transformers with all-MiniLM-L6-v2, cached locally under models/.
- Subject-based PDF organization in data/ is important: retrieval is grouped by academic subject rather than by a single global corpus.
7. LLM abstraction and fallback
- src/llm_manager.py is the abstraction layer used by the app to talk to whichever model is active.
- src/llm_proxy.py exposes an OpenAI-compatible FastAPI endpoint and mediates between local vLLM/Qwen and Google Gemini fallback.
- This creates a clean boundary: the Streamlit app talks to one interface, while model selection and fallback are hidden behind the proxy.
8. Storage and data flow
- PostgreSQL stores durable application state: users, conversations, messages, and settings.
- Qdrant stores semantic chunks and embeddings for retrieval.
- The app reads both: PostgreSQL for conversation history/user state, Qdrant for knowledge grounding.
- These are independent stores with different access patterns: relational for app state, vector for semantic search.
9. PDF ingestion path
- extracting_pdf_pipeline/main.py suggests a separate ingestion entrypoint for processing PDFs outside the interactive chat loop.
- The readme indicates PDF text extraction uses PyMuPDF / pymupdf4llm, then chunking and embedding before indexing.
- This is a batch-style preprocessing boundary, distinct from interactive question answering.
10. Deployment and service composition
- docker/docker-compose.yml orchestrates four main runtime services: app (Streamlit), llm_proxy (FastAPI), qdrant, and postgres.
- docker/Dockerfile and docker/Dockerfile.proxy separate the UI/runtime image from the proxy/model-serving image.
- Health checks are used to ensure the app starts only after the dependent services are ready.
11. Embeddable widget boundary
- The widget/ folder contains a standalone chatbot widget with a loader and integration snippets.
- This is a separate integration surface from the Streamlit app, meant for embedding the chatbot into another website.
- Architecturally, it consumes the same chat backend behavior but is packaged as a frontend component.
12. Configuration and operational concerns
- src/config.py centralizes runtime knobs such as chunk size, top-k retrieval, model choice, temperature, and service URLs.
- Logging goes to a dated file under logs/, which is useful for tracing ingestion, retrieval, and generation behavior.
- .env.example shows the key external dependencies: Google API key, PostgreSQL URL, Qdrant URL, and LLM proxy URL.
13. How to read the architecture diagram
- Draw the Streamlit UI at the top.
- Behind it, split the backend into three clear concerns:
- Identity / chat state via auth + PostgreSQL,
- Knowledge retrieval via processor + Qdrant + embeddings,
- Answer generation via llm_manager + llm_proxy + Gemini/vLLM.
- Treat PDF ingestion as a preprocessing pipeline feeding Qdrant, and treat the widget as an alternate presentation channel.
Main entry points: app_v2.py Streamlit app · processor.py RAG pipeline · llm_proxy.py LLM proxy · docker-compose.yml Compose
Components 20
Presentation
User-facing UI and embedding surfaces
- Streamlit app · Main Streamlit entrypoint coordinating auth, chat flow, and backend calls
src/app_v2.py - Auth UI · Reusable authentication screen pieces for the app
components/auth_ui.py - Frontend auth · Authentication-facing frontend layer used by the UI shell
frontend/auth_ui.py - Chat UI · Chat presentation and interaction layer
frontend/chat_ui.py - Styles · Visual styling shared by the frontend layer
frontend/styles.py - Widget · Standalone embeddable chatbot frontend
widget/chatbot-widget.js - Loader · Loader script for embedding the widget in external sites
widget/loader.js
State
Authentication, conversations, and persistent app data
- Auth logic · Signup, login, password hashing, and account checks
auth/authentication.py - DB session · Database engine, sessions, and initialization
database/database.py - Models · Users, conversations, messages, shares, and settings
database/models.py - Conversation svc · Create, update, pin, archive, delete, and share conversations
services/conversation_service.py
RAG Pipeline
Retrieval, generation, and PDF preprocessing
- RAG pipeline · PDF ingestion, chunking, embedding, retrieval, context assembly, and response prep
src/processor.py - PDF ingest · Separate preprocessing entrypoint for PDF extraction and indexing
extracting_pdf_pipeline/main.py - LLM manager · Application-facing abstraction over the active language model
src/llm_manager.py
Runtime
Proxy, deployment, and service wiring
- LLM proxy · OpenAI-compatible FastAPI proxy with local vLLM/Qwen and Gemini fallback
src/llm_proxy.py - API service · HTTP service surface used by the application and integrations
src/api_service.py - Config · Central runtime knobs for chunking, retrieval, models, and service URLs
src/config.py - Compose · Runs Streamlit app, LLM proxy, Qdrant, and PostgreSQL together
docker/docker-compose.yml - App image · Container image for the Streamlit application runtime
docker/Dockerfile - Proxy image · Container image for the model proxy runtime
docker/Dockerfile.proxy
Connections 25
- Streamlit app → Auth UI: renders · Uses reusable auth UI pieces
- Streamlit app → Chat UI: drives · Coordinates chat interaction screens
- Streamlit app → Auth logic: authenticates · Checks login and signup state
- Streamlit app → Conversation svc: writes chat · Persists conversation actions and message updates
- Streamlit app → RAG pipeline: asks · Sends user questions into the RAG pipeline
- Streamlit app → LLM manager: generates · Requests model responses through the model facade
- Auth UI → Frontend auth: shares UI · Auth interface is composed across UI layers
- Chat UI → Styles: styles · Chat presentation uses shared styling
- Auth logic → DB session: stores users · Uses the database session layer for account persistence
- Auth logic → Models: reads schema · Relies on persisted user/account entities
- Conversation svc → DB session: persists · Runs SQLAlchemy-backed writes and reads
- Conversation svc → Models: uses models · Operates on conversation and message entities
- RAG pipeline → PDF ingest: ingests · Shares the PDF preprocessing boundary
- RAG pipeline → Config: reads config · Uses chunking, retrieval, and service settings
- RAG pipeline → LLM manager: calls model · Hands assembled context to generation layer
- RAG pipeline → LLM proxy: retrieves via · Connects to the model proxy and downstream services
- LLM manager → LLM proxy: proxies · Forwards model requests through the gateway
- LLM proxy → Config: uses config · Applies model, temperature, and endpoint settings
- API service → LLM proxy: serves model api · Exposes the backend model-facing HTTP surface
- Compose → App image: builds app · Defines the Streamlit service image
- Compose → Proxy image: builds proxy · Defines the proxy/model-serving image
- Compose → LLM proxy: starts · Runs the model proxy alongside other services
- Compose → Streamlit app: starts · Launches the main Streamlit application service
- Widget → Loader: bootstraps · Widget loader initializes the embedded chatbot
- Widget → API service: calls backend · Consumes the same chatbot API behavior as the app