# pdfmathtranslate/pdfmathtranslate-next architecture

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

- Interactive diagram: https://gitdiagram.com/pdfmathtranslate/pdfmathtranslate-next
- Repository: https://github.com/pdfmathtranslate/pdfmathtranslate-next

## Overview

##### Project Type and Purpose
- PDFMathTranslate (pdf2zh-next) is a full-stack, Python-based PDF translation tool. It exposes:
a. A command-line interface (CLI) for batch translation of scientific PDFs.
b. An interactive WebUI (via Gradio or similar) for real-time use.
c. A Dockerized deployment for ease of installation.
d. An HTTP API endpoint for integration into other services.
- Core purpose: parse PDF layouts (text, formulas, images), translate content via pluggable translator backends, and reassemble bilingual PDF preserving original formatting.

##### File Structure Analysis
- Top-level:
- Dockerfile + script/ for container images (China, Demo).
- pyproject.toml, setup.cfg: packaging config.
- mkdocs.yml + docs/: multi-language documentation site.
- Python package pdf2zh_next/:
- config/: CLI/env/model definitions and loading.
- main.py, high_level.py: orchestration entrypoints.
- gui.py: launches WebUI.
- http_api.py: HTTP server endpoints.
- translator/:
– base_translator.py, base_rate_limiter.py, cache.py
– rate_limiter/: QPS limiter implementations
– translator_impl/: one module per supported backend (OpenAI, Azure, Google, DeepL, etc.)
- utils/asynchronize/: asynchronous task utilities.
- tests/ and test/: unit and integration tests for config, cache, translator.

##### Architecture Highlights from README
- Plugin-style translator backends, selected at runtime.
- Support for multiple translation services and language codes.
- Three usage modes (CLI, WebUI, HTTP API).

a. Main Components
- Clients:
– CLI client (python -m pdf2zh_next.main)
– WebUI client (browser)
- Application server:
– CLI entrypoint (main.py)
– WebUI server (gui.py)
– HTTP API server (http_api.py)
- Core Orchestrator (high_level.py): document parsing, translation workflow.
- PDF Parser modules: Pdfminer.six, PyMuPDF integrations.
- Translator layer:
– Strategy pattern: base_translator + translator_impl plugins
– Rate limiter + cache subcomponents
- External Services: translation APIs (OpenAI, Azure, Google, Deepl, etc.)
- Output module: reassemble PDF, bilingual comparison, preserve formulas/images.
- Configuration store: CLI args, env vars, pyproject / config models.

b. Relationships & Data Flow
1. User → selects mode (CLI/WebUI/HTTP).
2. Entrypoint loads configuration.
3. Entrypoint calls orchestrator:
– Parse input PDF → internal representation (text blocks, formulas, figures).
– For each text segment: check cache → if miss, select translator_impl → apply rate limiter → call external API → update cache.
4. Merge translated segments with original layout → generate bilingual PDF.
5. Return/download result (stdout file path, WebUI preview, HTTP response).

c. Architectural Patterns
- Strategy pattern for translator backends.
- Decorator-like rate limiting and caching wrappers.
- Asynchronous task management for parallel translations.
- Modular separation: parsing, translation, output, UI/APIs.

