# poppanda/llm_pdf_translator architecture

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

- Interactive diagram: https://gitdiagram.com/poppanda/llm_pdf_translator
- Repository: https://github.com/poppanda/llm_pdf_translator

## Overview

##### Project Type and Purpose
- This is a full-stack Python application (“LLM PDF Translator”) that exposes a web GUI and REST API for translating PDF files while preserving layout.
- Key subsystems: PDF ingestion (upload or URL download), layout analysis (UniLM DiT or VGT), OCR (PaddleOCR), LLM translation (OpenAI, Ollama, QWEN, Google), PDF rendering (ReportLab), plus CLI/batch utilities.

##### File Structure Analysis
- Top-level scripts:
- server.py – launches FastAPI/uvicorn server and defines TranslateApi class
- cli.py / batch.py – command-line and batch translation scripts
- Makefile / Dockerfile – build, model download, docker run targets
- Directories:
- models/ – prebuilt ONNX models for OCR and configuration files for layout models
- modules/ – pluggable engines (layout, ocr, render, translate) implementing common interfaces
- pdf_operation/ – basic PDF utilities (merge, add blank page)
- utils/ – low-level helpers: database logging, Ditod/VGT model loading & training helpers, PaddleOCR ONNX integration, GUI support
- Config and assets:
- config.yaml – runtime settings for translation provider, fonts, threading
- assets/ – screenshots and GUI assets

##### README Insights
- Single-process separation of OCR/layout and translation to conserve VRAM
- Multi-threaded translation engine for LLM calls
- Supported translation providers: Ollama, OpenAI GPT, QWEN, Google Translate
- Layout engine: UniLM DiT (future VGT support)
- OCR engine: PaddleOCR ONNX
- Renderer: ReportLab

##### Main Components
a. Client Layer
- Web GUI (browser) – built into server, serves upload/download pages
- CLI/Batch clients – command-line scripts invoking TranslateApi
b. API / Orchestrator
- FastAPI server (server.py) hosting endpoints and orchestrating workflow
- Configuration loader (config.yaml)
c. Worker Processes
- OCR/Layout Worker – standalone process that loads layout and OCR models from models/; invoked by orchestrator; killed before translation to free VRAM
- Translation Engine Pool – multi-threaded clients invoking external APIs or local LLMs (OpenAI, Ollama, QWEN, Google) via modules/translate
d. Core Workflow Modules
- PDF Operation (pdf_operation/) – splitting, merging, page handling
- Layout Detection (modules/layout) – DiT or VGT detector
- OCR (modules/ocr) – PaddleOCR inference via ONNX
- Text Extraction & Post-processing (utils/ocr_model/ppocr_onnx)
- LLM Translation (modules/translate) – abstraction over API clients
- Reference Checking (LLM-based skip logic)
- Rendering (modules/render) – ReportLab-based PDF recreation with translated text, embedded fonts
e. Data Stores & Temp
- Temporary file directory – intermediate page images, JSON layout/OCR outputs
- models/ folder – local ONNX weights and config files
- utils/database – local SQLite (or similar) for request logging, file status
f. External Services
- OpenAI API
- Ollama local LLM
- QWEN API
- Google Translate API

##### Interactions and Data Flow
1. Client → Server API (upload PDF or URL)
2. Server API → PDF Operation: split source PDF into pages/images
3. Server API spawns OCR/Layout Worker:
- OCR → raw text + positional metadata
4. Worker returns layout+OCR JSON to orchestrator
5. Orchestrator kills OCR/Layout process → frees VRAM
6. Orchestrator → Translation Engine Pool (multi-threaded):
- For each text block, invoke selected translation provider
- Perform LLM-based reference detection and skip logic
7. Translated text + layout metadata → Renderer → output PDF
8. Orchestrator → persists logs to utils/database
9. Server → returns translated PDF (download)

##### Architectural Patterns and Design Principles
- Modular “strategy” pattern: interchangeable modules under modules/layout, modules/ocr, modules/translate, modules/render
- Process isolation: OCR/Layout decoupled from translation to reduce GPU memory footprint
- Thread pool for I/O-bound translation calls
- Configuration-driven design (config.yaml)
- CLI & GUI share the same TranslateApi core

