# pspdfkit/pspdfkit-flutter architecture

> Architecture diagram of the GitHub repository pspdfkit/pspdfkit-flutter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pspdfkit/pspdfkit-flutter
- Repository: https://github.com/pspdfkit/pspdfkit-flutter

## Overview

##### Project type and purpose
- This is an open-source Flutter plugin (SDK) that embeds the PSPDFKit PDF engine into Flutter apps on Android, iOS, and Web.
- It provides a unified Dart API, platform channels (MethodChannel/Pigeon), and native/web adaptors to the underlying PSPDFKit binaries or WebAssembly.

##### File structure
- **lib/**: The Dart interface and platform-agnostic implementation.
- **pigeons/**: Pigeon IDL and generated platform API code (pspdfkit_api.g.dart).
- **android/**: Native Java/Kotlin plugin code, binds Dart calls to PSPDFKit Android SDK.
- **ios/**: Native Swift/Objective-C plugin code, binds Dart calls to PSPDFKit iOS SDK.
- **web assets** (under example/web and instructions in README): the PSPDFKit Web WASM and JS loader.
- **example/**: A sample Flutter application demonstrating plugin integration.
- **test/**: Unit tests for Dart code, mocks for Pigeon API, widget controller tests.

##### README for insights
- Confirms cross-platform support (Android, iOS, Web).
- Describes setup steps and the runtime flow: initializing `Pspdfkit.initialize() → PspdfkitWidget` → document loading → platform SDK.

##### Main components
a. **Flutter App Layer**
- Widgets (e.g., `PspdfkitWidget`, host app UI)
- Business logic (e.g., asset extraction, FutureBuilders)
b. **Dart SDK Core** (`lib/pspdfkit_flutter.dart` + `lib/src/…`)
- Public API surface (`Pspdfkit`, `PspdfkitWidgetController`)
- MethodChannel or Pigeon channel handlers (`pspdfkit_flutter_method_channel.dart`, `pspdfkit_flutter_api_impl.dart`)
c. **Pigeon-Generated API** (`pigeons/` and `lib/src/api/pspdfkit_api.g.dart`)
- Strongly typed messages and callbacks
d. **Platform Channels**
- MethodChannel (Android/iOS) & JS interop (Web)
e. **Platform-Specific Plugin Code**
- Android: Java/Kotlin classes under `android/src/main/java/com/pspdfkit/flutter/pspdfkit`
- iOS: Swift/ObjC under `ios/Classes`
- Web: JavaScript/WASM assets loaded via `<script src="assets/pspdfkit.js">`
f. **Underlying PSPDFKit SDK**
- Android AAR/native libraries
- iOS frameworks
- WebAssembly modules + JS glue
g. **External Dependencies**
- Flutter engine
- Gradle/Maven (Android build)
- CocoaPods (iOS build)
- Web server serving WASM with correct MIME
h. **Example App**

##### Relationships & Interactions
- SDK API → sends message over **Pigeon/MethodChannel**
- **Platform channel** → dispatch to **Android/iOS/Web plugin code**
- Plugin code → invokes **PSPDFKit native SDK** or **WASM**
- Results/events → bubble up via the same channel back to **Dart** → update UI

##### Architectural patterns & design principles
- **Layered architecture**: UI layer, SDK core, platform adaptors, native libraries
- **Pigeon for type-safe channel calls**
- **Platform interface abstraction**: Dart defines an interface (`PspdfkitFlutterPlatform`), implementations are registered per platform (Android, iOS, Web)
- **Separation of concerns**:
· UI vs document processing vs native binding
· Cross-platform vs platform-specific code

##### Essential elements to capture
- Public Dart API → MethodChannel/Pigeon layer → platform code → native/Web SDK
- Initialization phase (`Pspdfkit.initialize`) and document display (`PspdfkitWidget`)
- Asset loading (local file system on mobile, WASM served over HTTP on Web)
- Event callbacks (annotation events, form submissions, analytics)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Example Application
    subgraph "Example Application"
        ExampleApp["Flutter App Layer\n(example/lib/)"]:::ui
    end

    %% Dart SDK Core
    subgraph "Dart SDK Core"
        PublicAPI["Public Dart API\nlib/pspdfkit_flutter.dart"]:::dart
        CoreEntry["SDK Core Entry Point\nlib/pspdfkit.dart"]:::dart
        PlatformInterface["Platform Interface Definition\nlib/src/pspdfkit_flutter_platform_interface.dart"]:::dart
        MethodChannelHandler["MethodChannel Handler\nlib/src/pspdfkit_flutter_method_channel.dart"]:::dart
        APIImpl["Pigeon API Implementation\nlib/src/pspdfkit_flutter_api_impl.dart"]:::dart
        WebAdaptor["Web Adaptor & JS/WASM Loader\nlib/src/web/"]:::dart
    end

    %% Pigeon Layer
    subgraph "Pigeon Layer"
        PigeonIDL["Pigeon IDL\npigeons/pspdfkit.dart"]:::pigeon
        PigeonGen["Generated API\nlib/src/api/pspdfkit_api.g.dart"]:::pigeon
    end

    %% Platform Channels
    subgraph "Platform Channels"
        Channels["MethodChannel / Pigeon Channels"]:::pigeon
    end

    %% Platform Implementations
    subgraph "Platform Implementations"
        AndroidPlugin["Android Plugin Code\nandroid/src/main/java/com/pspdfkit/flutter/pspdfkit/"]:::native
        iOSPlugin["iOS Plugin Code\nios/Classes/"]:::native
        WebPlugin["Web Adaptor Loader\nvia <script>"]:::native
    end

    %% Native PSPDFKit SDK
    subgraph "Native PSPDFKit SDK"
        AndroidSDK["PSPDFKit Android SDK"]:::native
        iOSSdk["PSPDFKit iOS SDK"]:::native
        WebWASM["PSPDFKit WebAssembly Module"]:::native
    end

    %% Example App Configurations
    subgraph "Example App Configurations"
        ExAndroid["Example Android Config\nexample/android/"]:::external
        ExiOS["Example iOS Config\nexample/ios/"]:::external
        ExWebAssets["Example Web Assets\nexample/web/"]:::external
    end

    %% Unit Tests
    Test["Unit Tests\ntest/"]:::external

    %% Connections
    ExampleApp -->|"uses API"| PublicAPI
    PublicAPI -->|"calls"| CoreEntry
    CoreEntry -->|"defines"| PlatformInterface
    CoreEntry -->|"routes to"| MethodChannelHandler
    CoreEntry -->|"routes to"| APIImpl
    APIImpl -->|"uses stubs"| PigeonGen
    PigeonIDL -->|"generates"| PigeonGen
    APIImpl -->|"sends messages"| Channels
    Channels -->|"dispatch to"| AndroidPlugin
    Channels -->|"dispatch to"| iOSPlugin
    Channels -->|"dispatch to"| WebPlugin
    AndroidPlugin -->|"invokes"| AndroidSDK
    iOSPlugin -->|"invokes"| iOSSdk
    WebPlugin -->|"loads"| WebWASM
    Test -->|"tests"| PublicAPI

    %% Example configs usage
    ExampleApp -.->|configured via| ExAndroid
    ExampleApp -.->|configured via| ExiOS
    ExampleApp -.->|loads assets from| ExWebAssets

    %% Click Events
    click ExampleApp "https://github.com/pspdfkit/pspdfkit-flutter/tree/master/example/lib/"
    click PublicAPI "https://github.com/pspdfkit/pspdfkit-flutter/blob/master/lib/pspdfkit_flutter.dart"
    click CoreEntry "https://github.com/pspdfkit/pspdfkit-flutter/blob/master/lib/pspdfkit.dart"
    click PlatformInterface "https://github.com/pspdfkit/pspdfkit-flutter/blob/master/lib/src/pspdfkit_flutter_platform_interface.dart"
    click MethodChannelHandler "https://github.com/pspdfkit/pspdfkit-flutter/blob/master/lib/src/pspdfkit_flutter_method_channel.dart"
    click APIImpl "https://github.com/pspdfkit/pspdfkit-flutter/blob/master/lib/src/pspdfkit_flutter_api_impl.dart"
    click PigeonIDL "https://github.com/pspdfkit/pspdfkit-flutter/blob/master/pigeons/pspdfkit.dart"
    click PigeonGen "https://github.com/pspdfkit/pspdfkit-flutter/blob/master/lib/src/api/pspdfkit_api.g.dart"
    click WebAdaptor "https://github.com/pspdfkit/pspdfkit-flutter/tree/master/lib/src/web/"
    click AndroidPlugin "https://github.com/pspdfkit/pspdfkit-flutter/tree/master/android/src/main/java/com/pspdfkit/flutter/pspdfkit/"
    click iOSPlugin "https://github.com/pspdfkit/pspdfkit-flutter/tree/master/ios/Classes/"
    click ExAndroid "https://github.com/pspdfkit/pspdfkit-flutter/tree/master/example/android/"
    click ExiOS "https://github.com/pspdfkit/pspdfkit-flutter/tree/master/example/ios/"
    click ExWebAssets "https://github.com/pspdfkit/pspdfkit-flutter/tree/master/example/web/"
    click Test "https://github.com/pspdfkit/pspdfkit-flutter/tree/master/test/"

    %% Styles
    classDef dart fill:#D0E6FF,stroke:#0273C3,color:#000
    classDef pigeon fill:#E0FFD6,stroke:#28A137,color:#000
    classDef native fill:#FFE8C1,stroke:#D9822B,color:#000
    classDef external fill:#F0F0F0,stroke:#999,color:#000
    classDef ui fill:#E8F1FF,stroke:#6699CC,color:#000
```
