bpmn-to-code

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.

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.

// 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.

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.

{
  "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.

/plugin marketplace add Miragon/bpmn-to-code
/plugin install bpmn-to-code@bpmn-to-code

Works with Claude Code out of the box.

Gradle Setup

plugins {
    id("io.miragon.bpmn-to-code-gradle") version "3.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