Bpmn Generator

BPMN Generator

[](https://github.com/Stieges/bpmn-generator/actions/workflows/ci.yml) [](LICENSE)

BPMN 2.0 diagram generator — converts natural language process descriptions or structured JSON into OMG-compliant BPMN 2.0.2 XML files and SVG previews (ISO/IEC 19510:2013).

Why this one

Three things you can verify in the repo, not just claim:

1. Multi-pool collaborations with lanes and message flows render fully. The closest open-source comparable (bpmn-auto-layout@1.3.0, used by BPMN Assistant) silently drops every participant after the first plus all inter-pool message flows ([data](EVALUATION.md#bpmn-auto-layout-comparison)). Our pipeline renders all participants and all message flows.
2. Strict JSON Schema gate at every HTTP API entry. LLM output cannot reach the layout engine with malformed Logic-Core — ajv draft-2020-12 rejects it at the boundary ([scripts/schema-gate.js](scripts/schema-gate.js)).
3. Native Claude Code MCP server. Exposed as a [Skill](SKILL.md) and via [scripts/mcp-bpmn-server.js](scripts/mcp-bpmn-server.js). The LLM never touches coordinates — it emits Logic-Core JSON, the pipeline handles layout deterministically.

Reproduce the comparison: cd scripts && node bench/compare-bpmn-auto-layout.mjs — produces [tests/bench/auto-layout-comparison.md](tests/bench/auto-layout-comparison.md) + side-by-side HTML.

See [EVALUATION.md](EVALUATION.md) for the full benchmark, the competitor matrix, and honest notes about where ProMoAI and BPMN Assistant are stronger.

Visual examples

Single-pool linear flow + exclusive gateway Two pools, three lanes, message flows — what bpmn-auto-layout drops

One pool, four lanes (Frontend / Backend / Ops / QA) Expanded subprocess with inner activities

Full gallery: [docs/screenshots/](docs/screenshots/). All SVGs regenerated from fixtures by the pipeline — they reflect current output, not stale marketing screenshots.

How we compare (verified)

| Capability | This generator | ProMoAI | BPMN Assistant | BPMN-Chatbot | |---|---|---|---|---| | Multi-pool with lanes + message flows | ✅ verified | ✅ | ❌ (bpmn-auto-layout limitation) | ? | | Strict JSON Schema input gate (ajv) | ✅ | n/a | partial | partial | | Soundness check | WF-Net (3 rules) | POWL by construction | none | none | | Configurable rule engine | 28 rules, 4 layers, JSON profiles | limited | none | none | | MCP server | ✅ | ❌ | ❌ | ❌ | | Stack | Node.js / ES Modules | Python / Streamlit | Python + Vue.js | React + OpenAI | | License | MIT | GPL-3.0 | MIT-ish | unclear | | Paper | none (engineering) | IJCAI-24, EMMSAD 2024 | arXiv 2509.24592 | CEUR-WS Vol-3758 |

Each ✅ on our row links back to a fixture, a benchmark, or a source file. See [EVALUATION.md](EVALUATION.md) for cell-by-cell evidence and honest notes on where competitors are stronger (ProMoAI's mathematical soundness guarantee, BPMN Assistant's web UI).

What It Does

You describe a business process — either as free text or as a structured JSON (Logic-Core) — and the generator produces:

• A BPMN 2.0 XML file (.bpmn) that opens in bpmn.io, Camunda Modeler, or any standard-compliant tool
• An SVG preview with all BPMN symbols, lanes, pools, and edge routing
• A validation report covering structural correctness, naming conventions, and complexity metrics

The output is structurally valid and OMG-compliant. It handles pools, lanes, gateways, boundary events, sub-processes, message flows, and loop markers correctly — things that LLMs typically get wrong when generating BPMN XML directly.

Realistic Expectations

This tool produces a solid first draft, not a finished diagram. Expect to refine:

• Layout — Auto-layout handles most cases well (happy-path alignment, orthogonal routing, lane partitioning), but complex processes with many cross-lane edges or feedback loops may need manual adjustment in a BPMN editor
• Labels & naming — The LLM generates reasonable names, but domain-specific terminology may need correction
• Edge cases — Unusual gateway patterns, deeply nested sub-processes, or very large diagrams (30+ activities) can produce suboptimal visual results
• Business logic — The generator models what you describe; it doesn't validate whether your process makes business sense

Think of it as going from 0% → 80% in seconds. The remaining 20% is domain expertise that requires human judgment.

Pipeline

User Text → [Phase 1] Intent Extraction (LLM → JSON Logic-Core)
          → [Phase 2] Validation (28 rules, 4 layers, deadlock detection)
          → [Phase 3] Auto-Layout (ElkJS Sugiyama layered algorithm)
          → [Phase 4] Serialization → BPMN 2.0 XML + SVG

The LLM never handles coordinates. Layout is 100% algorithmic.

Quick Start

cd scripts/
npm install          # installs elkjs + jest

# Generate from JSON Logic-Core:
node pipeline.js my-process.json my-process

# From stdin:
echo '{ ... }' | node pipeline.js - output

# Import existing BPMN:
node import.js existing.bpmn extracted.json

# DOT export (Graphviz):
node pipeline.js my-process.json my-process --dot

# DOT import → Logic-Core JSON:
node pipeline.js graph.dot output --import-dot

# Run tests:
npm test

Output: output.bpmn (BPMN 2.0 XML) + output.svg (vector preview)

Usage as Claude Code Skill

In a specific project

Copy SKILL.md to .claude/skills/operative/bpmn-prozess-erstellen.md and adjust the relative paths for references/ and scripts/ to match where you placed those directories.

As a portable .skill file

The bpmn-generator-v3.skill ZIP archive can be shared with other projects. It contains everything needed:

• SKILL.md — Skill definition
• references/ — Schema, prompt templates, inline template
• scripts/ — Pipeline modules, import.js, package.json

Module Architecture

scripts/
├── pipeline.js        Orchestrator + CLI (~180 LOC)
│   ├── validate.js    Validation wrapper → rules.js
│   ├── rules.js       Rule engine (28 rules, 4 layers, profile support) — see `references/fachliches-regelwerk.md` for the catalog
│   ├── topology.js    Gateway directions, topological sort, lane ordering
│   ├── layout.js      ELK graph construction + layout execution
│   ├── coordinates.js Coordinate maps, edge clipping, pool equalization
│   ├── bpmn-xml.js    BPMN 2.0 XML generation (DI, top-level defs)
│   ├── svg.js         SVG rendering (pools, lanes, activities, events)
│   ├── icons.js       Event markers, task icons, bottom markers
│   ├── dot.js         DOT export (Logic-Core → Graphviz) + import
│   ├── types.js       Type predicates, BPMN XML tag mapping
│   └── utils.js       Config loader, visual constants, helpers
├── import.js          BPMN XML → Logic-Core JSON round-trip importer
├── orchestrator.js    Multi-agent state machine + CLI
├── agents/
│   ├── modeler.js     LLM-powered: text→JSON, refine, amend
│   ├── reviewer.js    Deterministic: validateLogicCore() wrapper
│   ├── layout.js      runPipeline() + optional vision review
│   ├── compliance.js  Deterministic: runRules() gate
│   └── llm-provider.js OpenAI-compatible fetch abstraction (cloud + local)
├── workflow-net.js    Petri-Net soundness checker (WF01-WF03)
├── prepare-training-data.js  Training data ETL (BPMN→LC, filter, JSONL)
├── evaluate-slm.js    SLM evaluation (pipeline-based metrics)
├── mcp-bpmn-server.js MCP server (4 tools)
├── http-server.js     HTTP API (5 endpoints)
├── config.json        Externalized constants (shapes, colors, gaps)
├── package.json       Dependencies (elkjs, jest)
├── pipeline.test.js   114 tests (Jest, ES Modules)
└── orchestrator.test.js 22 tests (agents + state machine)

Dependency graph (acyclic):

types.js ← (no deps)
utils.js ← (no deps, reads config.json)
rules.js ← types, workflow-net
workflow-net.js ← types
validate.js ← rules
topology.js ← types
layout.js ← types, utils, topology, elkjs
coordinates.js ← types, utils
icons.js ← utils
bpmn-xml.js ← types, utils, topology, icons
svg.js ← types, utils, icons
dot.js ← types
pipeline.js ← all of the above

Repo Structure

bpmn-generator/
├── README.md                             This file
├── LICENSE                               MIT License
├── CHANGELOG.md                          Version history
├── CONTRIBUTING.md                       Contribution guide
├── THIRD-PARTY-NOTICES.md                Dependency licenses
├── SKILL.md                              Claude Code skill definition
├── CLAUDE.md                             Project instructions for Claude Code
├── ROADMAP.md                            Development roadmap (K0-K8, M1-M6, L1-L6)
├── COMPATIBILITY.md                      bpmn.io compatibility report
├── bpmn-generator-v3.skill               Portable ZIP archive
├── .github/workflows/ci.yml             GitHub Actions CI
├── references/
│   ├── logic-core-schema.md              JSON schema documentation (prose)
│   ├── input-schema.json                 Formal JSON Schema (draft 2020-12)
│   ├── prompt-template.md                LLM prompt templates + few-shot patterns
│   ├── inline-template.md                HTML template for browser-side ElkJS
│   ├── fachliches-regelwerk.md           Rule documentation (authoritative catalog — per-rule source citations)
│   ├── omg-compliance.md                 OMG BPMN 2.0.2 compliance mapping
│   └── review-set/                       Test fixtures for visual review
├── rules/
│   ├── default-profile.json              Default rule profile (all layers active)
│   └── strict-profile.json               Strict profile (warnings → errors)
├── scripts/                              Pipeline modules (see above)
└── tests/
    └── fixtures/                         Test input files (JSON Logic-Core)

Rule Engine

28 rules across 4 layers with configurable severity via JSON profiles. The authoritative catalog lives in [references/fachliches-regelwerk.md](references/fachliches-regelwerk.md); this README does not duplicate per-rule descriptions.

| Layer | Severity | Rules | Examples | |-------|----------|-------|----------| | Soundness | ERROR | S01-S12 | Start/End events, deadlocks, boundary events | | Style | WARNING | M01-M10 (M05/M06 severity=OFF) | Naming conventions, gateway labels | | Pragmatics | INFO | P01-P03 | Complexity metrics | | Workflow-Net | ERROR/WARNING | WF01-WF03 | Liveness, boundedness, deadlock-freedom (opt-in) |

# Default profile (all layers active):
node pipeline.js input.json output

# Strict profile (style warnings → errors):
# (programmatic: runPipeline(lc, { ruleProfile: 'rules/strict-profile.json' }))

See references/fachliches-regelwerk.md for full rule documentation.

Programmatic API

import { runPipeline } from './pipeline.js';

const logicCore = { nodes: [...], edges: [...] };
const result = await runPipeline(logicCore);

// result.bpmnXml   — BPMN 2.0 XML string (or null on validation error)
// result.svg       — SVG string
// result.coordMap  — coordinate map
// result.validation — { errors: [], warnings: [] }

Individual modules can be imported directly:

import { validateLogicCore } from './validate.js';
import { generateBpmnXml } from './bpmn-xml.js';
import { generateSvg } from './svg.js';
import { logicCoreToDot, dotToLogicCore } from './dot.js';

Features

• Multi-pool collaborations with message flows
• All BPMN 2.0 task types (User, Service, Script, Send, Receive, Manual, Business Rule)
• Call Activity, Sub-Process, Transaction with correct rendering
• Expanded sub-processes with inline children
• Boundary events (timer, error, message, signal, escalation — interrupting/non-interrupting)
• All gateway types with correct gatewayDirection (Diverging/Converging/Mixed)
• Loop/multi-instance markers (standard loop, parallel MI, sequential MI)
• Data objects, data stores, text annotations, groups, associations
• Collapsed pools (black-box participants)
• Round-tripping (BPMN XML → Logic-Core JSON → BPMN XML)
• DOT format (Graphviz export + import for visualization)
• Inline mode (browser-side ElkJS rendering without Node.js)
• Configurable rule engine (28 rules, 4 layers, JSON profiles)
• OMG BPMN 2.0.2 compliant XML output (ISO/IEC 19510:2013)
• BPMN-in-Color (bioc: namespace — per-node fill/stroke in XML + SVG)
• Documentation View (SVG tooltips + --doc Markdown companion)
• Happy-Path Y-Leveling (post-layout alignment, configurable)
• Visual Refinement Pass (opt-in post-layout polish — see below)
• MCP Server (generate, validate, import as MCP tools)
• bpmn.io compatible (verified with bpmn-js viewer)

Visual Refinement (opt-in)

Post-layout coordinate transforms that polish BPMN diagrams without changing semantics. Default enabled: false — existing pipeline output stays byte-identical.

• Pass 1 — Dynamic per-pool lane-header widths with multi-line wrapping (long lane/pool names no longer clip)
• Pass 2 — compactLanes: reduces lane padding (~45px per non-empty lane on typical layouts, ~10–20% canvas shrink on multi-lane diagrams)
• Pass 3 — Edge label collision repair via bbox-nudge
• Pass 5 — ELK MULTI_EDGE wrapping for wide pipelines (>20 nodes)

Enable via config:

{
  "visualRefinement": {
    "enabled": true,
    "minLaneHeight": 80
  }
}

Or per-call:

const result = await runPipeline(logicCore, { visualRefinement: true });

Design spec: [docs/superpowers/specs/2026-04-21-bpmn-visual-refinement-pass-design.md](docs/superpowers/specs/2026-04-21-bpmn-visual-refinement-pass-design.md)

Multi-Agent Orchestration

The orchestrator chains 4 agents in a feedback loop until the diagram is valid and compliant:

Modeler (LLM) → Reviewer → Layout/Pipeline → Compliance → Done
   ↑               │              │
   └───────────────┘              │  (Review loop: max 3)
   ↑                              │
   └──────────────────────────────┘  (Layout loop: max 2)

# Review-only (no LLM needed):
node scripts/orchestrator.js --input logic-core.json --output /tmp/result

# Full cycle with LLM (text → BPMN):
node scripts/orchestrator.js --text "Process description..." \
  --api-url https://api.example.com/v1 --api-key KEY --model gpt-4.1 \
  --output /tmp/result

import { orchestrate } from './orchestrator.js';

// Without LLM — review + generate + compliance only:
const result = await orchestrate(logicCoreJson);

// With LLM — full text-to-BPMN cycle:
const result = await orchestrate('Process description...', { llmProvider });

MCP Server

The BPMN Generator can be used as an MCP (Model Context Protocol) server, exposing four tools:

| Tool | Description | |------|-------------| | generate_bpmn | Logic-Core JSON → BPMN 2.0 XML + SVG | | validate_bpmn | Validate Logic-Core without generating output | | import_bpmn | BPMN 2.0 XML → Logic-Core JSON | | orchestrate_bpmn | Multi-agent review + generate + compliance |

Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "bpmn-generator": {
      "command": "node",
      "args": ["/path/to/scripts/mcp-bpmn-server.js"]
    }
  }
}

HTTP API

The BPMN Generator also provides an HTTP API for multi-user access (CI/CD pipelines, web apps, external systems):

| Method | Path | Description | |--------|------|-------------| | POST | /api/v1/generate | Logic-Core JSON → BPMN 2.0 XML + SVG | | POST | /api/v1/validate | Validate Logic-Core without generating output | | POST | /api/v1/import | BPMN 2.0 XML → Logic-Core JSON | | POST | /api/v1/orchestrate | Multi-agent review + generate + compliance | | GET | /health | Health check (uptime, version) |

Start

PORT=3000 node scripts/http-server.js

Req

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Stieges
• Source: Stieges/bpmn-generator
• License: MIT

Install and usage instructions live in the source repository linked above.