Declarative Java DSL for structured business PDFs.
Describe what the document says; the engine resolves layout, pagination, themes, and PDFBox rendering. Cinematic by default.

Release status — 🟢 Latest stable: v1.8.0 — codenamed "illustrative": native vector charts, SVG & gradient graphics, free-form clipping, and a leaner engine artifact. What's new in v1.8 ↓

 ·  🟡 In develop: next cycle — open (see CHANGELOG)  ·  See API stability policy for tier definitions.

Live Showcase  ·  Examples Gallery  ·  Docs  ·  Changelog

_{☝ This banner is itself a GraphCompose document — view the full capability deck (PDF), rendered by EngineDeckExample: native vector charts and real comparative benchmarks, all drawn by the engine. It renders its own marketing.}

Why GraphCompose

• Author intent, not coordinates. Fluent DSL for sections, paragraphs, tables, lists, layer stacks, themes — the engine handles measurement, pagination, and rendering.
• Deterministic by design. Two-pass layout. Snapshots are stable across machines, so layout regressions are catchable in tests before any byte ships.
• Cinematic by default. BusinessTheme, soft panels, accent strips, transforms, native vector charts, and gradients are first-class primitives, not workarounds.
• PDFBox isolated, DOCX optional. Single backend interface. Apache POI–backed DOCX export is available for compatible semantic content — see support matrix for limitations.

Sits between iText (low-level page primitives) and JasperReports (XML-template-driven layout): a Java DSL describes the document semantically, the engine renders.

What's new in v1.8

The "illustrative" release — the engine gains a vector-graphics dimension.

• Native vector charts — bar / line / pie, inline sparklines, and MONOTONE / SMOOTH line interpolation, drawn as native PDF Béziers (no rasterization): section.chart(ChartSpec.line()…, style).
• SVG path & icon import — SvgIcon.parse(svg) turns SVG into native vector geometry; recolour per use and place with addSvgIcon(icon, width, align).
• Gradients & free-form clipping — linear / radial DocumentPaint fills and arbitrary ShapeOutline.Path clip regions.
• Block-level alignment — addAligned(HorizontalAlign.CENTER, node) centres or right-aligns any fixed node without a wrapper container.
• keepTogether() pagination — keep a section from splitting across a page break.
• Leaner publication — the bundled Google fonts moved to the independently-versioned graph-compose-fonts artifact, so the engine jar dropped from ~20 MB to ~2 MB. Pure-text / standard-14 documents need nothing extra; add graph-compose-fonts (or graph-compose-bundle) to keep the bundled families — see the migration note.

Core document APIs stay source- and binary-compatible with v1.7 (ConfigLoader is the one removal). Full notes in CHANGELOG.md.

Installation

Requires Java 17+ (enforced by the build).

<dependency>
    <groupId>io.github.demchaav</groupId>
    <artifactId>graph-compose</artifactId>
    <version>1.8.0</version>
</dependency>

dependencies { implementation("io.github.demchaav:graph-compose:1.8.0") }

Bundled fonts (from v1.8.0). The curated Google fonts no longer ship inside the engine jar — they live in an independently-versioned companion artifact so an engine upgrade never re-downloads ~18 MB of fonts. Pure-text and standard-14 documents need nothing extra; to use the bundled families, add:

<dependency>
    <groupId>io.github.demchaav</groupId>
    <artifactId>graph-compose-fonts</artifactId>
    <version>1.0.0</version>
</dependency>

Prefer a single "batteries-included" coordinate? Depend on io.github.demchaav:graph-compose-bundle (same version as graph-compose above) to pull the engine + fonts together. Full details and upgrade steps: the v1.8.0 fonts migration note.

Distribution — Maven Central is the canonical channel from v1.6.6 onwards (io.github.demchaav:graph-compose:<version>). Hosted Javadocs auto-publish to javadoc.io/doc/io.github.demchaav/graph-compose shortly after each Central release. The legacy JitPack URL (com.github.DemchaAV:GraphCompose:v<version>) remains resolvable for callers pinned to v1.6.5 and earlier but is no longer the documented install option.

Upgrading from v1.5? Core document authoring stays source-compatible — engine, DSL, themes, and backend-neutral records carry v1.5 callers unchanged. Templates v2 replaces the legacy CV / cover-letter template classes; legacy classes were deleted, not deprecated. Read the migration guide before upgrading template-heavy code.

Hello world

import com.demcha.compose.GraphCompose;
import com.demcha.compose.document.api.DocumentPageSize;
import com.demcha.compose.document.api.DocumentSession;
import com.demcha.compose.document.theme.BusinessTheme;

import java.nio.file.Path;

class Hello {
    public static void main(String[] args) throws Exception {
        BusinessTheme theme = BusinessTheme.modern();

        try (DocumentSession document = GraphCompose.document(Path.of("hello.pdf"))
                .pageSize(DocumentPageSize.A4)
                .pageBackground(theme.pageBackground())
                .margin(28, 28, 28, 28)
                .create()) {

            document.pageFlow(page -> page
                    .addSection("Hero", section -> section
                            .softPanel(theme.palette().surfaceMuted(), 10, 14)
                            .accentLeft(theme.palette().accent(), 4)
                            .addParagraph(p -> p.text("GraphCompose").textStyle(theme.text().h1()))
                            .addParagraph(p -> p.text("A theme-driven hero, no manual coordinates.")
                                    .textStyle(theme.text().body()))));

            document.buildPdf();
        }
    }
}

