# pdf4j/icepdf architecture

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

- Interactive diagram: https://gitdiagram.com/pdf4j/icepdf
- Repository: https://github.com/pdf4j/icepdf

## Overview

##### Project type and purpose
- This is a Maven multi-module Java project (“PDF4J ICEPDF”) that provides:
- A pure-Java PDF parsing and rendering engine (core)
- A Java print API and command-line tool (print)
- A Swing-based desktop viewer (viewer + viewerapp)
- A JSF-based web viewer (webviewer)
- Example client code (examples)
- Its goal is to let you embed PDF viewing, rendering, printing in Java applications or web apps.

##### File structure
Top-level modules (each with its own pom.xml):
- core
– Packages under org.icepdf.core: parser (io, util, pobjects), rendering (graphics, filters, fonts), event system, security, search
– Third-party JBIG2 decoder under org.jpedal.jbig2 (optional GPL profile)
- print
– Simple POJOs (PrintHelper, PrinterTask, PrintJobWatcher) that call core + Java Print Service
- viewer
– Swing MVC layers: controllers, view builders, view models, tools, annotation subsystems, utilities, resource bundles
- viewerapp
– Assembly module: shades viewer + core + dependencies into one self-contained JAR
- webviewer
– JSF 2.x application: Faces servlet, PdfResourceHandler, PdfRenderer servlet, managed beans (DocumentCache, DocumentManager), Facelets templates (XHTML), static resources
- examples
– Demo code for annotations, applets, extraction, print, search, signatures

##### README for additional insights
- Confirms module responsibilities, Maven GPL vs ASL profiles, how to build/run each module, published Maven artifacts, and licensing.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Core Engine and optional plugin
    CE["Core Engine\n(IO/Parser, PObject, Rendering, Security, Search)"]:::core
    JB["JBIG2 Decoder\n(Optional GPL plugin)"]:::optional

    %% Service and Platforms
    PR["Print Service API\n(PrintHelper, PrinterTask, PrintJobWatcher)"]:::print
    SV["Swing Viewer\n(Controllers, View, ViewModel, Tools, Annotations)"]:::ui
    WV["JSF Web Viewer\n(Faces Servlet, PdfRenderer, Managed Beans, Templates)"]:::web

    %% ViewerApp wrapper
    subgraph "ViewerApp\n(Self-contained JAR)"
        VA["ViewerApp"] 
    end

    %% External systems
    PS["Java Print Service"]:::external
    JSF["JSF Container\n(e.g., Tomcat)"]:::external
    JVM["JVM / AWT-Swing"]:::external

    %% Examples
    EX["Examples\n(Demos: annotation, applet, extraction, print, search)"]:::external

    %% Relationships
    SV -->|"calls core APIs"| CE
    PR -->|"renders pages via core"| CE
    PR -->|"sends to printer"| PS
    WV -->|"generates pages via core"| CE
    WV -->|"deployed on"| JSF
    CE -.->|"optional plugin"| JB
    SV -->|"runs on"| JVM

    VA --> SV
    VA --> CE

    EX --> CE
    EX --> PR
    EX --> SV
    EX --> WV

    %% Click Events
    click CE "https://github.com/pdf4j/icepdf/tree/master/core/src/main/java/org/icepdf/core"
    click JB "https://github.com/pdf4j/icepdf/tree/master/core/src/main/java/org/jpedal/jbig2"
    click PR "https://github.com/pdf4j/icepdf/tree/master/print/src/main/java/org/pdf4j/icepdf/util"
    click SV "https://github.com/pdf4j/icepdf/tree/master/viewer/src/main/java/org/icepdf/ri"
    click VA "https://github.com/pdf4j/icepdf/blob/master/viewerapp/pom.xml"
    click WV "https://github.com/pdf4j/icepdf/blob/master/webviewer/pom.xml"
    click EX "https://github.com/pdf4j/icepdf/tree/master/examples/src/main/java/org/pdf4j/icepdf/examples"

    %% Styles
    classDef core fill:#BEE3F8,stroke:#3182CE
    classDef ui fill:#C6F6D5,stroke:#2F855A
    classDef print fill:#FEEBC8,stroke:#DD6B20
    classDef web fill:#E9D8FD,stroke:#6B46C1
    classDef optional fill:#E2E8F0,stroke:#A0AEC0,stroke-dasharray:5 5
    classDef external fill:#EDF2F7,stroke:#A0AEC0,stroke-dasharray:0
```
