# anil-matcha/chatpdf architecture

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

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

## Overview

##### Project type and purpose
- This is a small “chat-with-PDF” Python application offering two entry points:
- main.py: a simple script to load a PDF, query it via OpenAI, and print results in the console
- streamlitui.py: a Streamlit-based web UI for uploading a PDF and chatting with it
- It leverages pdfquery.py to parse/extract text and the OpenAI API to answer or summarize user questions.

##### File structure
- Top-level files:
- main.py – CLI launcher
- streamlitui.py – Streamlit app
- pdfquery.py – core PDF ingestion and query logic
- requirements.txt – dependencies (openai, streamlit, pdfquery or pdfminer, etc.)
- Gemini_ChatPDF.ipynb – demo/notebook
- README.md, LICENSE
- No subfolders or persistent databases: all operations are in memory and external via OpenAI.

##### Additional insights from the README
- Purpose: let users “upload any PDF and chat with it”
- Workflow:
1. Read PDF
2. Chunk text & extract embeddings (implicitly)
3. Call OpenAI’s chat/completions endpoint
4. Return answers + “sources included”

a. Main components:
- User Interface
– CLI (main.py)
– Web UI (streamlitui.py)
- PDF Processing Module (pdfquery.py)
- Chat/Query Engine
– Text chunking & embedding (in-memory vector store or on-the-fly)
– OpenAI API client
- External Service
– OpenAI Chat/Completions API
b. Relationships & interactions:
1. User interacts with either CLI or Streamlit UI
2. UI calls PDF Processing Module to extract and chunk text
3. Chat Engine module embeds or sends text+user query to OpenAI
4. OpenAI returns responses and tokenized source references
5. Response flows back up to UI for display
c. Architectural patterns / principles:
- Monolithic Python app with clear separation of concerns (UI vs. ingestion vs. API client)
- Pipeline pattern: ingest → preprocess → call LLM → postprocess
- Stateless per-request design; no persistence beyond runtime
d. Key technologies:
- Python 3.x
- pdfquery (or underlying PDF parsing libs)
- openai Python SDK
- Streamlit for web interface
- (Optional) small in-memory store for chunk embeddings

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        CLIUI["CLI User Interface"]:::firstParty
        StreamlitUI["Streamlit Web User Interface"]:::firstParty
    end

    %% Logic Layer
    subgraph "Logic Layer"
        direction TB
        PDFProcessor["PDF Processing Module"]:::firstParty
        ChatEngine["Chat/Query Engine & OpenAI API Client"]:::firstParty
    end

    %% External Service
    subgraph "External Service"
        direction TB
        OpenAI["OpenAI Chat/Completions API"]:::external
    end

    %% Optional Demo/Documentation
    subgraph "Optional / Documentation"
        direction TB
        Notebook["Demo Jupyter Notebook"]:::optional
        Requirements["Dependency Specification"]:::optional
        README["Project Documentation"]:::optional
        LICENSEFile["License Information"]:::optional
    end

    %% Data Flows
    CLIUI -->|"extract & chunk text"| PDFProcessor
    StreamlitUI -->|"extract & chunk text"| PDFProcessor
    PDFProcessor -->|"prepare prompt & context"| ChatEngine
    ChatEngine -->|"send prompt + context"| OpenAI
    OpenAI -->|"return answer + sources"| ChatEngine
    ChatEngine -->|"return answer + sources"| CLIUI
    ChatEngine -->|"return answer + sources"| StreamlitUI

    %% Optional Demo Flow
    Notebook -.->|"demo ingestion & query"| PDFProcessor

    %% Click Events
    click CLIUI "https://github.com/anil-matcha/chatpdf/blob/main/main.py"
    click StreamlitUI "https://github.com/anil-matcha/chatpdf/blob/main/streamlitui.py"
    click PDFProcessor "https://github.com/anil-matcha/chatpdf/blob/main/pdfquery.py"
    click ChatEngine "https://github.com/anil-matcha/chatpdf/blob/main/pdfquery.py"
    click Notebook "https://github.com/anil-matcha/chatpdf/blob/main/Gemini_ChatPDF.ipynb"
    click Requirements "https://github.com/anil-matcha/chatpdf/blob/main/requirements.txt"
    click README "https://github.com/anil-matcha/chatpdf/blob/main/README.md"
    click LICENSEFile "https://github.com/anil-matcha/chatpdf/tree/main/LICENSE"

    %% Styles
    classDef firstParty fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef external fill:#90EE90,stroke:#000,stroke-width:1px
    classDef optional stroke-dasharray: 5 5,fill:#f9f9f9,stroke:#666,stroke-width:1px
```
