bpmn-react

A zero-dependency BPMN 2.0 diagramming library for React — with native versioning, governance and cryptographic audit.

bpmn-react is a from-scratch implementation of a BPMN process designer. It does not depend on any third-party diagramming library — the rendering engine is native SVG driven by React, and the domain engine is pure TypeScript with zero runtime dependencies.

What makes it different from generic BPMN editors:

• Versioning as a first-class entity — every diagram carries a semantic version with a governed lifecycle: draft → test → candidate → active → deprecated → retired, enforced by a configurable state machine with multi-role promotion rules.
• Temporal immutability — versioned edges are never deleted or edited. They are closed (removedInVersion) and superseded (supersedesEdgeId), preserving a complete lineage for audit.
• Cryptographic audit ledger — an append-only, SHA-256 hash-chained ledger records every change; any retroactive tampering breaks the chain and is detected by verify().
• BPMN 2.0 XML interoperability — import/export with full BPMN DI (shapes, bounds, waypoints), pools & lanes (collaboration/participant, laneSet with interactive membership), messageFlow and association, so diagrams round-trip with Camunda Modeler and bpmn.io tools. Custom properties travel inside standard extensionElements.
• Extensible by design — custom node types, shapes, palette items, validation rules and XML mappings are registered through a declarative plugin object. Your domain vocabulary lives in a plugin, not in a fork.

Packages

Package	Description
@buildtovalue/core	Domain engine: model, events, commands, lifecycle, rules, validation, diff, audit, geometry, XML. Pure TypeScript, runs headless (browser, Node, workers).
@buildtovalue/react	React layer: SVG canvas, shapes, gestures (drag/connect/zoom/pan), palette, inspector, minimap, diff view. Peer deps: react, react-dom.
@buildtovalue/registry	Headless version governance: queryable registry with temporal validity (activeAt), publication channels/environments, diff/lineage, dual changelog and execution pinning (bindRun).
@buildtovalue/domain-example	Example domain plugin (squads, personas, gates, prompts, connectors, deliverables) showing how to extend the core.
@buildtovalue/conformance	OMG conformance tooling: interoperability corpus (50+ files), element-by-element matrix, certifyXml.
@buildtovalue/soundness	Structural soundness analysis: deadlock/livelock/dead-branch rules over the process graph (O(V+E), scope-aware), plugin-compatible.
@buildtovalue/audit	Demonstrable integrity: hash-chain ledger verification (verifyLedger), canonical promotion attestations (attestVersion), XES 2.0 export for process mining (toXES).
@buildtovalue/dmn	DMN family (wheel step 185°): DRD node types/shapes, requirement edges (straight routing) and a DMN 1.3+ XML converter. Workspace-only until the npm-scope decision (pendências §1).
@buildtovalue/healthcare	Healthcare pack (wheel step 305°): clinical vocabulary mapped to interoperable BPMN (bpmnr:meta preserves identity) with visible validation for unlinked clinical decisions. Workspace-only until the npm-scope decision (pendências §1).
@buildtovalue/library	Generic artifact catalog for BuildToValue Studio: ArtifactAdapter contract + headless search/filter/sort — knows nothing about BPMN; adapters plug in. Workspace-only until the npm-scope decision (pendências §1).
@buildtovalue/library-react	React UI for the generic library: gallery with status/type chips, search, cards and detail drawer — driven exclusively by the adapter contract. Workspace-only until the npm-scope decision (pendências §1).
@buildtovalue/adapters-bpmn	Concrete ArtifactAdapters over the registry (flow, persona, prompt, connector, policy, DMN decision) + headless SVG thumbnails + the "recipe" acid-test fixture. Workspace-only until the npm-scope decision (pendências §1).
@buildtovalue/studio	BuildToValue Studio: shell with hash navigation + Revisão do Aprovador (engine-derived queue, real verification calls, immutable ledger decisions — approving never activates). Workspace-only until the npm-scope decision (pendências §1).
@buildtovalue/cli	Headless CLI: validate, certify, export, diff, registry/governance commands.
@buildtovalue/example	Demo app (Vite) with the full designer.

Quick start

pnpm add @buildtovalue/core @buildtovalue/react

import { createDiagram } from '@buildtovalue/core';
import { BpmnDesigner } from '@buildtovalue/react';

const diagram = createDiagram({ name: 'Order fulfilment' });

export function App() {
  return <BpmnDesigner diagram={diagram} onChange={(d) => console.log(d)} />;
}

Read-only rendering:

import { BpmnViewer } from '@buildtovalue/react';

<BpmnViewer diagram={diagram} />;

Development

pnpm install
pnpm build          # build all packages
pnpm test           # unit tests (Vitest)
pnpm typecheck
pnpm lint
pnpm --filter @buildtovalue/example dev   # run the demo app

Documentation

• Getting started
• Architecture
• Plugins
• Versioning & governance
• Version registry (channels, validity, run pinning)
• BPMN 2.0 XML format profile
• Known limitations

Stability & versioning

All packages are released in lockstep and follow semantic versioning from 1.0.0:

• The public API is the set of documented exports of each package — frozen by the apiSurface.test.ts contract tests, so any accidental surface change fails CI.
• Breaking changes only happen in major versions, preceded by a deprecation period (deprecated APIs keep working for at least one minor release and log a warning).
• New capabilities (e.g. additional BPMN profile elements, new routers) arrive in minor versions; fixes in patches.
• The BPMN XML profile is itself versioned: documents exported today will always re-import in future 1.x releases.

See CHANGELOG.md for release history.

BPMN 2.0 conformance

The import/export profile covers the OMG Descriptive class at 100% (declarable) and the Analytic class at 100% — the full element-by-element matrix lives in CONFORMANCE.md (generated; freshness enforced in CI) and is exercised by a 50+ file interoperability corpus. Third parties can verify their own documents with bpmn-react certify <file.bpmn> [--require descriptive|analytic].

Known limitations (summary)

• The BPMN 2.0 XML converter supports a documented profile (see docs/format-spec.md), not the full ~500-page OMG spec. Unknown elements are ignored with warnings on import.
• SVG rendering is optimized for diagrams up to ~300–400 elements. Virtualization and a canvas fallback for larger graphs are on the roadmap (post-1.0).
• No built-in multi-user collaboration (CRDT) — planned as a future layer.
• PNG export requires all fonts/styles to be inlined in the SVG (browser canvas security); external assets would taint the canvas.
• The XML parser validates structure, not the official XSD schema. It rejects DOCTYPE/DTD by design (XXE-safe).

License

Apache 2.0 — see also NOTICE. All code in this repository is original work; architectural inspiration from publicly documented design patterns is credited in NOTICE.