# vuthanhnhan2003/ask-pdf-text-only--chatbot architecture

> Architecture diagram of the GitHub repository vuthanhnhan2003/ask-pdf-text-only--chatbot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vuthanhnhan2003/ask-pdf-text-only--chatbot
- Repository: https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot

## Overview

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: [`src/app_v2.py`](https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot/blob/main/src/app_v2.py) (Streamlit app), [`src/processor.py`](https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot/blob/main/src/processor.py) (RAG pipeline), [`src/llm_proxy.py`](https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot/blob/main/src/llm_proxy.py) (LLM proxy), [`docker/docker-compose.yml`](https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot/blob/main/docker/docker-compose.yml) (Compose)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_src_app_v2["Streamlit app<br/>ui orchestrator<br/>[app_v2.py]"]
  node_components_auth_ui["Auth UI<br/>ui component<br/>[auth_ui.py]"]
  node_frontend_auth_ui["Frontend auth<br/>ui screen<br/>[auth_ui.py]"]
  node_frontend_chat_ui["Chat UI<br/>ui screen<br/>[chat_ui.py]"]
  node_frontend_styles["Styles<br/>ui styling<br/>[styles.py]"]
  node_widget_chatbot_widget["Widget<br/>[chatbot-widget.js]"]
  node_widget_loader["Loader<br/>embed bootstrap<br/>[loader.js]"]
end

subgraph group_state["State"]
  node_auth_authentication["Auth logic<br/>auth service<br/>[authentication.py]"]
  node_database_database["DB session<br/>sqlalchemy access<br/>[database.py]"]
  node_database_models["Models<br/>persistence schema<br/>[models.py]"]
  node_services_conversation_service["Conversation svc<br/>business logic"]
end

subgraph group_rag["RAG Pipeline"]
  node_src_processor["RAG pipeline<br/>retrieval pipeline<br/>[processor.py]"]
  node_extracting_pdf_pipeline_main["PDF ingest<br/>batch pipeline<br/>[main.py]"]
  node_src_llm_manager["LLM manager<br/>model facade<br/>[llm_manager.py]"]
end

subgraph group_runtime["Runtime"]
  node_src_llm_proxy["LLM proxy<br/>model gateway<br/>[llm_proxy.py]"]
  node_src_api_service["API service<br/>backend api<br/>[api_service.py]"]
  node_src_config["Config<br/>[config.py]"]
  node_docker_compose["Compose<br/>service orchestration<br/>[docker-compose.yml]"]
  node_dockerfile_app["App image<br/>container build"]
  node_dockerfile_proxy["Proxy image<br/>container build<br/>[Dockerfile.proxy]"]
end

node_src_app_v2 -->|"renders"| node_components_auth_ui
node_src_app_v2 -->|"drives"| node_frontend_chat_ui
node_src_app_v2 -->|"authenticates"| node_auth_authentication
node_src_app_v2 -->|"writes chat"| node_services_conversation_service
node_src_app_v2 -->|"asks"| node_src_processor
node_src_app_v2 -->|"generates"| node_src_llm_manager
node_components_auth_ui -.->|"shares UI"| node_frontend_auth_ui
node_frontend_chat_ui -->|"styles"| node_frontend_styles
node_auth_authentication -->|"stores users"| node_database_database
node_auth_authentication -->|"reads schema"| node_database_models
node_services_conversation_service -->|"persists"| node_database_database
node_services_conversation_service -->|"uses models"| node_database_models
node_src_processor -.->|"ingests"| node_extracting_pdf_pipeline_main
node_src_processor -->|"reads config"| node_src_config
node_src_processor -->|"calls model"| node_src_llm_manager
node_src_processor -->|"retrieves via"| node_src_llm_proxy
node_src_llm_manager -->|"proxies"| node_src_llm_proxy
node_src_llm_proxy -->|"uses config"| node_src_config
node_src_api_service -->|"serves model api"| node_src_llm_proxy
node_docker_compose -->|"builds app"| node_dockerfile_app
node_docker_compose -->|"builds proxy"| node_dockerfile_proxy
node_docker_compose -->|"starts"| node_src_llm_proxy
node_docker_compose -->|"starts"| node_src_app_v2
node_widget_chatbot_widget -->|"bootstraps"| node_widget_loader
node_widget_chatbot_widget -.->|"calls backend"| node_src_api_service

