# l4rzy/okular-mupdf-ng architecture

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

- Interactive diagram: https://gitdiagram.com/l4rzy/okular-mupdf-ng
- Repository: https://github.com/l4rzy/okular-mupdf-ng

## Overview

okular-mupdf-ng is an Okular document backend that moves parsing and rendering into a hardened worker process. The principal flow is Okular opening a document through the plugin, which transfers it to the worker; the worker dispatches document operations to format engines and returns rendered pages and document data. The README also documents OCR, export, annotations, signing, theming, and configuration capabilities. Edges reflect README statements or SOURCE INDEX references; unsampled feature wiring is not asserted.

Main entry points: [`src/worker/runtime/command_service.cpp`](https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/worker/runtime/command_service.cpp) (Command Service), [`src/plugin/worker_transport.cpp`](https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/plugin/worker_transport.cpp) (Plugin Transport), [`src/plugin/worker_client.cpp`](https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/plugin/worker_client.cpp) (Worker Client), [`src/worker/main.cpp`](https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/worker/main.cpp) (Worker Process)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["Okular Integration"]
  node_backend["Generator Backend<br/>[mupdfng.cpp]"]
  node_worker_client["Worker Client<br/>[worker_client.cpp]"]
  node_cli["Command Line Client<br/>[main.cpp]"]
end

subgraph group_worker["Worker Runtime"]
  node_worker_process["Worker Process<br/>[main.cpp]"]
  node_worker_server["Worker Server<br/>[worker_server.cpp]"]
  node_command_service["Command Service"]
  node_sandbox["Sandbox<br/>[sandbox.cpp]"]
end

subgraph group_engines["Document Engines"]
  node_pdf_engine["PDF Engine<br/>[document.cpp]"]
  node_epub_engine["EPUB Engine<br/>[document.cpp]"]
  node_mobi_engine["MOBI Engine<br/>[document.cpp]"]
  node_kindle_engine["AZW3 KFX Engine<br/>[document.cpp]"]
  node_xps_engine["XPS Engine<br/>[document.cpp]"]
end

subgraph group_features["Document Features"]
  node_ocr_controller["OCR Controller<br/>[controller.cpp]"]
  node_certificates[("Certificate Manager")]
  node_link_preview["Link Preview<br/>[link_preview.cpp]"]
  node_annotations["Annotation Support<br/>[annotation.cpp]"]
  node_xfdf["XFDF Import Export<br/>[export.cpp]"]
  node_ocr_engine["Worker OCR<br/>[ocr.cpp]"]
  node_export_jobs["Export Jobs<br/>[jobs.cpp]"]
end

subgraph group_ipc["IPC and Shared Types"]
  node_worker_transport["Plugin Transport"]
  node_ctrl_channel["Control Channel<br/>[ctrl_channel.cpp]"]
  node_fd_channel["Descriptor Channel<br/>[fd_channel.cpp]"]
  node_protocol["IPC Codec<br/>[zpp_codec.cpp]"]
  node_shared_types["Shared Data Model<br/>[types.hpp]"]
end

node_okular(("Okular"))

