# espresso3389/pdfrx architecture

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

- Interactive diagram: https://gitdiagram.com/espresso3389/pdfrx
- Repository: https://github.com/espresso3389/pdfrx

## Overview

#### Purpose and Entry Points
This pub-workspace monorepo delivers PDF rendering, viewing, and manipulation for Dart and Flutter. Its public package entry points are:
- Flutter UI API: `packages/pdfrx/lib/pdfrx.dart`
- Platform-agnostic document API: `packages/pdfrx_engine/lib/pdfrx_engine.dart`
- Direct PDFium FFI: `packages/pdfium_dart/lib/pdfium_dart.dart`
- Flutter PDFium packaging: `packages/pdfium_flutter/lib/pdfium_flutter.dart`
- Experimental Apple CoreGraphics backend: `packages/pdfrx_coregraphics/lib/pdfrx_coregraphics.dart`

#### PDFium Binding and Deployment Layer
PDFium is the primary rendering/manipulation engine. `pdfium_dart` exposes generated C FFI bindings and resolves a usable PDFium library; build/link hooks acquire and package native assets. `pdfium_flutter` supplies Flutter-specific loading and Darwin framework integration.
- `packages/pdfium_dart/lib/src/pdfium_bindings.dart`
- `packages/pdfium_dart/lib/src/pdfium_loader.dart`
- `packages/pdfium_dart/hook/build.dart`
- `packages/pdfium_flutter/darwin/pdfium_flutter/Sources/main/pdfium_flutter.swift`

Native targets include Android, iOS, macOS, Windows, and Linux. iOS/macOS use a PDFium XCFramework through CocoaPods or Swift Package Manager; other native environments use Dart native assets.

#### Engine: Document and Rendering Domain
`pdfrx_engine` is the non-Flutter boundary over PDFium. It defines document/page abstractions plus PDF-domain values for text, images, annotations, links, outlines, permissions, destinations, and editing operations. This layer can support CLI or server-side Dart consumers without widget dependencies.
- `packages/pdfrx_engine/lib/src/pdf_document.dart`
- `packages/pdfrx_engine/lib/src/pdf_page.dart`
- `packages/pdfrx_engine/lib/src/pdfrx.dart`

The control flow is initialization → document open/create → page/text/image/link operations → render or write/export. Native PDFium adaptation, file access/write callbacks, caching, and worker handling live behind the engine boundary:
- `packages/pdfrx_engine/lib/src/native/pdfrx_pdfium.dart`
- `packages/pdfrx_engine/lib/src/native/pdfium_file_access.dart`
- `packages/pdfrx_engine/lib/src/native/worker.dart`

#### Flutter Viewer Composition
`pdfrx` builds the interactive Flutter presentation layer on the engine. The viewer owns document presentation, viewport/layout state, page rendering, gestures, keyboard handling, overlays, search, selection, links, and scroll feedback.
- `packages/pdfrx/lib/src/widgets/pdf_viewer.dart`
- `packages/pdfrx/lib/src/widgets/interactive_viewer.dart`
- `packages/pdfrx/lib/src/widgets/pdf_viewer_params.dart`

Viewer behavior is delegated rather than hard-coded: sizing, zoom steps, and scroll interaction have interchangeable strategies.
- `packages/pdfrx/lib/src/widgets/sizing/pdf_viewer_size_delegate.dart`
- `packages/pdfrx/lib/src/widgets/zoom_steps/pdf_viewer_zoom_steps_delegate.dart`
- `packages/pdfrx/lib/src/widgets/scroll_interaction/pdf_viewer_scroll_interaction_delegate.dart`

#### Web and Apple Backend Boundaries
Web uses bundled WebAssembly plus JavaScript client/worker assets, separated from native loading code.
- `packages/pdfrx/assets/pdfium.wasm`
- `packages/pdfrx/assets/pdfium_client.js`
- `packages/pdfrx/lib/src/wasm/pdfrx_wasm.dart`

