# mirakl/openhtmltopdf architecture

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

- Interactive diagram: https://gitdiagram.com/mirakl/openhtmltopdf
- Repository: https://github.com/mirakl/openhtmltopdf

## Overview

##### Main Components
- Input/Parsing Layer: Represent the starting point where well-formed XML/XHTML (or some crafted HTML5) and associated CSS is provided. This part likely relies on third‐party HTML/CSS parsers (for instance, JSoup or native Java DOM parsers).
- Plugins/Extension Modules: These include distinct submodules such as:
- OpenHTMLtoPDF-Core: The central library code.
- SVG Support (openhtmltopdf-svg-support): Processes SVG images using libraries like Apache Batik.
- MathML Support (openhtmltopdf-mathml-support): For rendering MathML content.
- Java2D Output Module (openhtmltopdf-java2d): Optionally outputs the render to images using Java2D routines.
- PDFBox Integration (openhtmltopdf-pdfbox and related modules): Responsible for converting the visual layout into PDF documents using Apache PDFBox.
- Modules for RTL support, barcode objects (from the objects module), and additional template processing.
- Output Layer: The final output is the PDF document (or raster images), which are produced by the rendering engine when it processes the layout.
- Auxiliary/testing and example modules: These include the “openhtmltopdf-examples”, “tests” folder with subdirectories (diff, regress, etc.) that indicate an extensive automated visual regression testing and example implementations.

##### Relationships and Data Flow
- Data flows from the user-provided document (HTML/CSS) into the Parsing Layer.
- During rendering, the layout engine queries the appropriate plugins (like the SVG or MathML components) if it encounters specialized markup.
- The output from the layout engine is then handed to a rendering device, which may either be a PDF creation engine (using PDFBox) or a Java2D-based image generator.
- The system supports plug-in style extension points (for object drawers, font resolution, output device configuration, etc.) that can be seen in certain modules.
- The testing modules run side-by-side to ensure visual output consistency through regression tests.

##### Architectural Patterns and Design Principles
- Modular design: The project is broken into several Maven modules (core, examples, various support modules) so each can be developed, tested, and maintained independently.
- Separation of concerns: Parsing, layout, rendering, and special plugin handling are separated into different packages and modules.
- Extensibility: With clearly defined extension points (e.g., client-supplied font resolvers, custom object drawers, and resource controlling mechanisms), the design adheres to the open/closed principle.
- Use of External Libraries: Integration with Apache PDFBox for PDF generation and Apache Batik for SVG rendering is an important architectural decision that drives component interactions.
- Testing & Regression: The presence of extensive test cases and visual regression tests indicates a design that heavily depends on constant feedback from automated tests to maintain rendering accuracy.

##### Technologies and Subsystems
- Components utilize Java 8 or later (as noted in the README).
- Core rendering with dependencies on PDFBOX and Batik.
- CSS parser and processing – both custom code and third-party libraries are used for interpreting and cascading styles.
- A multi-module Maven project, with modules such as openhtmltopdf-core, openhtmltopdf-java2d, openhtmltopdf-pdfbox, etc.
- Integration with build tools (Maven, GitHub Actions workflows) and automated testing frameworks (JUnit).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Layer
    subgraph "Input Layer"
        input["HTML/CSS Input"]:::input
    end

    %% Processing Layer
    subgraph "Processing Layer"
        core["OpenHTMLtoPDF-Core"]:::core
        layout["Layout Engine"]:::core
        css["CSS Parser/Styling"]:::core
    end

    %% Plugin Modules
    subgraph "Plugin Modules"
        svg["SVG Support"]:::plugin
        mathml["MathML Support"]:::plugin
        rtl["RTL Support"]:::plugin
        objects["Object Drawers"]:::plugin
    end

    %% Output Layer
    subgraph "Output Layer"
        pdfbox["PDFBox Integration"]:::output
        java2d["Java2D Renderer"]:::output
    end

    %% Auxiliary & Testing
    subgraph "Auxiliary & Testing"
        templates["Templates & Examples"]:::aux
        testing["Automated Testing"]:::aux
        pdfuatest["PDF/UA Testing"]:::aux
    end

    %% Data Flow Connections
    input -->|"ingests HTML/CSS"| core
    core -->|"builds render tree"| layout
    core -->|"parses CSS"| css

    layout -->|"calls for SVG"| svg
    layout -->|"calls for MathML"| mathml
    layout -->|"calls for RTL"| rtl
    layout -->|"calls for objects"| objects

    layout -->|"renders PDF"| pdfbox
    layout -->|"renders Images"| java2d

    core -->|"integrates"| templates
    core -->|"validated by"| testing
    core -->|"tested by"| pdfuatest

    %% Click Events
    click core "https://github.com/mirakl/openhtmltopdf/tree/open-dev-v1/openhtmltopdf-core"
    click layout "https://github.com/mirakl/openhtmltopdf/tree/open-dev-v1/openhtmltopdf-core/src/main/java/com/openhtmltopdf/layout"
    click layout "https://github.com/mirakl/openhtmltopdf/tree/open-dev-v1/openhtmltopdf-core/src/main/java/com/openhtmltopdf/render"
    click css "https://github.com/mirakl/openhtmltopdf/tree/open-dev-v1/openhtmltopdf-core/src/main/java/com/openhtmltopdf/css"
    click svg "https://github.com/mirakl/openhtmltopdf/tree/open-dev-v1/openhtmltopdf-svg-support"
    click mathml "https://github.com/mirakl/openhtmltopdf/tree/open-dev-v1/openhtmltopdf-mathml-support"
    click rtl "https://github.com/mirakl/openhtmltopdf/tree/open-dev-v1/openhtmltopdf-rtl-support"
    click objects "https://github.com/mirakl/openhtmltopdf/tree/open-dev-v1/openhtmltopdf-objects"
    click java2d "https://github.com/mirakl/openhtmltopdf/tree/open-dev-v1/openhtmltopdf-java2d"
    click pdfbox "https://github.com/mirakl/openhtmltopdf/tree/open-dev-v1/openhtmltopdf-pdfbox"
    click pdfuatest "https://github.com/mirakl/openhtmltopdf/tree/open-dev-v1/openhtmltopdf-pdfa-testing"
    click templates "https://github.com/mirakl/openhtmltopdf/tree/open-dev-v1/openhtmltopdf-templates"
    click templates "https://github.com/mirakl/openhtmltopdf/tree/open-dev-v1/openhtmltopdf-examples"
    click testing "https://github.com/mirakl/openhtmltopdf/tree/open-dev-v1/tests"

    %% Styles
    classDef input fill:#f9f,stroke:#333,stroke-width:2px;
    classDef core fill:#bbf,stroke:#333,stroke-width:2px;
    classDef plugin fill:#fc3,stroke:#333,stroke-width:2px;
    classDef output fill:#cfc,stroke:#333,stroke-width:2px;
    classDef aux fill:#fdd,stroke:#333,stroke-width:2px;
```
