How wxyhgk/retain-pdf works
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: mod.rs Job runner · router.rs API router · run_document_flow.py Document flow worker · facade.rs Job services
Components 20
Delivery surfaces
- Docker deployment · App/API and web images run behind Nginx.
docker/delivery/docker-compose.yml - Electron desktop · Starts local backend and loads the frontend bundle.
desktop/main.js - Local backend runtime
desktop/src/main/backend-runtime.js
Client applications
- Production React SPA · Home workflow, job detail, and reader entry points.
frontend/src/pages/home/entry.tsx
Rust orchestration
- Rust HTTP API · Authoritative API, persistence, artifacts, and job lifecycle boundary.
backend/rust_api/src/main.rs - API router
backend/rust_api/src/app/router.rs - Job services · Maps API commands and queries to jobs, storage, and artifacts.
backend/rust_api/src/services/jobs/facade.rs - Job runner · Launches workers, tracks events, and handles cancellation, retry, and resume.
backend/rust_api/src/job_runner/mod.rs - Worker stage commands
backend/rust_api/src/worker_command/stage_commands.rs - OCR provider catalog · Owns configured OCR providers and remote integration behavior.
backend/rust_api/src/ocr_provider/catalog.rs - Storage and database · Backs uploads, job data, event logs, and artifacts.
backend/rust_api/src/storage_paths/registry.rs - Artifact registry · Registers downloads, previews, and output variants.
backend/rust_api/src/services/artifacts/registry.rs - Reader AI service
backend/rust_api/src/services/jobs/reader_ai.rs
Python document pipeline
- Document flow worker · Runs whole-document and individual processing stages.
backend/scripts/entrypoints/run_document_flow.py - OCR normalization · Converts provider payloads and layout semantics into the canonical model.
backend/scripts/services/ocr_provider/provider_pipeline.py - document.v1 · Shared intermediate representation for translation and rendering.
backend/scripts/services/document_schema/document.v1.schema.json - Translation workflow · Applies policies, glossary protection, placeholders, batching, validation, and repair.
backend/scripts/services/translation/workflow/translation_workflow.py - DeepSeek client
backend/scripts/services/translation/llm/providers/deepseek/translation_client.py - Rendering workflow · Analyzes pages, routes layout handling, and fits translated overlays.
backend/scripts/services/rendering/workflow/executor.py - Typst compiler · Builds overlays and final PDFs.
backend/scripts/services/rendering/output/typst/compiler.py
Connections 24
- 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