node_okular -->|"uses backend"| node_backend
node_backend -.->|"requests document work"| node_worker_client
node_worker_client -->|"delegates transport"| node_worker_transport
node_worker_transport -->|"starts worker"| node_worker_process
node_worker_transport -->|"sends control messages"| node_ctrl_channel
node_worker_transport -->|"transfers descriptors"| node_fd_channel
node_worker_transport -->|"encodes requests"| node_protocol
node_worker_transport -->|"exchanges data"| node_shared_types
node_worker_process -->|"runs server"| node_worker_server
node_worker_process -->|"configures isolation"| node_sandbox
node_worker_server -->|"dispatches requests"| node_command_service
node_command_service -.->|"dispatches document work"| node_pdf_engine
node_command_service -.->|"dispatches document work"| node_epub_engine
node_command_service -.->|"dispatches document work"| node_mobi_engine
node_command_service -.->|"dispatches document work"| node_kindle_engine
node_command_service -.->|"dispatches document work"| node_xps_engine
node_command_service -->|"uses OCR jobs"| node_ocr_engine
node_command_service -->|"uses export jobs"| node_export_jobs
node_command_service -->|"exchanges messages"| node_shared_types
node_ocr_controller -->|"requests OCR"| node_worker_client
node_okular -->|"previews links"| node_link_preview
node_okular -->|"edits annotations"| node_annotations
node_okular -->|"imports exports XFDF"| node_xfdf
node_okular -->|"manages certificates"| node_certificates
node_cli -->|"calls worker"| node_worker_client
node_pdf_engine -.->|"performs page OCR"| node_ocr_engine
node_epub_engine -.->|"supports export"| node_export_jobs

