# BPMN Kit

> A TypeScript SDK for building, modeling, simulating, and deploying BPMN processes on Camunda 8.

## Packages

- [@bpmnkit/core](https://github.com/bpmnkit/monorepo/tree/main/packages/core): Fluent process builder, BPMN 2.0 parser/serializer, DMN support, AI-compact format (compactify/expand), auto-layout (Sugiyama algorithm), SVG export (zero third-party deps, all runtimes). Multi-process support: Bpmn.createDiagram() assembles caller/callee process pairs in one definitions document. Full branching inside sub-processes (exclusiveGateway, parallelGateway, branch()). Ergonomic boundary events via withBoundary() — cursor auto-restores to main flow after the error path. Includes 29 TypeScript type guard predicates (isBpmnServiceTask, isBpmnGateway…), typed error classes (ParseError, ValidationError — instanceof-catchable), and element lookup utilities (findElement, getZeebeExtensions, etc.)
- [@bpmnkit/engine](https://github.com/bpmnkit/monorepo/tree/main/packages/engine): BPMN simulation engine, zero third-party dependencies (browser + Node.js) — service tasks, user tasks, gateways, timers, message correlation, DMN evaluation
- [@bpmnkit/api](https://github.com/bpmnkit/monorepo/tree/main/packages/api): Camunda 8 REST API client — 180 typed methods, 30+ resource classes, OAuth2 / Bearer / Basic auth, LRU+TTL cache, exponential backoff, TypedEventEmitter
- [@bpmnkit/canvas](https://github.com/bpmnkit/monorepo/tree/main/packages/canvas): Zero-third-party-dependency SVG BPMN viewer with pan/zoom, dark/light theme, plugin API
- [@bpmnkit/editor](https://github.com/bpmnkit/monorepo/tree/main/packages/editor): Full BPMN editor — canvas + properties panel + AI bridge + storage
- [casen (CLI)](https://github.com/bpmnkit/monorepo/tree/main/apps/cli): Interactive TUI for managing Camunda 8 from the terminal: processes, jobs, incidents, decisions, variables, messages

## Key Features

- Fluent builder API: chain .startEvent().serviceTask().exclusiveGateway().branch()...
- Multi-process definitions: Bpmn.createDiagram(id) assembles multiple processes (caller/callee, sub-flows) into one BPMN definitions document
- Sub-process branching: full gateway and branch() support inside subProcess() callbacks, with auto-join insertion
- Ergonomic boundary events: .withBoundary(id, options, handler) attaches error/timeout paths and auto-restores the main flow cursor
- Auto-layout: Sugiyama algorithm produces clean diagrams with no coordinate math
- AI-native: compact intermediate format fits an entire diagram in a single LLM prompt
- Camunda 8 ready: native Zeebe task definitions, IO mappings, connectors, forms
- Roundtrip fidelity: parse → modify → export without data loss
- SVG export: generate diagram images from BpmnDefinitions — zero third-party deps, works in Node.js, browser, Deno, Bun
- Type guards: 29 predicates (isBpmnServiceTask, isBpmnGateway…) narrow BpmnFlowElement unions at compile time
- Typed errors: ParseError and ValidationError extend a common BpmnSdkError base — all instanceof-catchable with error codes
- Element lookup utilities: findElement, findProcess, getZeebeExtensions and friends traverse parsed diagrams
- Full JSDoc coverage: @param, @returns, @throws, @example on every public API
- Simulation engine: deploy and run processes locally, register job workers, evaluate DMN
- REST API client: full Camunda 8 Orchestration Cluster API coverage
- CLI: arrow-key TUI, connection profiles, tabular results

## Quick Start

```typescript
import { Bpmn, exportSvg } from "@bpmnkit/core";

const defs = Bpmn.createProcess("hello")
  .startEvent("start")
  .serviceTask("task", {
    name: "Hello World",
    taskType: "greet",
  })
  .endEvent("end")
  .withAutoLayout()
  .build();

const xml = Bpmn.export(defs); // ✓ BPMN 2.0 XML
const svg = exportSvg(defs);   // ✓ SVG image, zero deps
```

## Documentation

### Getting Started

- [Installation](https://bpmnkit.com/docs/getting-started/installation): Install BPMN Kit packages in your project.
- [Quick Start](https://bpmnkit.com/docs/getting-started/quick-start): Build and run your first BPMN process in minutes.
- [Core Concepts](https://bpmnkit.com/docs/getting-started/concepts): Understand how the builder, serializer, auto-layout, and AI-compact format work.

### Guides

- [Building Processes](https://bpmnkit.com/docs/guides/building-processes): Service tasks, user tasks, events, sub-processes, boundary events, multi-process diagrams, and multi-instance patterns.
- [Gateways & Branching](https://bpmnkit.com/docs/guides/gateways): Exclusive, parallel, inclusive, and event-based gateways with condition expressions.
- [Pattern Library](https://bpmnkit.com/docs/guides/patterns): Domain BPMN patterns that Claude uses as context when implementing processes with /bpmnkit:implement.
- [Simulation](https://bpmnkit.com/docs/guides/simulation): Run BPMN processes locally with @bpmnkit/engine — no Camunda cluster required.
- [Camunda 8 Deployment](https://bpmnkit.com/docs/guides/deployment): Deploy and manage BPMN processes on a live Camunda 8 cluster using @bpmnkit/api.
- [Standalone Workers](https://bpmnkit.com/docs/guides/workers-standalone): Build, run, and deploy TypeScript workers that connect to Zeebe without any BPMNKit dependency.
- [AI Integration](https://bpmnkit.com/docs/guides/ai): Use BPMN Kit with LLMs to generate and modify process diagrams from natural language.
- [Building Processes with AI](https://bpmnkit.com/docs/guides/ai-implement): Go from a natural language description to a deployed, tested BPMN process — via a deterministic ProcessPlan pipeline, never hand-written XML.
- [AI Agents](https://bpmnkit.com/docs/guides/ai-agents): Add a Camunda 8 AI Agent Sub-process to a BPMN process — an LLM-in-the-loop step that can call tools, generated deterministically like everything else in the pipeline.
- [Claude Code Plugin](https://bpmnkit.com/docs/guides/claude-code-plugin): Install the bpmnkit plugin for Claude Code to get AI-first BPMN development and operations — generate diagrams, wire connectors, deploy, and resolve incidents from natural language.

### Packages

- [@bpmnkit/core](https://bpmnkit.com/docs/packages/core): Fluent process builder, BPMN 2.0 parser/serializer, auto-layout, and AI-compact format.
- [@bpmnkit/engine](https://bpmnkit.com/docs/packages/engine): Zero-dependency BPMN simulation engine for browsers and Node.js.
- [@bpmnkit/api](https://bpmnkit.com/docs/packages/api): Fully-typed Camunda 8 REST API client with OAuth2, caching, and retry.
- [@bpmnkit/canvas](https://bpmnkit.com/docs/packages/canvas): Zero-dependency SVG BPMN viewer with pan/zoom, dark/light theme, and plugin API.
- [@bpmnkit/editor](https://bpmnkit.com/docs/packages/editor): Full BPMN editor — canvas, properties panel, AI bridge, and storage.
- [@bpmnkit/worker-client](https://bpmnkit.com/docs/packages/worker-client): Thin Zeebe REST client for standalone workers — no BPMNKit SDK required at runtime.
- [@bpmnkit/connector-gen](https://bpmnkit.com/docs/packages/connector-gen): Generate Camunda REST connector element templates from OpenAPI 3.x and Swagger 2.x specs.
- [@bpmnkit/docspack](https://bpmnkit.com/docs/packages/docspack): BPMN Kit documentation as an offline, version-locked package that AI agents can install and search.

### CLI

- [casen CLI](https://bpmnkit.com/docs/cli/casen): Interactive TUI for managing Camunda 8 clusters from the terminal.
- [casen generate](https://bpmnkit.com/docs/cli/generate): Generate BPMN files from built-in templates, CompactDiagram JSON, or by patching an existing file.
- [casen view](https://bpmnkit.com/docs/cli/view): View BPMN, DMN, and Camunda form files in the browser via a local server.
- [casen connector](https://bpmnkit.com/docs/cli/connector): Browse the bundled Camunda 8 connector catalog, or generate connector element templates from OpenAPI specs, via the casen CLI.
- [AIKit Skills](https://bpmnkit.com/docs/cli/skills): Claude Code slash commands for AI-driven process implementation, review, testing, and deployment.
- [casen Plugins](https://bpmnkit.com/docs/cli/plugins): Official casen CLI plugins shipped with the BPMN Kit monorepo.
- [casen Plugin Authoring](https://bpmnkit.com/docs/cli/plugin-authoring): Build and publish plugins that extend the casen CLI with new command groups.

## Links

- [Live Editor](https://bpmnkit.com/editor): Visual BPMN editor with AI-assisted editing and process simulation
- [GitHub](https://github.com/bpmnkit/monorepo): Source code, issues, and contribution guide
- [npm](https://www.npmjs.com/org/bpmnkit): Package registry

## Optional

- [Full content (llms-full.txt)](https://bpmnkit.com/llms-full.txt): All site and documentation content with extended code examples