https://github.com/emaarco/bpmn-to-code
Gradle and Maven plugin that bridges gaps between BPMN and code - fostering the creation of clean process-automation solutions 🪴
https://github.com/emaarco/bpmn-to-code
bpmn camunda7 codegenerator java kotlin operaton zeebe
Last synced: 29 days ago
JSON representation
Gradle and Maven plugin that bridges gaps between BPMN and code - fostering the creation of clean process-automation solutions 🪴
- Host: GitHub
- URL: https://github.com/emaarco/bpmn-to-code
- Owner: emaarco
- License: mit
- Created: 2025-01-07T15:31:57.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2026-04-22T10:00:01.000Z (about 1 month ago)
- Last Synced: 2026-04-22T10:33:34.439Z (about 1 month ago)
- Topics: bpmn, camunda7, codegenerator, java, kotlin, operaton, zeebe
- Language: Kotlin
- Homepage: https://emaarco.github.io/bpmn-to-code/
- Size: 1.54 MB
- Stars: 17
- Watchers: 2
- Forks: 1
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
> **bpmn-to-code is early-stage and actively developing.**
> The four pillars — Generate, Validate, Surface, Ship — are taking shape, but expect rough edges.
> Feedback and contributions are very welcome.
[](https://emaarco.github.io/bpmn-to-code/)
[](https://bpmn-to-code.miragon.io/static/index.html)
[](https://central.sonatype.com/artifact/io.github.emaarco/bpmn-to-code-maven)
[](https://plugins.gradle.org/plugin/io.github.emaarco.bpmn-to-code-gradle)
# bpmn-to-code
Type-safe constants from your BPMN model — for your compiler, your tests, and your AI agents.
**Generate · Validate · Surface · Ship** — a type-safe BPMN toolkit for JVM projects.
## What It Does
### Generate — Type-Safe APIs
bpmn-to-code reads your BPMN files and generates typed constants from them. Every element ID, message name, and service task type becomes a compiled constant. Rename a task in the modeler → compiler error. No more silent runtime failures from hardcoded strings.
```kotlin
// Before
@JobWorker(type = "newsletter.sendConfirmationMail") // copied from modeler, no safety net
fun send() { ... }
// After — generated from the BPMN model
@JobWorker(type = NewsletterSubscriptionProcessApi.ServiceTasks.NEWSLETTER_SEND_CONFIRMATION_MAIL)
fun send() { ... }
```
### Validate — Architecture Rules for BPMN _(beta)_
Like ArchUnit for Java, `bpmn-to-code-testing` lets you write architecture tests for your BPMN models. The standalone `validateBpmnModels` Gradle task and `validate-bpmn` Maven goal run the same checks in CI.
```kotlin
BpmnValidator
.fromClasspath("bpmn/")
.engine(ProcessEngine.ZEEBE)
.validate()
.assertNoViolations()
```
11 built-in rules cover missing implementations, undefined timers, empty processes, naming violations, and variable collisions. Add custom rules by implementing `BpmnValidationRule`.
### Surface — Process Structure in Code _(beta)_
Generates a structured JSON alongside the API. Your process is readable by AI agents, code reviewers, and CI — without opening Camunda Modeler.
```json
{
"processId": "newsletterSubscription",
"flowNodes": [
{ "id": "StartEvent_SubmitRegistrationForm", "displayName": "Submit newsletter form", "elementType": "START_EVENT" },
{ "id": "Activity_SendConfirmationMail", "displayName": "Send confirmation mail", "elementType": "SERVICE_TASK" }
]
}
```
BPMN files are XML — technically readable, but full of visual layout data, namespace declarations, and rendering hints that make them noisy for AI tools. The generated JSON strips all of that away:
- **Smaller** — no diagram coordinates, waypoints, or SVG-style metadata
- **Focused** — only the elements and relationships that matter for logic and implementation
- **Structured** — flow nodes, sequence flows, messages, and errors in predictable, typed fields
The result is a compact, deterministic representation that AI agents can reason about accurately — with no hallucinated element IDs, because the JSON is derived directly from the BPMN model by rule.
### Ship — Agent Skills _(beta)_
Drop-in agent skills that automate the entire setup workflow. Integrate the plugin into your project in one prompt, scaffold a complete process service from a BPMN file, and migrate hardcoded strings to the generated API — without touching any config manually.
```bash
/plugin marketplace add emaarco/bpmn-to-code
/plugin install bpmn-to-code@bpmn-to-code
```
Works with Claude Code out of the box.
## Gradle Setup
```kotlin
plugins {
id("io.github.emaarco.bpmn-to-code-gradle") version "2.0.0"
}
tasks.named("generateBpmnModelApi", GenerateBpmnModelsTask::class) {
baseDir = projectDir.toString()
filePattern = "src/main/resources/**/*.bpmn"
outputFolderPath = "$projectDir/src/main/kotlin"
packagePath = "com.example.process"
outputLanguage = OutputLanguage.KOTLIN
processEngine = ProcessEngine.ZEEBE
}
```
## Maven Setup
```xml
io.github.emaarco
bpmn-to-code-maven
2.0.0
generate-bpmn-api
${project.basedir}
src/main/resources/*.bpmn
${project.basedir}/src/main/java
com.example.process
KOTLIN
ZEEBE
```
## Testing Module
```kotlin
dependencies {
testImplementation("io.github.emaarco:bpmn-to-code-testing:2.0.0")
}
```
## Supported Engines
| Engine | Value |
|--------|-------|
| Camunda 8 / Zeebe | `ZEEBE` |
| Camunda 7 / CIB7 | `CAMUNDA_7` |
| Operaton | `OPERATON` |
## Get It
- 📦 [Maven Central](https://central.sonatype.com/artifact/io.github.emaarco/bpmn-to-code-maven) — Maven Plugin
- 📦 [Gradle Plugin Portal](https://plugins.gradle.org/plugin/io.github.emaarco.bpmn-to-code-gradle) — Gradle Plugin
- 🌐 [Web App](https://bpmn-to-code.miragon.io/static/index.html) — Try in browser, no installation
- 🐳 [Docker Hub](https://hub.docker.com/r/emaarco/bpmn-to-code-web) — Self-hostable container
- 🤖 [MCP Server](bpmn-to-code-mcp/README.md) — AI-assisted generation inside your editor
## Project Structure
- **bpmn-to-code-core** — core parsing and generation logic
- **bpmn-to-code-gradle** — Gradle plugin
- **bpmn-to-code-maven** — Maven plugin
- **bpmn-to-code-testing** — BPMN architecture testing library
- **bpmn-to-code-web** — browser-based web app
- **bpmn-to-code-mcp** — MCP server for AI-assisted generation
## Contributing
Community contributions are welcome. Submit issues, open pull requests, or start a discussion on [GitHub](https://github.com/emaarco/bpmn-to-code).