click node_backend "https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/generator/mupdfng.cpp"
click node_worker_client "https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/plugin/worker_client.cpp"
click node_ocr_controller "https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/plugin/ocr/controller.cpp"
click node_certificates "https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/plugin/crypto/certificate_database.cpp"
click node_link_preview "https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/generator/ui/link_preview.cpp"
click node_annotations "https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/generator/proxy/annotation.cpp"
click node_xfdf "https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/plugin/xfdf/export.cpp"
click node_worker_process "https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/worker/main.cpp"
click node_worker_server "https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/worker/runtime/worker_server.cpp"
click node_command_service "https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/worker/runtime/command_service.cpp"
click node_sandbox "https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/worker/sys/sandbox.cpp"
click node_pdf_engine "https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/worker/engine/pdf/document.cpp"
click node_epub_engine "https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/worker/engine/epub/document.cpp"
click node_mobi_engine "https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/worker/engine/mobi/document.cpp"
click node_kindle_engine "https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/worker/engine/kindle/document.cpp"
click node_xps_engine "https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/worker/engine/xps/document.cpp"
click node_ocr_engine "https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/worker/engine/ocr/ocr.cpp"
click node_export_jobs "https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/worker/engine/export/jobs.cpp"
click node_worker_transport "https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/plugin/worker_transport.cpp"
click node_ctrl_channel "https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/shared/transport/ctrl_channel.cpp"
click node_fd_channel "https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/shared/transport/fd_channel.cpp"
click node_protocol "https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/shared/protocol/zpp_codec.cpp"
click node_shared_types "https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/shared/model/types.hpp"
click node_cli "https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/tools/cli/main.cpp"

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_backend,node_worker_client,node_cli toneBlue
class node_worker_process,node_worker_server,node_command_service,node_sandbox toneAmber
class node_pdf_engine,node_epub_engine,node_mobi_engine,node_kindle_engine,node_xps_engine toneMint
class node_ocr_controller,node_certificates,node_link_preview,node_annotations,node_xfdf,node_ocr_engine,node_export_jobs toneRose
class node_worker_transport,node_ctrl_channel,node_fd_channel,node_protocol,node_shared_types,node_okular toneIndigo
```

## Components

### Okular Integration

- [Generator Backend](https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/generator/mupdfng.cpp): `src/generator/mupdfng.cpp`
- [Worker Client](https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/plugin/worker_client.cpp): `src/plugin/worker_client.cpp`
- [Command Line Client](https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/tools/cli/main.cpp): `src/tools/cli/main.cpp`

### Worker Runtime

- [Worker Process](https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/worker/main.cpp): `src/worker/main.cpp`
- [Worker Server](https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/worker/runtime/worker_server.cpp): `src/worker/runtime/worker_server.cpp`
- [Command Service](https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/worker/runtime/command_service.cpp): `src/worker/runtime/command_service.cpp`
- [Sandbox](https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/worker/sys/sandbox.cpp): `src/worker/sys/sandbox.cpp`

### Document Engines

- [PDF Engine](https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/worker/engine/pdf/document.cpp): `src/worker/engine/pdf/document.cpp`
- [EPUB Engine](https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/worker/engine/epub/document.cpp): `src/worker/engine/epub/document.cpp`
- [MOBI Engine](https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/worker/engine/mobi/document.cpp): `src/worker/engine/mobi/document.cpp`
- [AZW3 KFX Engine](https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/worker/engine/kindle/document.cpp): `src/worker/engine/kindle/document.cpp`
- [XPS Engine](https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/worker/engine/xps/document.cpp): `src/worker/engine/xps/document.cpp`

### Document Features

- [OCR Controller](https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/plugin/ocr/controller.cpp): `src/plugin/ocr/controller.cpp`
- [Certificate Manager](https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/plugin/crypto/certificate_database.cpp): `src/plugin/crypto/certificate_database.cpp`
- [Link Preview](https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/generator/ui/link_preview.cpp): `src/generator/ui/link_preview.cpp`
- [Annotation Support](https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/generator/proxy/annotation.cpp): `src/generator/proxy/annotation.cpp`
- [XFDF Import Export](https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/plugin/xfdf/export.cpp): `src/plugin/xfdf/export.cpp`
- [Worker OCR](https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/worker/engine/ocr/ocr.cpp): `src/worker/engine/ocr/ocr.cpp`
- [Export Jobs](https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/worker/engine/export/jobs.cpp): `src/worker/engine/export/jobs.cpp`

### IPC and Shared Types

- [Plugin Transport](https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/plugin/worker_transport.cpp): `src/plugin/worker_transport.cpp`
- [Control Channel](https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/shared/transport/ctrl_channel.cpp): `src/shared/transport/ctrl_channel.cpp`
- [Descriptor Channel](https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/shared/transport/fd_channel.cpp): `src/shared/transport/fd_channel.cpp`
- [IPC Codec](https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/shared/protocol/zpp_codec.cpp): `src/shared/protocol/zpp_codec.cpp`
- [Shared Data Model](https://github.com/l4rzy/okular-mupdf-ng/blob/main/src/shared/model/types.hpp): `src/shared/model/types.hpp`

### Other components

- **Okular**

## Connections

- Okular → Generator Backend: uses backend
- Generator Backend → Worker Client: requests document work
- Worker Client → Plugin Transport: delegates transport (evidence: `src/plugin/worker_client.cpp`)
- Plugin Transport → Worker Process: starts worker
- Plugin Transport → Control Channel: sends control messages
- Plugin Transport → Descriptor Channel: transfers descriptors (evidence: `src/plugin/worker_transport.cpp`)
- Plugin Transport → IPC Codec: encodes requests (evidence: `src/plugin/worker_transport.cpp`)
- Plugin Transport → Shared Data Model: exchanges data (evidence: `src/plugin/worker_transport.cpp`)
- Worker Process → Worker Server: runs server (evidence: `src/worker/main.cpp`)
- Worker Process → Sandbox: configures isolation (evidence: `src/worker/main.cpp`)
- Worker Server → Command Service: dispatches requests
- Command Service → PDF Engine: dispatches document work
- Command Service → EPUB Engine: dispatches document work
- Command Service → MOBI Engine: dispatches document work
- Command Service → AZW3 KFX Engine: dispatches document work
- Command Service → XPS Engine: dispatches document work
- Command Service → Worker OCR: uses OCR jobs
- Command Service → Export Jobs: uses export jobs
- Command Service → Shared Data Model: exchanges messages
- OCR Controller → Worker Client: requests OCR
- Okular → Link Preview: previews links
- Okular → Annotation Support: edits annotations
- Okular → XFDF Import Export: imports exports XFDF
- Okular → Certificate Manager: manages certificates
- Command Line Client → Worker Client: calls worker (evidence: `src/tools/cli/main.cpp`)
- PDF Engine → Worker OCR: performs page OCR
- EPUB Engine → Export Jobs: supports export