ChatPDF 📄

Chat with any PDF using AI. Upload a document, ask questions about it, and get answers powered by Groq.

Architecture Diagram

Core Features

• Interactive Document Conversations — Upload PDF files and query their contents.
• Hybrid RAG Retrieval — Performs semantic vector searches on document chunks using ChromaDB and keyword search using BM25, fuses the scores with reciprocal rank/weighted score fusion, and reranks the results using an LLM to answer specific questions based on the PDF context.
• Secure Authentication — JWT authentication and Google OAuth login.
• Saves all chat history — Saves all chat history so you can revisit previous conversations.

---

Tech Stack

• Frontend: HTML, JavaScript, Vanilla CSS
• Backend: FastAPI, Python
• Orchestration: LangChain
• LLM and Embeddings: Groq (LLaMA 3.3) for LLM and Local Feature Hashing for Embeddings
• Vector Database: ChromaDB
• Relational Database: PostgreSQL (SQLAlchemy)

---

Folder Structure

ChatPDF/
│
├── backend/
│   │
│   ├── app/
│   │   │
│   │   ├── core/
│   │   │   ├── __init__.py
│   │   │   ├── embeddings.py                    # ChromaDB collections and vector storage operations
│   │   │   └── rag/
│   │   │       ├── __init__.py
│   │   │       ├── hybrid_retriever.py          # Retrieves candidate chunks using semantic and lexical search
│   │   │       ├── query_expander.py            # Expands user query into multiple queries using LLM
│   │   │       ├── rag_pipeline.py              # Entrypoint for running the RAG Q&A pipeline
│   │   │       ├── reranker.py                  # Reranks combined retrieve results using LLM
│   │   │       ├── fusion/
│   │   │       │   ├── __init__.py
│   │   │       │   └── weighted_fusion.py       # Combines vector and BM25 results with weighted fusion
│   │   │       └── retrievers/
│   │   │           ├── __init__.py
│   │   │           ├── bm25_retriever.py         # Local BM25 keyword index and retrieval
│   │   │           └── vector_retriever.py       # Semantic vector database retrieval
│   │   │
│   │   ├── db/
│   │   │   ├── database.py                      # PostgreSQL connection and session configurations
│   │   │   ├── models.py                        # SQLAlchemy models (User, Document, Session, ChatHistory)
│   │   │   ├── __init__.py
│   │   │   └── crud/                            # Database read/write (CRUD) operations
│   │   │       ├── __init__.py
│   │   │       ├── chat_crud.py                 # Messages history database storage
│   │   │       ├── document_crud.py             # Uploaded documents database management
│   │   │       ├── session_crud.py              # Chat sessions creation and listing queries
│   │   │       └── user_crud.py                 # User authentication and registration database actions
│   │   │
│   │   ├── helper/
│   │   │   ├── __init__.py
│   │   │   ├── auth_helper.py                   # JWT encoding/decoding and bcrypt password hashing
│   │   │   └── document_helper.py               # PDF text extraction and text splitting helpers
│   │   │
│   │   ├── routes/
│   │   │   ├── __init__.py
│   │   │   ├── auth.py                          # Signup, password login, and Google OAuth 2.0 routes
│   │   │   ├── chat.py                          # Session chat queries and history endpoints
│   │   │   ├── documents.py                     # File uploading and document list endpoints
│   │   │   └── sessions.py                      # Session creation, listing, and closing endpoints
│   │   │
│   │   ├── schemas/
│   │   │   ├── __init__.py
│   │   │   ├── auth_schemas.py                  # Pydantic schemas for authentication
│   │   │   ├── chat_schemas.py                  # Pydantic schemas for messaging
│   │   │   └── session_schemas.py               # Pydantic schemas for sessions
│   │   │
│   │   ├── config.py                            # Unified application environment config
│   │   ├── main.py                              # FastAPI main server entrypoint and route setups
│   │   └── __init__.py
│   │
│   └── requirements.txt                         # Python dependencies
│
├── frontend/
│   │
│   ├── js/
│   │   ├── api.js                               # Centralized fetch functions with JWT headers
│   │   ├── auth.js                              # Auth status checks and tab switching UI logic
│   │   ├── chat.js                              # Chat messages UI rendering and indicators
│   │   ├── dashboard.js                         # File drag-and-drop and session card rendering
│   │   └── utils.js                             # General toasts and formatting utilities
│   │
│   ├── styles/
│   │   ├── chat.css                             # Chat messaging bubbles, scrollbars, textareas, and voice/action states
│   │   ├── common.css                           # Resets, global variables, cards, buttons, inputs, toasts, and spinners
│   │   ├── dashboard.css                        # Upload boundaries, greeting sections, session grids, and badges
│   │   └── index.css                            # Styling for index/login layout and card headers
│   │
│   ├── chat.html                                # PDF Chat interface page
│   ├── dashboard.html                           # Document uploading and history dashboard
│   └── index.html                               # User entry / Auth login page
│
├── storage/                                     # Local storage directories
│   ├── uploads/                                 # Stores uploaded PDF files
│   └── vectorstore/                             # Stores persistent ChromaDB vector indexes
│
├── .gitignore
├── .env
├── .dockerignore
├── Dockerfile
├── docker-compose.yml
├── image1.png

---

Setup Instructions

1. Clone the Repository

git clone https://github.com/Swaroop883/ChatPDF.git
cd ChatPDF

2. Create and Activate Virtual Environment

python -m venv chatpdf-env

# Windows
chatpdf-env\Scripts\activate

# Mac/Linux
source chatpdf-env/bin/activate

3. Install Backend Dependencies

pip install -r backend/requirements.txt

4. Configure Local Environment

Create a .env file in the root directory and configure the environment variables (API keys, Database credentials, JWT settings, Google Client OAuth IDs).

5. Launch Backend Server

Ensure PostgreSQL service is running on your computer, then start the FastAPI application:

cd backend
uvicorn app.main:app --reload

6. Open Frontend

Open frontend/index.html in your web browser.

7. Run using Docker (Alternative)

If you have Docker and Docker Compose installed, you can spin up the entire application (including PostgreSQL) with a single command.

1. Configure your .env file in the project root directory.
2. Build and start the containers:

   docker compose up --build

3. Once the services start up:
   • The web app will be available at: http://localhost:8000/frontend/index.html.
   • The interactive API documentation will be available at: http://localhost:8000/docs.
4. To stop the containers, run:

   docker compose down

---

API Documentation

Method	Endpoint	Description
POST	/auth/register	Create a new user account
POST	/auth/login	Login and receive a JWT token
GET	/auth/google	Login using Google OAuth
GET	/auth/google/callback	Callback handler for Google OAuth callback
POST	/document/upload	Upload and process a PDF
GET	/document/list	List all uploaded documents of the user
POST	/session/create	Start a chat session associated with a document
GET	/session/list	List all user chat sessions
POST	/chat	Submit a question and retrieve standard RAG answer
GET	/history/{session_id}	Fetch full session conversation history
DELETE	/session/close/{session_id}	Close a session and clean up its vector embeddings

---

Future Improvements

1. Voice Interactions (STT & TTS): Use Speech-to-Text and Text-to-Speech models for voice conversation with the agent.
2. React Migration: Port the frontend to React instead of Vanilla HTML/CSS/JS.

---

Author

Built by Swaroop