# spiral-edwin/patt-pdf architecture

> Architecture diagram of the GitHub repository spiral-edwin/patt-pdf, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/spiral-edwin/patt-pdf
- Repository: https://github.com/spiral-edwin/patt-pdf

## Overview

PATT-PDF is a command-line PDF translation tool that replaces English text with Chinese while preserving page layout. The user workflow runs through CLI commands or the one-command `run` flow: plan PDF pages, estimate and confirm translation, translate with a selected backend, render replacements, run QA, then report or publish. Internally, text and OCR extraction feed grouping and keep rules; rendering uses font and decoration support. The README also documents offline/manual and pseudo backends, character limits, caching, and page selection. Some subsystem links rely on SOURCE INDEX references because their implementation excerpts were not provided.

Main entry points: [`src/patt_pdf/render.py`](https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/render.py) (PDF rendering), [`src/patt_pdf/jobs.py`](https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/jobs.py) (Job orchestration), [`src/patt_pdf/ocr.py`](https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/ocr.py) (OCR planning), [`src/patt_pdf/cli.py`](https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/cli.py) (CLI commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["User workflow"]
  node_cli["CLI commands<br/>[cli.py]"]
  node_run_flow["Run workflow<br/>[runcmd.py]"]
  node_jobs["Job orchestration<br/>[jobs.py]"]
  node_report["Reports<br/>[report.py]"]
  node_qa["Page QA<br/>[qa.py]"]
  node_sanity["Translation checks<br/>[sanity.py]"]
end

subgraph group_translation["Translation services"]
  node_translation_memory[("Translation memory<br/>[tm.py]")]
  node_backends["Translation backends<br/>[backends.py]"]
end

subgraph group_page_analysis["Page analysis"]
  node_analyze["Page planning<br/>[analyze.py]"]
  node_extract_text["Text extraction<br/>[extract_text.py]"]
  node_ocr["OCR planning<br/>[ocr.py]"]
  node_grouping["Text grouping<br/>[grouping.py]"]
  node_classification["Page classification<br/>[classify.py]"]
  node_keep_rules["Keep rules<br/>[keep.py]"]
  node_data_model["Plan data model<br/>[model.py]"]
  node_tables["Table analysis<br/>[tables.py]"]
end

subgraph group_rendering["PDF rendering"]
  node_render["PDF rendering<br/>[render.py]"]
  node_decor["Decoration handling<br/>[decor.py]"]
  node_fonts["CJK fonts<br/>[fonts.py]"]
  node_typeset["Typesetting<br/>[typeset.py]"]
  node_osenv["OS environment<br/>[osenv.py]"]
end

node_user(("PDF operator"))
node_deepl{{"DeepL API"}}
node_tesseract{{"Tesseract"}}

node_user -->|"invokes"| node_cli
node_cli -->|"dispatches"| node_jobs
node_cli -->|"selects"| node_backends
node_cli -->|"requests"| node_report
node_cli -->|"uses"| node_translation_memory
node_run_flow -->|"orchestrates"| node_jobs
node_jobs -->|"plans pages"| node_analyze
node_jobs -->|"translates via"| node_backends
node_jobs -->|"uses"| node_translation_memory
node_jobs -->|"renders with"| node_render
node_jobs -->|"checks output"| node_qa
node_backends -->|"sends text"| node_deepl
node_analyze -->|"extracts"| node_extract_text
node_analyze -->|"plans scans"| node_ocr
node_analyze -->|"classifies"| node_classification
node_extract_text -->|"groups text"| node_grouping
node_extract_text -->|"filters keeps"| node_keep_rules
node_extract_text -->|"uses"| node_tables
node_extract_text -->|"builds plans"| node_data_model
node_ocr -->|"runs OCR"| node_tesseract
node_ocr -->|"groups OCR"| node_grouping
node_ocr -->|"filters keeps"| node_keep_rules
node_ocr -->|"builds plans"| node_data_model
node_render -->|"uses"| node_grouping
node_render -->|"restores keeps"| node_keep_rules
node_render -->|"uses OCR data"| node_ocr
node_render -->|"handles decorations"| node_decor
node_render -->|"draws with"| node_fonts
node_render -->|"typesets text"| node_typeset
node_decor -->|"uses"| node_fonts
node_fonts -->|"finds fonts via"| node_osenv

click node_cli "https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/cli.py"
click node_run_flow "https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/runcmd.py"
click node_jobs "https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/jobs.py"
click node_report "https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/report.py"
click node_translation_memory "https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/tm.py"
click node_backends "https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/backends.py"
click node_analyze "https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/analyze.py"
click node_extract_text "https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/extract_text.py"
click node_ocr "https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/ocr.py"
click node_grouping "https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/grouping.py"
click node_classification "https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/classify.py"
click node_keep_rules "https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/keep.py"
click node_data_model "https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/model.py"
click node_tables "https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/tables.py"
click node_qa "https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/qa.py"
click node_sanity "https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/sanity.py"
click node_render "https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/render.py"
click node_decor "https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/decor.py"
click node_fonts "https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/fonts.py"
click node_typeset "https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/typeset.py"
click node_osenv "https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/osenv.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_run_flow,node_jobs,node_report,node_qa,node_sanity toneBlue
class node_translation_memory,node_backends toneAmber
class node_analyze,node_extract_text,node_ocr,node_grouping,node_classification,node_keep_rules,node_data_model,node_tables,node_deepl toneMint
class node_render,node_decor,node_fonts,node_typeset,node_osenv toneRose
class node_user,node_tesseract toneIndigo
```

## Components

### User workflow

- [CLI commands](https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/cli.py): `src/patt_pdf/cli.py`
- [Run workflow](https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/runcmd.py): `src/patt_pdf/runcmd.py`
- [Job orchestration](https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/jobs.py): `src/patt_pdf/jobs.py`
- [Reports](https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/report.py): `src/patt_pdf/report.py`
- [Page QA](https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/qa.py): `src/patt_pdf/qa.py`
- [Translation checks](https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/sanity.py): `src/patt_pdf/sanity.py`

### Translation services

- [Translation memory](https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/tm.py): `src/patt_pdf/tm.py`
- [Translation backends](https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/backends.py): `src/patt_pdf/backends.py`

### Page analysis

- [Page planning](https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/analyze.py): `src/patt_pdf/analyze.py`
- [Text extraction](https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/extract_text.py): `src/patt_pdf/extract_text.py`
- [OCR planning](https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/ocr.py): `src/patt_pdf/ocr.py`
- [Text grouping](https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/grouping.py): `src/patt_pdf/grouping.py`
- [Page classification](https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/classify.py): `src/patt_pdf/classify.py`
- [Keep rules](https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/keep.py): `src/patt_pdf/keep.py`
- [Plan data model](https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/model.py): `src/patt_pdf/model.py`
- [Table analysis](https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/tables.py): `src/patt_pdf/tables.py`

### PDF rendering

- [PDF rendering](https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/render.py): `src/patt_pdf/render.py`
- [Decoration handling](https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/decor.py): `src/patt_pdf/decor.py`
- [CJK fonts](https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/fonts.py): `src/patt_pdf/fonts.py`
- [Typesetting](https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/typeset.py): `src/patt_pdf/typeset.py`
- [OS environment](https://github.com/spiral-edwin/patt-pdf/blob/main/src/patt_pdf/osenv.py): `src/patt_pdf/osenv.py`

### Other components

- **PDF operator**
- **DeepL API**
- **Tesseract**

## Connections

- PDF operator → CLI commands: invokes (evidence: `README.md`)
- CLI commands → Job orchestration: dispatches (evidence: `src/patt_pdf/cli.py`)
- CLI commands → Translation backends: selects (evidence: `src/patt_pdf/cli.py`)
- CLI commands → Reports: requests (evidence: `src/patt_pdf/cli.py`)
- CLI commands → Translation memory: uses (evidence: `src/patt_pdf/cli.py`)
- Run workflow → Job orchestration: orchestrates (evidence: `src/patt_pdf/runcmd.py`)
- Job orchestration → Page planning: plans pages (evidence: `src/patt_pdf/jobs.py`)
- Job orchestration → Translation backends: translates via (evidence: `src/patt_pdf/jobs.py`)
- Job orchestration → Translation memory: uses (evidence: `src/patt_pdf/jobs.py`)
- Job orchestration → PDF rendering: renders with (evidence: `src/patt_pdf/jobs.py`)
- Job orchestration → Page QA: checks output (evidence: `src/patt_pdf/jobs.py`)
- Translation backends → DeepL API: sends text (evidence: `src/patt_pdf/backends.py`)
- Page planning → Text extraction: extracts (evidence: `src/patt_pdf/analyze.py`)
- Page planning → OCR planning: plans scans (evidence: `src/patt_pdf/analyze.py`)
- Page planning → Page classification: classifies (evidence: `src/patt_pdf/analyze.py`)
- Text extraction → Text grouping: groups text (evidence: `src/patt_pdf/extract_text.py`)
- Text extraction → Keep rules: filters keeps (evidence: `src/patt_pdf/extract_text.py`)
- Text extraction → Table analysis: uses (evidence: `src/patt_pdf/extract_text.py`)
- Text extraction → Plan data model: builds plans (evidence: `src/patt_pdf/extract_text.py`)
- OCR planning → Tesseract: runs OCR (evidence: `src/patt_pdf/ocr.py`)
- OCR planning → Text grouping: groups OCR (evidence: `src/patt_pdf/ocr.py`)
- OCR planning → Keep rules: filters keeps (evidence: `src/patt_pdf/ocr.py`)
- OCR planning → Plan data model: builds plans (evidence: `src/patt_pdf/ocr.py`)
- PDF rendering → Text grouping: uses (evidence: `src/patt_pdf/render.py`)
- PDF rendering → Keep rules: restores keeps (evidence: `src/patt_pdf/render.py`)
- PDF rendering → OCR planning: uses OCR data (evidence: `src/patt_pdf/render.py`)
- PDF rendering → Decoration handling: handles decorations (evidence: `src/patt_pdf/render.py`)
- PDF rendering → CJK fonts: draws with (evidence: `src/patt_pdf/render.py`)
- PDF rendering → Typesetting: typesets text (evidence: `src/patt_pdf/render.py`)
- Decoration handling → CJK fonts: uses (evidence: `src/patt_pdf/decor.py`)
- CJK fonts → OS environment: finds fonts via (evidence: `src/patt_pdf/fonts.py`)
