process-engine-blueprints

One business process, built on every major BPMN engine. Pick the setup you need and start from working, production-shaped code instead of a blank page.

Why

Engine tutorials stop at a happy-path service task. A real project starts with dozens of decisions around the engine: how the code talks to it, where it runs, how the model and the code stay in step, how you test a process end to end, what CI and dependency updates look like. Each of them takes time to get right, and most teams make them again from scratch.

These blueprints make those decisions once, for one realistic process. MiraVelo, a fictional bike brand, leases its bikes, and the leasing application runs from the first request to an active lease, with a DMN decision, timers, messages, escalations, compensation and user tasks along the way. What you get:

• A fair comparison. Every example automates the same process behind the same REST API and the same test scenarios. The engine and the integration style are the only things that change, so you compare like with like.
• A complete start. Hexagonal architecture enforced by tests, a typed process API generated from the model, process tests, API scenarios, mutation testing, pinned dependencies and CI, all already in place.
• Only what you need. One command turns one example in one language into your project. You get no monorepo and no other engines, and the package and the name are yours.
• Your language. Every engine example comes in Kotlin + Gradle and in Java + Maven, with the same behaviour.
• Ready for agents. Each example brings AGENTS.md and Claude Code skills for the tasks you will do next: automate a process step, add a delegate, a controller or a persistence adapter.

Examples

Example	Engine	Setup	Language
cibseven-embedded	CIB seven	embedded	Kotlin · Java
cibseven-process-engine-api	CIB seven	embedded	Kotlin · Java
cibseven-remote	CIB seven	remote	Kotlin · Java
fullstack-cibseven-embedded	CIB seven	embedded	Kotlin
operaton-embedded	Operaton	embedded	Kotlin · Java
operaton-process-engine-api	Operaton	embedded	Java
operaton-remote	Operaton	remote	Kotlin · Java
zeebe-native	Camunda 8 (Zeebe)	remote	Kotlin · Java

Embedded runs the engine inside your service, remote in its own engine host or Camunda 8 cluster. The name says how the service talks to it. Unsure? Four questions help.

Quick start

Nothing to install and nothing published anywhere: npx runs the starter straight from this repository. You need Node 22+, git, and read access to the repository.

npx --allow-git=root github:miragon-blueprints/process-engine-blueprints my-service

It asks where the engine should run, which blueprint and which language you want, and your package name. Then it creates a project that builds, with a fresh git history. Without questions:

npx --allow-git=root github:miragon-blueprints/process-engine-blueprints my-service --example cibseven-embedded --lang kotlin --package com.acme.leasing

--allow-git=root lets npm 12 and later run a package from git, which they refuse by default. --ref <branch or tag> starts from another state of the examples than main, --list shows the examples.

Working on an example

Open the example's folder, not the repository root. Its README, AGENTS.md, skills and Conductor targets treat that folder as the project.

cd examples/cibseven-embedded
npm ci                                            # the example's BPMN tooling
docker compose -f stack/docker-compose.yml up -d  # its local stack

Training material links to examples/<example>/README.md. These paths stay: an example folder is never renamed without a pointer at the old path.

Contributing

See CONTRIBUTING.md. How CI, Dependabot and drift checks work is described in docs/maintaining.md, and the decisions behind this repository are in docs/adr.

License

MIT