d. Key Technologies
- Python 3, asyncio
- Pdfminer.six, PyMuPDF
- HTTP framework (FastAPI or Flask inside http_api.py)
- Gradio or similar for gui.py
- Docker for containerization
- mkdocs for documentation site

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interfaces
    subgraph "User Interfaces"
        CLI["CLI Client"]:::frontend
        WebUI["WebUI Client (Browser)"]:::frontend
        HTTPClient["HTTP Client"]:::frontend
    end

    %% Entrypoints / Servers
    subgraph "Entrypoints / Servers"
        CLIep["CLI Entrypoint (main.py)"]:::frontend
        GUI["WebUI Server (gui.py)"]:::frontend
        API["HTTP API Server (http_api.py)"]:::frontend
    end

    CLI -->|selects mode| CLIep
    WebUI -->|visits| GUI
    HTTPClient -->|calls| API

    %% Configuration Store
    subgraph "Configuration Store"
        ConfigLoad["Config Loader"]:::util
        CLIModel["CLI/Env Models"]:::util
        GenericModel["Generic Models"]:::util
        TransEngineModel["Translate Engine Model"]:::util
    end

    CLIep --> ConfigLoad
    GUI --> ConfigLoad
    API --> ConfigLoad
    ConfigLoad --> CLIModel
    ConfigLoad --> GenericModel
    ConfigLoad --> TransEngineModel

    %% Core Orchestrator & Logic
    subgraph "Core Orchestrator & Logic"
        Orch["Core Orchestrator"]:::core
        Parser["PDF Parser Modules"]:::core
        Output["PDF Assembly & Output"]:::core
    end

    CLIep -->|calls| Orch
    GUI -->|calls| Orch
    API -->|calls| Orch
    Orch -->|parses| Parser
    Parser -->|data| Orch
    Orch -->|assembles| Output
    Output -->|response| CLIep
    Output -->|response| GUI
    Output -->|response| API

    %% Translator Subsystem
    subgraph "Translator Subsystem"
        BT["Translator Strategy Base"]:::core
        RL["Rate Limiter Base"]:::util
        Cache["Translation Cache"]:::util
        QPS["QPS Rate Limiter"]:::util
        subgraph "Translator Plugins"
            Plugins["Concrete Translator Plugins"]:::core
        end
    end

    Orch -->|translates| Cache
    Orch -->|uses| BT
    BT -->|wraps| RL
    RL -->|implements| QPS
    BT -->|selects| Plugins
    Plugins -->|requests| OpenAI
    Plugins -->|requests| Azure
    Plugins -->|requests| Google
    Plugins -->|requests| DeepL
    Plugins -->|requests| OtherTs

    %% External Translation Services
    subgraph "External Translation Services"
        OpenAI["OpenAI API"]:::external
        Azure["Azure Translation"]:::external
        Google["Google Translate"]:::external
        DeepL["DeepL API"]:::external
        OtherTs["Other Services"]:::external
    end

    %% Utilities
    subgraph "Utilities"
        Async["Async Task Utilities"]:::util
    end

    Orch -->|async tasks| Async

    %% Deployment & Documentation
    subgraph "Deployment & Docs"
        Docker["Docker Context"]:::util
        Docs["Documentation Site"]:::util
    end

    %% Click Events
    click CLIep "https://github.com/pdfmathtranslate/pdfmathtranslate-next/blob/main/pdf2zh_next/main.py"
    click GUI "https://github.com/pdfmathtranslate/pdfmathtranslate-next/blob/main/pdf2zh_next/gui.py"
    click API "https://github.com/pdfmathtranslate/pdfmathtranslate-next/blob/main/pdf2zh_next/http_api.py"
    click Orch "https://github.com/pdfmathtranslate/pdfmathtranslate-next/blob/main/pdf2zh_next/high_level.py"
    click CLIModel "https://github.com/pdfmathtranslate/pdfmathtranslate-next/blob/main/pdf2zh_next/config/cli_env_model.py"
    click ConfigLoad "https://github.com/pdfmathtranslate/pdfmathtranslate-next/blob/main/pdf2zh_next/config/main.py"
    click GenericModel "https://github.com/pdfmathtranslate/pdfmathtranslate-next/blob/main/pdf2zh_next/config/model.py"
    click TransEngineModel "https://github.com/pdfmathtranslate/pdfmathtranslate-next/blob/main/pdf2zh_next/config/translate_engine_model.py"
    click BT "https://github.com/pdfmathtranslate/pdfmathtranslate-next/blob/main/pdf2zh_next/translator/base_translator.py"
    click RL "https://github.com/pdfmathtranslate/pdfmathtranslate-next/blob/main/pdf2zh_next/translator/base_rate_limiter.py"
    click Cache "https://github.com/pdfmathtranslate/pdfmathtranslate-next/blob/main/pdf2zh_next/translator/cache.py"
    click Plugins "https://github.com/pdfmathtranslate/pdfmathtranslate-next/tree/main/pdf2zh_next/translator/translator_impl/"
    click QPS "https://github.com/pdfmathtranslate/pdfmathtranslate-next/blob/main/pdf2zh_next/translator/rate_limiter/qps_rate_limiter.py"
    click Async "https://github.com/pdfmathtranslate/pdfmathtranslate-next/tree/main/pdf2zh_next/utils/asynchronize/"
    click Docker "https://github.com/pdfmathtranslate/pdfmathtranslate-next/tree/main/Dockerfile"
    click Docs "https://github.com/pdfmathtranslate/pdfmathtranslate-next/blob/main/mkdocs.yml"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,color:#004085;
    classDef core fill:#d4edda,stroke:#155724,color:#155724;
    classDef external fill:#fff3cd,stroke:#856404,color:#856404;
    classDef util fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
```