- Threading boundary around Translation Engine Pool

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Layer"
        GUI["Web GUI (Browser)"]:::internal
        CLI["CLI/Batch Clients"]:::internal
    end

    subgraph "API / Orchestrator"
        API["FastAPI Orchestrator"]:::internal
        Config["Configuration Loader"]:::internal
    end

    subgraph "PDF Operation"
        AddBlank["Add Blank Page"]:::internal
        MergePDF["Split/Merge PDF"]:::internal
    end

    subgraph "OCR/Layout Worker"
        LayoutEngine["Layout Detection\n(modules/layout)"]:::internal_iso
        OCREngine["OCR Engine\n(modules/ocr)"]:::internal_iso
    end

    subgraph "Translation Engine Pool"
        TransPool["Translation Pool\n(modules/translate)"]:::internal
    end

    subgraph "PDF Renderer"
        Renderer["PDF Renderer\n(modules/render)"]:::internal
    end

    subgraph "Storage & Models"
        Temp["Temporary Storage\n(temp/)"]:::datastore
        Models["Models Folder\n(models/)"]:::datastore
        DB["Database / Logging\n(utils/database)"]:::datastore
    end

    subgraph "External Services"
        OpenAI["OpenAI API"]:::external
        Ollama["Ollama LLM"]:::external
        QWEN["QWEN API"]:::external
        Google["Google Translate API"]:::external
    end

    GUI --> API
    CLI --> API
    API --> Config
    API --> AddBlank
    API --> MergePDF
    AddBlank --> API
    MergePDF --> API
    API -->|"PDF pages"| LayoutEngine
    LayoutEngine -->|"bboxes"| OCREngine
    OCREngine -->|"OCR JSON"| API
    API --> TransPool
    TransPool -->|"translated text"| Renderer
    Renderer -->|"PDF"| API
    API --> DB
    API --> Temp
    TransPool --> OpenAI
    TransPool --> Ollama
    TransPool --> QWEN
    TransPool --> Google

    click GUI "https://github.com/poppanda/llm_pdf_translator/blob/main/server.py"
    click GUI "https://github.com/poppanda/llm_pdf_translator/blob/main/utils/gui.py"
    click GUI "https://github.com/poppanda/llm_pdf_translator/tree/main/assets/"
    click CLI "https://github.com/poppanda/llm_pdf_translator/blob/main/cli.py"
    click CLI "https://github.com/poppanda/llm_pdf_translator/blob/main/batch.py"
    click CLI "https://github.com/poppanda/llm_pdf_translator/blob/main/cli_operation/single.py"
    click API "https://github.com/poppanda/llm_pdf_translator/blob/main/server.py"
    click Config "https://github.com/poppanda/llm_pdf_translator/blob/main/config.yaml"
    click AddBlank "https://github.com/poppanda/llm_pdf_translator/blob/main/pdf_operation/add_front_blank_page.py"
    click MergePDF "https://github.com/poppanda/llm_pdf_translator/blob/main/pdf_operation/merge_pdf.py"
    click LayoutEngine "https://github.com/poppanda/llm_pdf_translator/blob/main/modules/layout/ditod.py"
    click OCREngine "https://github.com/poppanda/llm_pdf_translator/blob/main/modules/ocr/paddle.py"
    click TransPool "https://github.com/poppanda/llm_pdf_translator/blob/main/modules/translate/base.py"
    click OpenAI "https://github.com/poppanda/llm_pdf_translator/blob/main/modules/translate/openai_gpt.py"
    click Ollama "https://github.com/poppanda/llm_pdf_translator/blob/main/modules/translate/ollama_translate.py"
    click QWEN "https://github.com/poppanda/llm_pdf_translator/blob/main/modules/translate/qwen_translate.py"
    click Google "https://github.com/poppanda/llm_pdf_translator/blob/main/modules/translate/google_translate.py"
    click Renderer "https://github.com/poppanda/llm_pdf_translator/blob/main/modules/render/reportlab.py"
    click DB "https://github.com/poppanda/llm_pdf_translator/blob/main/utils/database/base.py"

    classDef internal fill:#D6EAF8,stroke:#1B4F72
    classDef external fill:#D5F5E3,stroke:#145A32
    classDef datastore fill:#FCF3CF,stroke:#B7950B
    classDef internal_iso fill:#D6EAF8,stroke:#1B4F72,stroke-dasharray: 5 5
```
