# armaanseth/chatpdf architecture

> Architecture diagram of the GitHub repository armaanseth/chatpdf, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/armaanseth/chatpdf
- Repository: https://github.com/armaanseth/chatpdf

## Overview

##### Project type and purpose
- This is a specialized RAG-powered “PDF Intelligence System” with a lightweight front-end (Streamlit) and a back-end pipeline (in `app.py` + `htmlTemplates.py`).
- Its purpose is to ingest one or more PDF files, index them into a FAISS vector store using Hugging Face embeddings, maintain conversational memory, and forward context plus user queries to OpenAI’s GPT-3.5 Turbo for answer generation.

##### File structure
- Top level files only:
- `app.py` – orchestrates the Streamlit UI, PDF ingestion, vector store creation, memory, and LLM calls.
- `htmlTemplates.py` – contains HTML templates or helper functions for rendering within Streamlit.
- `requirements.txt` – declares dependencies (Streamlit, FAISS, Hugging Face, OpenAI SDK, etc.).
- README, LICENSE, .gitignore – documentation and config.
- No separate “backend” or “frontend” folders; the architecture is embedded in `app.py`.

##### README for additional insights
- Workflow steps are clearly described: PDF → VectorStore (FAISS + all-MiniLM-L6-v2) → Memory Buffer → GPT-3.5 Turbo → Streamlit UI.
- Technologies: FAISS, Hugging Face Embeddings, OpenAI API, Streamlit.

a. Main components
- User Interface (Streamlit front-end)
- PDF Ingestion & Parser
- Chunker & Embedding Service (Hugging Face)
- Vector Store (FAISS)
- Conversation Memory (Buffer to track history)
- LLM Client (OpenAI GPT-3.5 Turbo API)
- Static Helpers (`htmlTemplates.py`)
- External Services (OpenAI, Hugging Face, FAISS library runtime)
b. Relationships & interactions
1. UI → PDF Ingestion: User uploads PDF(s) and submits a query.
2. Parser → Chunk & Embed: PDF text is chunked and passed to the Embedding Service.
3. Embedding Service → Vector Store: Embeddings are stored in FAISS.
4. On query: UI passes query + conversation history → Vector Store → retrieves top‐k relevant chunks.
5. Retrieved chunks + memory buffer → LLM Client → response.
6. LLM response → UI via htmlTemplates for display.
c. Architectural patterns & design principles
- Pipeline Pattern: clearly delineated stages (ingest → embed → index → retrieve → generate → display).
- Modularity: separation of concerns between UI, processing logic, storage, and third-party integrations.
- Retrieval-Augmented Generation: tightly couples retrieval (FAISS) with generation (GPT-3.5).
d. Key technologies/frameworks
- Streamlit for UI
- PyPDF (or similar) PDF parsing libraries inside `app.py`
- Hugging Face’s all-MiniLM-L6-v2 Embeddings model
- FAISS vector store
- OpenAI Python SDK (GPT-3.5 Turbo)
- Python standard libraries and helper templates in `htmlTemplates.py`

## Diagram (Mermaid)

```mermaid
flowchart TD
    UI["User Interface<br>(Streamlit UI)"]:::ui
    Parser["PDF Ingestion & Parser"]:::process
    Chunker["Chunker & Embedding Service"]:::process
    HF["Hugging Face Embedding Service"]:::external
    VectorStore["Vector Store<br>(FAISS)"]:::storage
    Memory["Conversation Memory Buffer"]:::process
    LLM["LLM Client<br>(OpenAI GPT-3.5 Turbo)"]:::external
    OpenAI["OpenAI API"]:::external
    StaticHelpers["Static Helpers<br>(htmlTemplates.py)"]:::ui
    Requirements["requirements.txt"]:::external
    README["README.md"]:::external
    LICENSE["LICENSE"]:::external

    UI -->|"upload PDF(s)"| Parser
    Parser -->|"text chunks"| Chunker
    Chunker -->|"requests embeddings"| HF
    HF -->|"vector embeddings"| VectorStore
    UI -->|"user query"| VectorStore
    VectorStore -->|"top-k chunks"| Memory
    Memory -->|"history+chunks"| LLM
    LLM -->|"API call"| OpenAI
    OpenAI -->|"response JSON"| LLM
    LLM -->|"generated response"| StaticHelpers
    StaticHelpers -->|"render HTML"| UI

    click UI "https://github.com/armaanseth/chatpdf/blob/main/app.py"
    click Parser "https://github.com/armaanseth/chatpdf/blob/main/app.py"
    click Chunker "https://github.com/armaanseth/chatpdf/blob/main/app.py"
    click VectorStore "https://github.com/armaanseth/chatpdf/blob/main/app.py"
    click Memory "https://github.com/armaanseth/chatpdf/blob/main/app.py"
    click LLM "https://github.com/armaanseth/chatpdf/blob/main/app.py"
    click StaticHelpers "https://github.com/armaanseth/chatpdf/blob/main/htmlTemplates.py"
    click Requirements "https://github.com/armaanseth/chatpdf/blob/main/requirements.txt"
    click README "https://github.com/armaanseth/chatpdf/blob/main/README.md"
    click LICENSE "https://github.com/armaanseth/chatpdf/tree/main/LICENSE"

    classDef ui fill:#BBDEFB,stroke:#000,stroke-width:1px
    classDef process fill:#C8E6C9,stroke:#000,stroke-width:1px
    classDef storage fill:#FFE0B2,stroke:#000,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#000,stroke-width:1px
```
