# franklyc/pagewisepdf architecture

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

- Interactive diagram: https://gitdiagram.com/franklyc/pagewisepdf
- Repository: https://github.com/franklyc/pagewisepdf

## Overview

##### Major Components
- Entry Point & Application Bootstrap: Note that run.py is the project’s entry file which initializes the application.
- GUI Layer: The application makes use of PyQt5 for a clean, user-friendly interface. Although not represented by a dedicated “gui” module in the file tree, this component is integral and likely instantiated from within src/main.py.
- Core Logic – Controller/Coordinator: The src/main.py file likely handles overall coordination between the GUI interactions and the processing logic. This component handles user inputs like selecting PDFs, configuring options, and launching processing tasks.
- PDF Processing Module: Outlined in src/pdf_processor.py, this module encapsulates the functionality to extract text, preserving formatting (tables, styles) and handling OCR tasks.
- Configuration & Settings: The src/settings.py module manages API keys, endpoint configurations, and other customizable parameters for the OpenAI Vision API and processing options.
- External Services: This includes the integration with OpenAI's Vision API for OCR as well as other libraries (PyMuPDF for PDF handling, PyQt5 for the GUI).

##### Relationships and Interactions
- The GUI (via PyQt5) interacts with the Controller (main.py) to receive user commands (e.g., file selection, processing options).
- The Controller then invokes functions from the PDF Processor to process the PDF (e.g., OCR, summarization).
- The PDF Processor communicates with external services, particularly the OpenAI Vision API, handling requests for OCR and summarization.
- The Settings component supplies the necessary configuration details (API keys, endpoints, processing parameters) used by both the Controller and the PDF Processor.
- Processed output (markdown files and images) is generated and stored locally, as depicted by the application usage notes.

##### Architectural Patterns and Principles
- Separation of Concerns: Clear division between the user interface (PyQt5), business logic (orchestration in main.py and pdf_processor.py), and settings (configuration management in settings.py).
- Modular Design: Each module is responsible for specific functionality making the system extensible and maintainable.
- External API Integration: Well-defined interaction boundaries with third-party services (OpenAI Vision API) which are critical to the application’s core AI capabilities.

##### Elements
- Clearly Label Components: Mark each module (run.py, main.py, pdf_processor.py, settings.py) along with external libraries and services.
- From user inputs (GUI) to the Controller.
- From the Controller to the PDF processor.
- From PDF processor to external APIs (OpenAI Vision API) and back.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction Layer
    subgraph "User Interaction Layer"
        U("User"):::user
        GUI("PyQt5 GUI"):::gui
    end

    %% Application Core
    subgraph "Application Core"
        Start("run.py"):::local
        Ctrl("Controller"):::local
        Set("Settings"):::local
        PDFProc("PDF Processor"):::local
    end

    %% External Services & Output Layer
    subgraph "External & Output"
        Vision("OpenAI Vision API"):::external
        PDFLib("PyMuPDF"):::external
        Output("Output Generation"):::output
    end

    %% Connections - User and Initialization
    U -->|"input"| GUI
    Start -->|"initializes"| Ctrl
    GUI -->|"triggers"| Ctrl

    %% Connections - Core Application Flow
    Ctrl -->|"retrieves"| Set
    Ctrl -->|"invokes processing in"| PDFProc

    %% Connections - PDF Processing and External Services
    PDFProc -->|"OCR & summarization"| Vision
    PDFProc -->|"extracts text"| PDFLib
    PDFProc -->|"produces"| Output

    %% Click Events for mapped components
    click Start "https://github.com/franklyc/pagewisepdf/blob/main/run.py"
    click Ctrl "https://github.com/franklyc/pagewisepdf/blob/main/src/main.py"
    click PDFProc "https://github.com/franklyc/pagewisepdf/blob/main/src/pdf_processor.py"
    click Set "https://github.com/franklyc/pagewisepdf/blob/main/src/settings.py"

    %% Styles
    classDef user fill:#D3E4CD,stroke:#333,stroke-width:2px;
    classDef gui fill:#FFDDC1,stroke:#333,stroke-width:2px;
    classDef local fill:#CDE7BE,stroke:#333,stroke-width:2px;
    classDef external fill:#B2EBF2,stroke:#333,stroke-width:2px;
    classDef output fill:#F7CAC9,stroke:#333,stroke-width:2px;
```