For a Spring Boot @RestController streaming the PDF straight to the response, see HttpStreamingExample.

Scope and comparison

Output support

When to use GraphCompose

• Server-side PDF generation in Java — invoices, CVs, reports, proposals, statements, schedules.
• Templated documents from data — themed presets (ModernProfessional, InvoiceTemplateV2, …) you parameterise instead of re-styling every time.
• Regression-tested layouts — DocumentSession#layoutSnapshot() makes layout changes visible in PRs before any byte ships; PdfVisualRegression adds a pixel-level gate for font and colour fidelity.
• Streaming PDFs from web backends — Spring Boot @RestController writing straight to the response (HttpStreamingExample).
• Higher-level than PDFBox, lighter than JasperReports — Java DSL describes semantics; no XML templates, no manual coordinates.

What GraphCompose is not

• Not a hosted PDF rendering service — it is a library you embed.
• Not a WYSIWYG editor — the DSL is code, not drag-and-drop.
• Not a reporting engine like JasperReports — no datasource bindings, no XML templates, no compiled .jasper files.
• Not a browser / HTML-to-PDF renderer — the engine has its own layout pipeline; HTML/CSS input is not supported.

Compared with similar Java libraries

GraphCompose uses PDFBox under the hood as the rendering backend — the comparison is about authoring surface, not the renderer.

Which API should I use?

Choosing a template surface — layered (cv.v2), classic (cv.presets), or the built-in *TemplateV2 family? See Which template system should I use? for the status matrix, decision tree, and classic → layered migration map.

v1.8 primitives in 30 lines

Three snippets from the new vector surfaces. Full runnable versions live in the examples gallery.

Native chart — categories + series in, native vector bars out (no rasterization).

ChartData revenue = ChartData.builder()
    .categories("Q1", "Q2", "Q3", "Q4")
    .series("2024", 12.4, 15.1, 9.8, 14.2)
    .series("2025", 14.0, 18.2, 11.3, 16.9)
    .build();
section.chart(ChartSpec.bar().data(revenue)
    .legend(LegendPosition.BOTTOM)
    .size(ChartSize.aspectRatio(16, 7))
    .build());

Overshoot-free line — a smooth curve constrained to never overshoot the data range.

section.chart(ChartSpec.line().data(series)
    .interpolation(LineInterpolation.MONOTONE)
    .build());

SVG import + alignment — parse SVG to native geometry, seat any fixed node across the width.

SvgIcon globe = SvgIcon.parse(svgMarkup);
flow.addSvgIcon(globe, 48, HorizontalAlign.CENTER);
flow.addAligned(HorizontalAlign.RIGHT, anyFixedNode);

Architecture

GraphCompose splits into a public canonical surface you author against (com.demcha.compose.document.*) and an internal shared engine foundation (com.demcha.compose.engine.*, marked @Internal) that resolves geometry, pagination, and rendering behind it. You author intent; the engine resolves the rest.

flowchart LR
    A["GraphCompose.document(...)<br/>DocumentSession · DocumentDsl"] --> B["DocumentNode tree<br/>document.node"]
    B --> C["LayoutCompiler<br/>document.layout"]
    C --> D["Engine foundation @Internal<br/>measure → paginate → place"]
    D --> E{Backend}
    E -->|PDF| F["PdfFixedLayoutBackend"]
    E -->|DOCX| G["DocxSemanticBackend · POI"]
    D -.->|layoutSnapshot| H["Deterministic snapshot<br/>(regression tests)"]

Full detail: architecture overview · package map · lifecycle.

Documentation

📚 Full docs index — categorised map of every doc, ADR, and recipe. Start there to navigate the documentation.

Templates

• 🆕 Templates — v2 layered architecture — the canonical going-forward pattern for new template families (CV v2 is the reference implementation). Personas: quickstart · using templates · authoring presets · contributing a new family.
• Templates v1-classic landing — the older BusinessTheme / CvSpec CV / cover-letter / invoice / proposal preset library (deprecated — CV + cover letter are superseded by v2-layered; invoice / proposal / schedule are not yet ported). Cheat sheet: authoring.

Architecture & operations

• Architecture overview · Lifecycle · Production rendering · Layout snapshot testing · Troubleshooting

Recipes & examples

• Recipes index — shape-as-container · shapes · transforms · page-backgrounds · layered-page-design · absolute-placement · tables · themes · streaming · extending · font-coverage
• Examples gallery — every runnable example with PDF preview

Contributing & releases

• Contributing · Code of conduct · Security policy · Release process
• API stability policy · Which template system? · Migration v1.6 → v1.7 · Migration v1.5 → v1.6

Companion projects

• graphcompose-ai-flow — experimental sister project exploring an AI-assisted authoring flow on top of GraphCompose. Independent codebase, separate lifecycle — nothing in this repo depends on it. Track it if you are interested in agentic document composition driven by the same semantic node model.

License

MIT — see LICENSE.

Star History