# wxyhgk/retain-pdf architecture

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

- Interactive diagram: https://gitdiagram.com/wxyhgk/retain-pdf
- Repository: https://github.com/wxyhgk/retain-pdf

## Overview

#### Purpose and delivery surfaces
RetainPDF translates PDFs while preserving layout, targeting scanned/image PDFs, complex inline math, code protection, and controlled table/layout handling. It ships as a Docker web deployment and an Electron desktop app. Primary production UI is `frontend/`; `frontend-react/` is a separate Vite migration track, not the current replacement.
- `docker/delivery/docker-compose.yml`
- `desktop/main.js`
- `frontend/src/pages/home/entry.tsx`

#### User-facing entry points
The production frontend has three React SPA entries: home/upload/workflow, job detail, and reader. It consumes the Rust HTTP API for uploads, job creation/control, live status, library data, artifacts, glossary management, and reader AI. Desktop loads the frontend bundle and starts/manages local backend runtime.
- `frontend/src/pages/home/entry.tsx`
- `frontend/src/pages/detail/entry.tsx`
- `frontend/src/pages/reader/entry.tsx`
- `desktop/src/main/backend-runtime.js`

#### Rust API: system-of-record and orchestration boundary
The Rust service is the authoritative API, persistence, artifact, and job-lifecycle layer. Its router exposes request boundaries; services translate API commands/queries into database records, storage paths, artifact responses, and background job launches. The runner plans stage execution, runs Python worker processes, parses their structured stdout, records failures, supports cancellation/retry/resume, and emits job events.
- `backend/rust_api/src/main.rs`
- `backend/rust_api/src/app/router.rs`
- `backend/rust_api/src/services/jobs/facade.rs`
- `backend/rust_api/src/job_runner/mod.rs`
- `backend/rust_api/src/db/schema.rs`

#### Pipeline contract and canonical document model
Python workers implement the document-processing pipeline behind a process/event contract rather than being called directly by clients. OCR provider outputs are normalized into `document.v1`, the shared intermediate representation consumed by translation and rendering. Stage entrypoints support whole-document flow plus individual OCR, translation, normalization, and render invocations; Rust builds and launches these commands.
- `backend/scripts/services/document_schema/document.v1.schema.json`
- `backend/scripts/services/document_schema/normalize_pipeline.py`
- `backend/scripts/entrypoints/run_document_flow.py`
- `backend/rust_api/src/worker_command/stage_commands.rs`

#### OCR and normalization stage
OCR is pluggable: Rust owns provider catalog/configuration, remote polling/download/retry behavior, and normalized artifact handoff. Implemented integrations include MinerU and Paddle; Python adapters map provider-specific payloads and layout semantics into the canonical document model. This is the boundary for adding providers without coupling translation/rendering to vendor payloads.
- `backend/rust_api/src/ocr_provider/catalog.rs`
- `backend/rust_api/src/job_runner/ocr_flow/mod.rs`
- `backend/scripts/services/ocr_provider/provider_pipeline.py`
- `backend/scripts/services/document_schema/provider_adapters/paddle/adapter.py`

#### Translation stage
Translation reads normalized OCR blocks, applies policy classification, glossary/term preservation, formula placeholders, context and continuation handling, then batches LLM calls with retries and validation. Results are canonicalized and applied as translation artifacts with diagnostics and repair/review paths. DeepSeek is the concrete LLM provider visible in the repository; prompts and provider runtime remain in Python.
- `backend/scripts/services/translation/workflow/translation_workflow.py`
- `backend/scripts/services/translation/llm/shared/orchestration/retrying_translator.py`
- `backend/scripts/services/translation/llm/providers/deepseek/translation_client.py`
- `backend/scripts/services/translation/services/results/applier.py`

#### Rendering, artifacts, and reading
Rendering analyzes source PDF pages, determines cleanup/overlay/layout routes, fits translated blocks, and emits Typst-based overlays/final PDFs. PDF cleanup and source preservation are separate from layout payload generation; Typst compilation is the final rendering boundary. Rust registers artifacts and provides downloads, previews, side-by-side outputs, library projections, and reader-region/AI APIs.
- `backend/scripts/runtime/pipeline/render_stage.py`
- `backend/scripts/services/rendering/workflow/executor.py`
- `backend/scripts/services/rendering/output/typst/compiler.py`
- `backend/rust_api/src/services/artifacts/registry.rs`
- `backend/rust_api/src/services/jobs/reader_ai.rs`

