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.
- 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.
The "illustrative" release — the engine gains a vector-graphics dimension.
- Native vector charts — bar / line / pie, inline sparklines, and
MONOTONE/SMOOTHline 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 withaddSvgIcon(icon, width, align). - Gradients & free-form clipping — linear / radial
DocumentPaintfills and arbitraryShapeOutline.Pathclip 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-fontsartifact, so the engine jar dropped from ~20 MB to ~2 MB. Pure-text / standard-14 documents need nothing extra; addgraph-compose-fonts(orgraph-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.
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 asgraph-composeabove) 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.
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.
| Format | Status | Notes |
|---|---|---|
| Production | Fixed-layout backend on PDFBox 3.0. Full DSL coverage. | |
| DOCX | Partial | Semantic export via Apache POI. Unsupported nodes (shape, line, ellipse, barcode) are dropped silently — layout fidelity is best-effort for paragraph / list / table content. |
| PPTX | Skeleton | Validates supported node types and emits a manifest. Not a real PowerPoint export yet — planned only if there is demand. |
- 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;PdfVisualRegressionadds a pixel-level gate for font and colour fidelity. - Streaming PDFs from web backends — Spring Boot
@RestControllerwriting straight to the response (HttpStreamingExample). - Higher-level than PDFBox, lighter than JasperReports — Java DSL describes semantics; no XML templates, no manual coordinates.
- 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
.jasperfiles. - Not a browser / HTML-to-PDF renderer — the engine has its own layout pipeline; HTML/CSS input is not supported.
| Library | API style | Layout | License | Best for |
|---|---|---|---|---|
| GraphCompose | Java DSL, semantic nodes | Two-pass, deterministic, snapshot-testable | MIT | Code-first business documents with layout regression tests |
| PDFBox | Low-level text / path primitives | Manual coordinates | Apache 2.0 | Direct PDF manipulation, parsing, extraction |
| iText 7 | Object/layout API + low-level canvas | Automatic layout with direct-positioning options | AGPL / commercial | When AGPL is acceptable or you have a commercial licence |
| OpenPDF | iText 4 fork | Manual + helpers | LGPL / MPL | Legacy iText 4 codebases |
| JasperReports | XML templates compiled to .jasper |
Template-driven | LGPL | Tabular reports with datasource bindings |
GraphCompose uses PDFBox under the hood as the rendering backend — the comparison is about authoring surface, not the renderer.
| You want to… | Surface | Entry point |
|---|---|---|
| Generate a one-off PDF programmatically | DSL | GraphCompose.document(...).pageFlow(...) — see Hello world above |
| Generate a CV / cover letter from data | Layered templates | ModernProfessional.create().compose(session, cvDocument) — see layered templates |
| Add a custom visual primitive | Engine extension | NodeDefinition + PdfFragmentRenderHandler — see extension guide |
| Regression-test generated layouts | Layout snapshots | DocumentSession#layoutSnapshot() — quickstart at Testing your document; full reference at snapshot testing |
| Pixel-test the rendered PDF (fonts, colours, anti-aliasing) | Visual regression | PdfVisualRegression.standard()…assertMatchesBaseline(...) — see visual regression testing |
| See the live gallery | Static showcase site | Showcase — source under web/, deployed to GitHub Pages via the Pages workflow |
Choosing a template surface — layered (
cv.v2), classic (cv.presets), or the built-in*TemplateV2family? See Which template system should I use? for the status matrix, decision tree, andclassic → layeredmigration map.
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);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.
📚 Full docs index — categorised map of every doc, ADR, and recipe. Start there to navigate the documentation.
- 🆕 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/CvSpecCV / 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 overview · Lifecycle · Production rendering · Layout snapshot testing · Troubleshooting
- 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 · Code of conduct · Security policy · Release process
- API stability policy · Which template system? · Migration v1.6 → v1.7 · Migration v1.5 → v1.6
- 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.
MIT — see LICENSE.