# wuomzfx/pdfgpt architecture

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

- Interactive diagram: https://gitdiagram.com/wuomzfx/pdfgpt
- Repository: https://github.com/wuomzfx/pdfgpt

## Overview

##### Main Components

a. Input and Configuration:
- Configuration Loader: The file tree includes a config.js (while the README mentions config.json). This part of the system manages API credentials (e.g., the apiKey) and question definitions, essentially governing the project’s runtime behavior.

b. Processing Modules:
- PDF Processing Module: The utility (in utils/pdf.js) deals with reading and parsing the PDF file to extract its content.
- Content & Embedding Module: Modules like utils/content.js and utils/embedding.js process the extracted text – possibly segmenting content and generating vector embeddings for later use in question answering.
- Cache Module: The cache directory (with cache/index.js) likely stores intermediate results (such as already processed embeddings or parsed content) to speed up repeated runs.

c. Execution Scripts (Orchestration):
- Load Script: scripts/load.js – This script likely triggers PDF processing, text extraction, and embedding generation, acting as the “loading” phase.
- Ask Script: scripts/ask.js – Once the data is prepared, this script interacts with OpenAI via modules like utils/openai.js and utils/ai.js to process the given questions and generate outputs.

d. Output:
- Answer Storage: According to the README, the final answers are stored under an answerFiles directory (even if not part of the static file tree), representing where the processed results are logged.
- Log & Utility Modules: Additional utilities such as utils/fs.js and utils/tree.js help manage file operations and directory traversals.

##### Relationships and Data Flow

- The process starts with the user providing a PDF in the proper folder and setting parameters (via the config file).
- The Load Script (npm run load) uses the PDF Processing Module to extract text and then employs the Embedding/Content module. Results are cached (cache directory) for efficiency.
- Once the document has been processed, the Ask Script (npm run ask) uses the generated content along with the configuration-specified questions. This script leverages the OpenAI integration (via utils/openai.js and related modules) to generate answers.
- The final answers are then written out to a designated output directory (answerFiles).

##### Architectural Patterns and Design Principles

- Modular Design: The project is neatly divided into modules (scripts, utils, cache) with each one handling a distinct responsibility.
- Two-Phase Pipeline: The architecture follows a clear pipeline – first a “load” phase (data acquisition, conversion, and embedding) and then an “ask” phase (query processing and answer generation).
- External Service Integration: The project integrates with external APIs (OpenAI) for natural language processing, implying that the API client (utils/openai.js) is a critical component.
- Reusability and Extensibility: The presence of various utility files indicates that the system is designed with separation of concerns, making it easy to extend or swap components.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Input Components
    A["PDF Input"]:::input
    B["Configuration Loader"]:::input

    %% Load Phase Subgraph
    subgraph "Load Phase"
        C["Load Script"]:::script
        D["PDF Processor"]:::processor
        E["Content Processor"]:::processor
        F["Embedding Processor"]:::processor
        G["Cache Module"]:::cache
        C --> D
        D --> E
        E --> F
        F --> G
    end

    %% Ask Phase Subgraph
    subgraph "Ask Phase"
        H["Ask Script"]:::script
        I["OpenAI Integration"]:::external
        J["Answer Storage"]:::storage
        H --> I
        H --> J
    end

    %% Utility Component
    K["File System Utilities"]:::utility

    %% Data Flow Connections
    A -->|"provides PDF"| C
    B -->|"provides config"| C
    C ---|"uses"| K
    H ---|"uses"| K
    C -->|"processed data"| H

    %% Click Events
    click B "https://github.com/wuomzfx/pdfgpt/blob/main/config.js"
    click D "https://github.com/wuomzfx/pdfgpt/blob/main/utils/pdf.js"
    click E "https://github.com/wuomzfx/pdfgpt/blob/main/utils/content.js"
    click F "https://github.com/wuomzfx/pdfgpt/blob/main/utils/embedding.js"
    click G "https://github.com/wuomzfx/pdfgpt/blob/main/cache/index.js"
    click C "https://github.com/wuomzfx/pdfgpt/blob/main/scripts/load.js"
    click H "https://github.com/wuomzfx/pdfgpt/blob/main/scripts/ask.js"
    click I "https://github.com/wuomzfx/pdfgpt/blob/main/utils/openai.js"
    click K "https://github.com/wuomzfx/pdfgpt/blob/main/utils/fs.js"

    %% Styles
    classDef input fill:#c2f0c2,stroke:#333,stroke-width:2px;
    classDef script fill:#f9e79f,stroke:#333,stroke-width:2px;
    classDef processor fill:#aed6f1,stroke:#333,stroke-width:2px;
    classDef cache fill:#f5cba7,stroke:#333,stroke-width:2px;
    classDef external fill:#d7bde2,stroke:#333,stroke-width:2px;
    classDef storage fill:#d5f5e3,stroke:#333,stroke-width:2px;
    classDef utility fill:#fef9e7,stroke:#333,stroke-width:2px;
```