#### Infrastructure and operational boundaries
Runtime spans Rust, Python, Node/React, Electron, Typst, packaged fonts, and PDF/OCR dependencies. Docker separates app/API and web images behind Nginx; desktop provisions local backend/Python dependencies. Job data, uploads, event logs, and artifacts are filesystem/database-backed through Rust storage abstractions rather than exposed directly to the UI.
- `docker/Dockerfile.app`
- `docker/Dockerfile.web`
- `docker/nginx.conf.template`
- `backend/rust_api/src/storage_paths/registry.rs`
- `desktop/src/main/python-runtime.js`

Main entry points: [`backend/rust_api/src/job_runner/mod.rs`](https://github.com/wxyhgk/retain-pdf/blob/main/backend/rust_api/src/job_runner/mod.rs) (Job runner), [`backend/rust_api/src/app/router.rs`](https://github.com/wxyhgk/retain-pdf/blob/main/backend/rust_api/src/app/router.rs) (API router), [`backend/scripts/entrypoints/run_document_flow.py`](https://github.com/wxyhgk/retain-pdf/blob/main/backend/scripts/entrypoints/run_document_flow.py) (Document flow worker), [`backend/rust_api/src/services/jobs/facade.rs`](https://github.com/wxyhgk/retain-pdf/blob/main/backend/rust_api/src/services/jobs/facade.rs) (Job services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_delivery["Delivery surfaces"]
  node_docker["Docker deployment<br/>container deployment<br/>[docker-compose.yml]"]
  node_desktop["Electron desktop<br/>desktop runtime<br/>[main.js]"]
  node_desktop_backend["Local backend runtime<br/>desktop process manager<br/>[backend-runtime.js]"]
end

subgraph group_client["Client applications"]
  node_frontend["Production React SPA<br/>web client<br/>[entry.tsx]"]
end

subgraph group_api["Rust orchestration"]
  node_rust_api{{"Rust HTTP API<br/>system of record<br/>[main.rs]"}}
  node_router["API router<br/>request boundary<br/>[router.rs]"]
  node_job_facade["Job services<br/>application service<br/>[facade.rs]"]
  node_job_runner["Job runner<br/>pipeline orchestrator<br/>[mod.rs]"]
  node_worker_commands["Worker stage commands<br/>process command builder<br/>[stage_commands.rs]"]
  node_ocr_catalog["OCR provider catalog<br/>provider configuration<br/>[catalog.rs]"]
  node_storage[("Storage and database<br/>persistence layer<br/>[registry.rs]")]
  node_artifacts["Artifact registry<br/>artifact service<br/>[registry.rs]"]
  node_reader_ai["Reader AI service<br/>reader service<br/>[reader_ai.rs]"]
end

subgraph group_pipeline["Python document pipeline"]
  node_document_flow["Document flow worker<br/>pipeline entrypoint"]
  node_ocr_normalization["OCR normalization<br/>OCR adapter pipeline"]
  node_document_model["document.v1<br/>canonical document model"]
  node_translation["Translation workflow<br/>LLM translation stage"]
  node_deepseek["DeepSeek client<br/>LLM provider"]
  node_rendering["Rendering workflow<br/>PDF render stage<br/>[executor.py]"]
  node_typst["Typst compiler<br/>PDF compilation boundary<br/>[compiler.py]"]
end

node_docker -->|"serves"| node_frontend
node_docker -->|"runs"| node_rust_api
node_desktop -->|"manages"| node_desktop_backend
node_desktop_backend -->|"starts locally"| node_rust_api
node_desktop -->|"loads bundle"| node_frontend
node_frontend -->|"HTTP API"| node_router
node_router -->|"commands and queries"| node_job_facade
node_router -->|"artifact access"| node_artifacts
node_router -->|"reader requests"| node_reader_ai
node_job_facade -->|"launches jobs"| node_job_runner
node_job_facade -->|"persists jobs"| node_storage
node_job_runner -->|"builds process commands"| node_worker_commands
node_job_runner -->|"selects provider"| node_ocr_catalog
node_job_runner -->|"runs Python worker"| node_document_flow
node_document_flow -->|"OCR stage"| node_ocr_normalization
node_ocr_normalization -->|"normalizes to"| node_document_model
node_document_flow -->|"translation stage"| node_translation
node_translation -->|"reads and applies translations"| node_document_model
node_translation -->|"LLM calls"| node_deepseek
node_document_flow -->|"render stage"| node_rendering
node_rendering -->|"uses layout blocks"| node_document_model
node_rendering -->|"compiles output"| node_typst
node_typst -->|"registered output"| node_artifacts
node_job_runner -->|"events and failures"| node_storage

click node_docker "https://github.com/wxyhgk/retain-pdf/blob/main/docker/delivery/docker-compose.yml"
click node_desktop "https://github.com/wxyhgk/retain-pdf/blob/main/desktop/main.js"
click node_desktop_backend "https://github.com/wxyhgk/retain-pdf/blob/main/desktop/src/main/backend-runtime.js"
click node_frontend "https://github.com/wxyhgk/retain-pdf/blob/main/frontend/src/pages/home/entry.tsx"
click node_rust_api "https://github.com/wxyhgk/retain-pdf/blob/main/backend/rust_api/src/main.rs"
click node_router "https://github.com/wxyhgk/retain-pdf/blob/main/backend/rust_api/src/app/router.rs"
click node_job_facade "https://github.com/wxyhgk/retain-pdf/blob/main/backend/rust_api/src/services/jobs/facade.rs"
click node_job_runner "https://github.com/wxyhgk/retain-pdf/blob/main/backend/rust_api/src/job_runner/mod.rs"
click node_worker_commands "https://github.com/wxyhgk/retain-pdf/blob/main/backend/rust_api/src/worker_command/stage_commands.rs"
click node_ocr_catalog "https://github.com/wxyhgk/retain-pdf/blob/main/backend/rust_api/src/ocr_provider/catalog.rs"
click node_storage "https://github.com/wxyhgk/retain-pdf/blob/main/backend/rust_api/src/storage_paths/registry.rs"
click node_artifacts "https://github.com/wxyhgk/retain-pdf/blob/main/backend/rust_api/src/services/artifacts/registry.rs"
click node_reader_ai "https://github.com/wxyhgk/retain-pdf/blob/main/backend/rust_api/src/services/jobs/reader_ai.rs"
click node_document_flow "https://github.com/wxyhgk/retain-pdf/blob/main/backend/scripts/entrypoints/run_document_flow.py"
click node_ocr_normalization "https://github.com/wxyhgk/retain-pdf/blob/main/backend/scripts/services/ocr_provider/provider_pipeline.py"
click node_document_model "https://github.com/wxyhgk/retain-pdf/blob/main/backend/scripts/services/document_schema/document.v1.schema.json"
click node_translation "https://github.com/wxyhgk/retain-pdf/blob/main/backend/scripts/services/translation/workflow/translation_workflow.py"
click node_deepseek "https://github.com/wxyhgk/retain-pdf/blob/main/backend/scripts/services/translation/llm/providers/deepseek/translation_client.py"
click node_rendering "https://github.com/wxyhgk/retain-pdf/blob/main/backend/scripts/services/rendering/workflow/executor.py"
click node_typst "https://github.com/wxyhgk/retain-pdf/blob/main/backend/scripts/services/rendering/output/typst/compiler.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_docker,node_desktop,node_desktop_backend toneBlue
class node_frontend toneAmber
class node_rust_api,node_router,node_job_facade,node_job_runner,node_worker_commands,node_ocr_catalog,node_storage,node_artifacts,node_reader_ai toneMint
class node_document_flow,node_ocr_normalization,node_document_model,node_translation,node_deepseek,node_rendering,node_typst toneRose
```

## Components

### Delivery surfaces

- [Docker deployment](https://github.com/wxyhgk/retain-pdf/blob/main/docker/delivery/docker-compose.yml): container deployment · App/API and web images run behind Nginx. · `docker/delivery/docker-compose.yml`
- [Electron desktop](https://github.com/wxyhgk/retain-pdf/blob/main/desktop/main.js): desktop runtime · Starts local backend and loads the frontend bundle. · `desktop/main.js`
- [Local backend runtime](https://github.com/wxyhgk/retain-pdf/blob/main/desktop/src/main/backend-runtime.js): desktop process manager · `desktop/src/main/backend-runtime.js`

### Client applications

- [Production React SPA](https://github.com/wxyhgk/retain-pdf/blob/main/frontend/src/pages/home/entry.tsx): web client · Home workflow, job detail, and reader entry points. · `frontend/src/pages/home/entry.tsx`

### Rust orchestration

- [Rust HTTP API](https://github.com/wxyhgk/retain-pdf/blob/main/backend/rust_api/src/main.rs): system of record · Authoritative API, persistence, artifacts, and job lifecycle boundary. · `backend/rust_api/src/main.rs`
- [API router](https://github.com/wxyhgk/retain-pdf/blob/main/backend/rust_api/src/app/router.rs): request boundary · `backend/rust_api/src/app/router.rs`
- [Job services](https://github.com/wxyhgk/retain-pdf/blob/main/backend/rust_api/src/services/jobs/facade.rs): application service · Maps API commands and queries to jobs, storage, and artifacts. · `backend/rust_api/src/services/jobs/facade.rs`
- [Job runner](https://github.com/wxyhgk/retain-pdf/blob/main/backend/rust_api/src/job_runner/mod.rs): pipeline orchestrator · Launches workers, tracks events, and handles cancellation, retry, and resume. · `backend/rust_api/src/job_runner/mod.rs`
- [Worker stage commands](https://github.com/wxyhgk/retain-pdf/blob/main/backend/rust_api/src/worker_command/stage_commands.rs): process command builder · `backend/rust_api/src/worker_command/stage_commands.rs`
- [OCR provider catalog](https://github.com/wxyhgk/retain-pdf/blob/main/backend/rust_api/src/ocr_provider/catalog.rs): provider configuration · Owns configured OCR providers and remote integration behavior. · `backend/rust_api/src/ocr_provider/catalog.rs`
- [Storage and database](https://github.com/wxyhgk/retain-pdf/blob/main/backend/rust_api/src/storage_paths/registry.rs): persistence layer · Backs uploads, job data, event logs, and artifacts. · `backend/rust_api/src/storage_paths/registry.rs`
- [Artifact registry](https://github.com/wxyhgk/retain-pdf/blob/main/backend/rust_api/src/services/artifacts/registry.rs): artifact service · Registers downloads, previews, and output variants. · `backend/rust_api/src/services/artifacts/registry.rs`
- [Reader AI service](https://github.com/wxyhgk/retain-pdf/blob/main/backend/rust_api/src/services/jobs/reader_ai.rs): reader service · `backend/rust_api/src/services/jobs/reader_ai.rs`

### Python document pipeline

- [Document flow worker](https://github.com/wxyhgk/retain-pdf/blob/main/backend/scripts/entrypoints/run_document_flow.py): pipeline entrypoint · Runs whole-document and individual processing stages. · `backend/scripts/entrypoints/run_document_flow.py`
- [OCR normalization](https://github.com/wxyhgk/retain-pdf/blob/main/backend/scripts/services/ocr_provider/provider_pipeline.py): OCR adapter pipeline · Converts provider payloads and layout semantics into the canonical model. · `backend/scripts/services/ocr_provider/provider_pipeline.py`
- [document.v1](https://github.com/wxyhgk/retain-pdf/blob/main/backend/scripts/services/document_schema/document.v1.schema.json): canonical document model · Shared intermediate representation for translation and rendering. · `backend/scripts/services/document_schema/document.v1.schema.json`
- [Translation workflow](https://github.com/wxyhgk/retain-pdf/blob/main/backend/scripts/services/translation/workflow/translation_workflow.py): LLM translation stage · Applies policies, glossary protection, placeholders, batching, validation, and repair. · `backend/scripts/services/translation/workflow/translation_workflow.py`
- [DeepSeek client](https://github.com/wxyhgk/retain-pdf/blob/main/backend/scripts/services/translation/llm/providers/deepseek/translation_client.py): LLM provider · `backend/scripts/services/translation/llm/providers/deepseek/translation_client.py`
- [Rendering workflow](https://github.com/wxyhgk/retain-pdf/blob/main/backend/scripts/services/rendering/workflow/executor.py): PDF render stage · Analyzes pages, routes layout handling, and fits translated overlays. · `backend/scripts/services/rendering/workflow/executor.py`
- [Typst compiler](https://github.com/wxyhgk/retain-pdf/blob/main/backend/scripts/services/rendering/output/typst/compiler.py): PDF compilation boundary · Builds overlays and final PDFs. · `backend/scripts/services/rendering/output/typst/compiler.py`

## Connections

- Docker deployment → Production React SPA: serves
- Docker deployment → Rust HTTP API: runs
- Electron desktop → Local backend runtime: manages
- Local backend runtime → Rust HTTP API: starts locally
- Electron desktop → Production React SPA: loads bundle
- Production React SPA → API router: HTTP API
- API router → Job services: commands and queries
- API router → Artifact registry: artifact access
- API router → Reader AI service: reader requests
- Job services → Job runner: launches jobs
- Job services → Storage and database: persists jobs
- Job runner → Worker stage commands: builds process commands
- Job runner → OCR provider catalog: selects provider
- Job runner → Document flow worker: runs Python worker
- Document flow worker → OCR normalization: OCR stage
- OCR normalization → document.v1: normalizes to
- Document flow worker → Translation workflow: translation stage
- Translation workflow → document.v1: reads and applies translations
- Translation workflow → DeepSeek client: LLM calls
- Document flow worker → Rendering workflow: render stage
- Rendering workflow → document.v1: uses layout blocks
- Rendering workflow → Typst compiler: compiles output
- Typst compiler → Artifact registry: registered output
- Job runner → Storage and database: events and failures