On Apple platforms, an experimental plugin can substitute system PDFKit/CoreGraphics while preserving the `pdfrx` widget-facing API.
- `packages/pdfrx_coregraphics/darwin/pdfrx_coregraphics/Sources/PdfrxCoregraphicsPlugin.swift`
- `packages/pdfrx_coregraphics/lib/pdfrx_coregraphics.dart`

#### Consumer Applications and Delivery
The primary executable examples are Flutter applications: a full viewer and a PDF-combine/page-rearrangement tool.
- `packages/pdfrx/example/viewer/lib/main.dart`
- `packages/pdfrx/example/pdf_combine/lib/main.dart`

CI is GitHub Actions-based, including build/test, static analysis, Pages documentation, and Apple PDFium release automation.
- `.github/workflows/build-test.yml`
- `.github/workflows/pdfium-apple-release.yml`

Main entry points: [`packages/pdfrx/lib/src/widgets/pdf_viewer.dart`](https://github.com/espresso3389/pdfrx/blob/master/packages/pdfrx/lib/src/widgets/pdf_viewer.dart) (PDF viewer), [`packages/pdfium_dart/lib/pdfium_dart.dart`](https://github.com/espresso3389/pdfrx/blob/master/packages/pdfium_dart/lib/pdfium_dart.dart) (pdfium_dart API), [`packages/pdfrx_engine/lib/pdfrx_engine.dart`](https://github.com/espresso3389/pdfrx/blob/master/packages/pdfrx_engine/lib/pdfrx_engine.dart) (pdfrx_engine API), [`packages/pdfrx/lib/pdfrx.dart`](https://github.com/espresso3389/pdfrx/blob/master/packages/pdfrx/lib/pdfrx.dart) (pdfrx Flutter API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pdfium["PDFium Runtime"]
  node_pdfium_api["pdfium_dart API<br/>Dart package<br/>[pdfium_dart.dart]"]
  node_ffi_bindings["Generated FFI bindings<br/>FFI layer"]
  node_pdfium_loader["PDFium loader<br/>runtime loader<br/>[pdfium_loader.dart]"]
  node_native_asset_build["Native asset build hook<br/>[build.dart]"]
  node_flutter_pdfium["pdfium_flutter<br/>Flutter package"]
  node_darwin_pdfium["Darwin PDFium bridge<br/>Swift plugin"]
end

subgraph group_engine["Document Engine"]
  node_engine_api["pdfrx_engine API<br/>Dart package<br/>[pdfrx_engine.dart]"]
  node_document_domain["Document and page domain<br/>domain model<br/>[pdf_document.dart]"]
  node_native_engine["Native PDFium adapter<br/>native adapter<br/>[pdfrx_pdfium.dart]"]
end

subgraph group_flutter["Flutter Viewer"]
  node_pdfrx_api["pdfrx Flutter API<br/>Flutter package<br/>[pdfrx.dart]"]
  node_pdf_viewer["PDF viewer<br/>Flutter widget<br/>[pdf_viewer.dart]"]
  node_interactive_viewer["Interactive viewport<br/>widget controller"]
  node_viewer_strategies["Viewer strategies<br/>delegate APIs"]
  node_web_wasm["WebAssembly PDFium<br/>web runtime<br/>[pdfium.wasm]"]
  node_wasm_adapter["WASM adapter<br/>web adapter<br/>[pdfrx_wasm.dart]"]
end

subgraph group_apple["Apple Alternative"]
  node_coregraphics_api["CoreGraphics backend<br/>experimental Flutter package"]
end

subgraph group_delivery["Consumers &amp; Delivery"]
  node_viewer_example["Viewer example<br/>Flutter application<br/>[main.dart]"]
  node_combine_example["PDF combine example<br/>Flutter application<br/>[main.dart]"]
  node_ci["Build and release CI<br/>GitHub Actions<br/>[build-test.yml]"]
end

node_pdfium_api -->|"exposes"| node_ffi_bindings
node_pdfium_api -->|"loads through"| node_pdfium_loader
node_native_asset_build -->|"packages assets for"| node_pdfium_loader
node_flutter_pdfium -->|"uses"| node_pdfium_api
node_flutter_pdfium -->|"integrates"| node_darwin_pdfium
node_engine_api -->|"exports"| node_document_domain
node_engine_api -->|"delegates native work to"| node_native_engine
node_native_engine -->|"adapts"| node_pdfium_api
node_pdfrx_api -->|"exports"| node_pdf_viewer
node_pdf_viewer -->|"composes"| node_interactive_viewer
node_pdf_viewer -->|"delegates behavior to"| node_viewer_strategies
node_pdf_viewer -->|"opens, renders, and edits through"| node_engine_api
node_wasm_adapter -->|"loads"| node_web_wasm
node_pdfrx_api -.->|"uses on web"| node_wasm_adapter
node_coregraphics_api -.->|"substitutes backend for"| node_pdfrx_api
node_viewer_example -->|"consumes"| node_pdfrx_api
node_combine_example -->|"consumes"| node_engine_api
node_ci -.->|"builds and tests"| node_native_asset_build
node_ci -.->|"releases Apple PDFium"| node_darwin_pdfium

click node_pdfium_api "https://github.com/espresso3389/pdfrx/blob/master/packages/pdfium_dart/lib/pdfium_dart.dart"
click node_ffi_bindings "https://github.com/espresso3389/pdfrx/blob/master/packages/pdfium_dart/lib/src/pdfium_bindings.dart"
click node_pdfium_loader "https://github.com/espresso3389/pdfrx/blob/master/packages/pdfium_dart/lib/src/pdfium_loader.dart"
click node_native_asset_build "https://github.com/espresso3389/pdfrx/blob/master/packages/pdfium_dart/hook/build.dart"
click node_flutter_pdfium "https://github.com/espresso3389/pdfrx/blob/master/packages/pdfium_flutter/lib/pdfium_flutter.dart"
click node_darwin_pdfium "https://github.com/espresso3389/pdfrx/blob/master/packages/pdfium_flutter/darwin/pdfium_flutter/Sources/main/pdfium_flutter.swift"
click node_engine_api "https://github.com/espresso3389/pdfrx/blob/master/packages/pdfrx_engine/lib/pdfrx_engine.dart"
click node_document_domain "https://github.com/espresso3389/pdfrx/blob/master/packages/pdfrx_engine/lib/src/pdf_document.dart"
click node_native_engine "https://github.com/espresso3389/pdfrx/blob/master/packages/pdfrx_engine/lib/src/native/pdfrx_pdfium.dart"
click node_pdfrx_api "https://github.com/espresso3389/pdfrx/blob/master/packages/pdfrx/lib/pdfrx.dart"
click node_pdf_viewer "https://github.com/espresso3389/pdfrx/blob/master/packages/pdfrx/lib/src/widgets/pdf_viewer.dart"
click node_interactive_viewer "https://github.com/espresso3389/pdfrx/blob/master/packages/pdfrx/lib/src/widgets/interactive_viewer.dart"
click node_viewer_strategies "https://github.com/espresso3389/pdfrx/blob/master/packages/pdfrx/lib/src/widgets/sizing/pdf_viewer_size_delegate.dart"
click node_web_wasm "https://github.com/espresso3389/pdfrx/blob/master/packages/pdfrx/assets/pdfium.wasm"
click node_wasm_adapter "https://github.com/espresso3389/pdfrx/blob/master/packages/pdfrx/lib/src/wasm/pdfrx_wasm.dart"
click node_coregraphics_api "https://github.com/espresso3389/pdfrx/blob/master/packages/pdfrx_coregraphics/lib/pdfrx_coregraphics.dart"
click node_viewer_example "https://github.com/espresso3389/pdfrx/blob/master/packages/pdfrx/example/viewer/lib/main.dart"
click node_combine_example "https://github.com/espresso3389/pdfrx/blob/master/packages/pdfrx/example/pdf_combine/lib/main.dart"
click node_ci "https://github.com/espresso3389/pdfrx/blob/master/.github/workflows/build-test.yml"

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_pdfium_api,node_ffi_bindings,node_pdfium_loader,node_native_asset_build,node_flutter_pdfium,node_darwin_pdfium toneBlue
class node_engine_api,node_document_domain,node_native_engine toneAmber
class node_pdfrx_api,node_pdf_viewer,node_interactive_viewer,node_viewer_strategies,node_web_wasm,node_wasm_adapter toneMint
class node_coregraphics_api toneRose
class node_viewer_example,node_combine_example,node_ci toneIndigo
```

## Components

### PDFium Runtime

Native binding, loading, and platform packaging.

- [pdfium_dart API](https://github.com/espresso3389/pdfrx/blob/master/packages/pdfium_dart/lib/pdfium_dart.dart): Dart package · Direct PDFium FFI entry point. · `packages/pdfium_dart/lib/pdfium_dart.dart`
- [Generated FFI bindings](https://github.com/espresso3389/pdfrx/blob/master/packages/pdfium_dart/lib/src/pdfium_bindings.dart): FFI layer · `packages/pdfium_dart/lib/src/pdfium_bindings.dart`
- [PDFium loader](https://github.com/espresso3389/pdfrx/blob/master/packages/pdfium_dart/lib/src/pdfium_loader.dart): runtime loader · Resolves a usable native PDFium library. · `packages/pdfium_dart/lib/src/pdfium_loader.dart`
- [Native asset build hook](https://github.com/espresso3389/pdfrx/blob/master/packages/pdfium_dart/hook/build.dart): build hook · Acquires and packages PDFium native assets. · `packages/pdfium_dart/hook/build.dart`
- [pdfium_flutter](https://github.com/espresso3389/pdfrx/blob/master/packages/pdfium_flutter/lib/pdfium_flutter.dart): Flutter package · Flutter-specific PDFium loading and Darwin integration. · `packages/pdfium_flutter/lib/pdfium_flutter.dart`
- [Darwin PDFium bridge](https://github.com/espresso3389/pdfrx/blob/master/packages/pdfium_flutter/darwin/pdfium_flutter/Sources/main/pdfium_flutter.swift): Swift plugin · Integrates the PDFium XCFramework for Apple platforms. · `packages/pdfium_flutter/darwin/pdfium_flutter/Sources/main/pdfium_flutter.swift`

### Document Engine

Platform-agnostic PDF domain and native adaptation.

- [pdfrx_engine API](https://github.com/espresso3389/pdfrx/blob/master/packages/pdfrx_engine/lib/pdfrx_engine.dart): Dart package · Platform-agnostic document API. · `packages/pdfrx_engine/lib/pdfrx_engine.dart`
- [Document and page domain](https://github.com/espresso3389/pdfrx/blob/master/packages/pdfrx_engine/lib/src/pdf_document.dart): domain model · Documents, pages, text, images, links, annotations, and editing values. · `packages/pdfrx_engine/lib/src/pdf_document.dart`
- [Native PDFium adapter](https://github.com/espresso3389/pdfrx/blob/master/packages/pdfrx_engine/lib/src/native/pdfrx_pdfium.dart): native adapter · Handles PDFium access, callbacks, caching, and workers. · `packages/pdfrx_engine/lib/src/native/pdfrx_pdfium.dart`

### Flutter Viewer

Interactive widget composition and web runtime.

- [pdfrx Flutter API](https://github.com/espresso3389/pdfrx/blob/master/packages/pdfrx/lib/pdfrx.dart): Flutter package · Public widget-facing PDF API. · `packages/pdfrx/lib/pdfrx.dart`
- [PDF viewer](https://github.com/espresso3389/pdfrx/blob/master/packages/pdfrx/lib/src/widgets/pdf_viewer.dart): Flutter widget · Owns presentation, page rendering, overlays, search, selection, and links. · `packages/pdfrx/lib/src/widgets/pdf_viewer.dart`
- [Interactive viewport](https://github.com/espresso3389/pdfrx/blob/master/packages/pdfrx/lib/src/widgets/interactive_viewer.dart): widget controller · Manages layout state, gestures, keyboard input, and scroll feedback. · `packages/pdfrx/lib/src/widgets/interactive_viewer.dart`
- [Viewer strategies](https://github.com/espresso3389/pdfrx/blob/master/packages/pdfrx/lib/src/widgets/sizing/pdf_viewer_size_delegate.dart): delegate APIs · Interchangeable sizing, zoom-step, and scroll-interaction behavior. · `packages/pdfrx/lib/src/widgets/sizing/pdf_viewer_size_delegate.dart`
- [WebAssembly PDFium](https://github.com/espresso3389/pdfrx/blob/master/packages/pdfrx/assets/pdfium.wasm): web runtime · Bundled WASM with JavaScript client and worker assets. · `packages/pdfrx/assets/pdfium.wasm`
- [WASM adapter](https://github.com/espresso3389/pdfrx/blob/master/packages/pdfrx/lib/src/wasm/pdfrx_wasm.dart): web adapter · Separates web PDFium access from native loading. · `packages/pdfrx/lib/src/wasm/pdfrx_wasm.dart`

### Apple Alternative

Experimental system-framework backend.

- [CoreGraphics backend](https://github.com/espresso3389/pdfrx/blob/master/packages/pdfrx_coregraphics/lib/pdfrx_coregraphics.dart): experimental Flutter package · Preserves the widget-facing API using PDFKit/CoreGraphics. · `packages/pdfrx_coregraphics/lib/pdfrx_coregraphics.dart`

### Consumers & Delivery

- [Viewer example](https://github.com/espresso3389/pdfrx/blob/master/packages/pdfrx/example/viewer/lib/main.dart): Flutter application · `packages/pdfrx/example/viewer/lib/main.dart`
- [PDF combine example](https://github.com/espresso3389/pdfrx/blob/master/packages/pdfrx/example/pdf_combine/lib/main.dart): Flutter application · Page rearrangement and PDF-combine tool. · `packages/pdfrx/example/pdf_combine/lib/main.dart`
- [Build and release CI](https://github.com/espresso3389/pdfrx/blob/master/.github/workflows/build-test.yml): GitHub Actions · Builds, tests, analyzes, publishes docs, and releases Apple PDFium. · `.github/workflows/build-test.yml`

## Connections

- pdfium_dart API → Generated FFI bindings: exposes
- pdfium_dart API → PDFium loader: loads through
- Native asset build hook → PDFium loader: packages assets for
- pdfium_flutter → pdfium_dart API: uses
- pdfium_flutter → Darwin PDFium bridge: integrates
- pdfrx_engine API → Document and page domain: exports
- pdfrx_engine API → Native PDFium adapter: delegates native work to
- Native PDFium adapter → pdfium_dart API: adapts
- pdfrx Flutter API → PDF viewer: exports
- PDF viewer → Interactive viewport: composes
- PDF viewer → Viewer strategies: delegates behavior to
- PDF viewer → pdfrx_engine API: opens, renders, and edits through
- WASM adapter → WebAssembly PDFium: loads
- pdfrx Flutter API → WASM adapter: uses on web
- CoreGraphics backend → pdfrx Flutter API: substitutes backend for
- Viewer example → pdfrx Flutter API: consumes
- PDF combine example → pdfrx_engine API: consumes
- Build and release CI → Native asset build hook: builds and tests
- Build and release CI → Darwin PDFium bridge: releases Apple PDFium