click node_src_app_v2 "https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot/blob/main/src/app_v2.py"
click node_components_auth_ui "https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot/blob/main/components/auth_ui.py"
click node_frontend_auth_ui "https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot/blob/main/frontend/auth_ui.py"
click node_frontend_chat_ui "https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot/blob/main/frontend/chat_ui.py"
click node_frontend_styles "https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot/blob/main/frontend/styles.py"
click node_widget_chatbot_widget "https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot/blob/main/widget/chatbot-widget.js"
click node_widget_loader "https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot/blob/main/widget/loader.js"
click node_auth_authentication "https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot/blob/main/auth/authentication.py"
click node_database_database "https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot/blob/main/database/database.py"
click node_database_models "https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot/blob/main/database/models.py"
click node_services_conversation_service "https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot/blob/main/services/conversation_service.py"
click node_src_processor "https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot/blob/main/src/processor.py"
click node_extracting_pdf_pipeline_main "https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot/blob/main/extracting_pdf_pipeline/main.py"
click node_src_llm_manager "https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot/blob/main/src/llm_manager.py"
click node_src_llm_proxy "https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot/blob/main/src/llm_proxy.py"
click node_src_api_service "https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot/blob/main/src/api_service.py"
click node_src_config "https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot/blob/main/src/config.py"
click node_docker_compose "https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot/blob/main/docker/docker-compose.yml"
click node_dockerfile_app "https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot/tree/main/docker/Dockerfile"
click node_dockerfile_proxy "https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot/blob/main/docker/Dockerfile.proxy"

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_src_app_v2,node_components_auth_ui,node_frontend_auth_ui,node_frontend_chat_ui,node_frontend_styles,node_widget_chatbot_widget,node_widget_loader toneBlue
class node_auth_authentication,node_database_database,node_database_models,node_services_conversation_service toneAmber
class node_src_processor,node_extracting_pdf_pipeline_main,node_src_llm_manager toneMint
class node_src_llm_proxy,node_src_api_service,node_src_config,node_docker_compose,node_dockerfile_app,node_dockerfile_proxy toneRose
```

## Components

### Presentation

User-facing UI and embedding surfaces

- [Streamlit app](https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot/blob/main/src/app_v2.py): ui orchestrator · Main Streamlit entrypoint coordinating auth, chat flow, and backend calls · `src/app_v2.py`
- [Auth UI](https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot/blob/main/components/auth_ui.py): ui component · Reusable authentication screen pieces for the app · `components/auth_ui.py`
- [Frontend auth](https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot/blob/main/frontend/auth_ui.py): ui screen · Authentication-facing frontend layer used by the UI shell · `frontend/auth_ui.py`
- [Chat UI](https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot/blob/main/frontend/chat_ui.py): ui screen · Chat presentation and interaction layer · `frontend/chat_ui.py`
- [Styles](https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot/blob/main/frontend/styles.py): ui styling · Visual styling shared by the frontend layer · `frontend/styles.py`
- [Widget](https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot/blob/main/widget/chatbot-widget.js): embed widget · Standalone embeddable chatbot frontend · `widget/chatbot-widget.js`
- [Loader](https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot/blob/main/widget/loader.js): embed bootstrap · Loader script for embedding the widget in external sites · `widget/loader.js`

### State

Authentication, conversations, and persistent app data

- [Auth logic](https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot/blob/main/auth/authentication.py): auth service · Signup, login, password hashing, and account checks · `auth/authentication.py`
- [DB session](https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot/blob/main/database/database.py): sqlalchemy access · Database engine, sessions, and initialization · `database/database.py`
- [Models](https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot/blob/main/database/models.py): persistence schema · Users, conversations, messages, shares, and settings · `database/models.py`
- [Conversation svc](https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot/blob/main/services/conversation_service.py): business logic · Create, update, pin, archive, delete, and share conversations · `services/conversation_service.py`

### RAG Pipeline

Retrieval, generation, and PDF preprocessing

- [RAG pipeline](https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot/blob/main/src/processor.py): retrieval pipeline · PDF ingestion, chunking, embedding, retrieval, context assembly, and response prep · `src/processor.py`
- [PDF ingest](https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot/blob/main/extracting_pdf_pipeline/main.py): batch pipeline · Separate preprocessing entrypoint for PDF extraction and indexing · `extracting_pdf_pipeline/main.py`
- [LLM manager](https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot/blob/main/src/llm_manager.py): model facade · Application-facing abstraction over the active language model · `src/llm_manager.py`

### Runtime

Proxy, deployment, and service wiring

- [LLM proxy](https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot/blob/main/src/llm_proxy.py): model gateway · OpenAI-compatible FastAPI proxy with local vLLM/Qwen and Gemini fallback · `src/llm_proxy.py`
- [API service](https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot/blob/main/src/api_service.py): backend api · HTTP service surface used by the application and integrations · `src/api_service.py`
- [Config](https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot/blob/main/src/config.py): runtime config · Central runtime knobs for chunking, retrieval, models, and service URLs · `src/config.py`
- [Compose](https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot/blob/main/docker/docker-compose.yml): service orchestration · Runs Streamlit app, LLM proxy, Qdrant, and PostgreSQL together · `docker/docker-compose.yml`
- [App image](https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot/tree/main/docker/Dockerfile): container build · Container image for the Streamlit application runtime · `docker/Dockerfile`
- [Proxy image](https://github.com/vuthanhnhan2003/ask-pdf-text-only--chatbot/blob/main/docker/Dockerfile.proxy): container build · Container image for the model proxy runtime · `docker/Dockerfile.proxy`

## Connections

- 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
