tri-bpmn-engine

Powered by The Real Insight GmbH BPMN Engine (the-real-insight.com).

A BPMN 2.0 subset execution engine for Node.js, with event-sourced process instances, optimistic concurrency, and push-style callbacks for human tasks, service tasks, and external gateway decisions. Use it as an HTTP service (REST + WebSocket) or embed it in local mode against MongoDB.

npm package: @the-real-insight/tri-bpmn-engine

Why this project

• Deterministic execution — token flow, joins, and recorded decisions; replay-friendly event stream per instance.
• Two integration styles — REST (BpmnEngineClient + /ws) for microservices, or local (BpmnEngineClient + mongodb Db) for tests and embedded use.
• Worklist-ready — human tasks projected to /v1/tasks with claim, activate, and complete flows; optional TriSdk facade for engine + tasks in one object.
• Honest scope — implements a defined BPMN subset (see requirements); not a full Camunda/Flowable replacement.

Quick start

Prerequisites: Node.js 18+, MongoDB.

git clone <repository-url>
cd tri-bpmn-engine
npm install
cp .env.example .env
# Set MONGO_URL in .env if needed

Run the engine (API + worker + WebSocket on port 3000 by default):

npm run dev

Run the browser demo (interactive test UI; default port 9100 in npm run server):

npm run server
# Open http://localhost:9100/

Use from your app:

npm install @the-real-insight/tri-bpmn-engine

import { BpmnEngineClient } from '@the-real-insight/tri-bpmn-engine/sdk';

const client = new BpmnEngineClient({
  mode: 'rest',
  baseUrl: 'http://localhost:3000',
});

// deploy, startInstance, getState, completeUserTask, subscribeToCallbacks, …

More examples, local mode, init, and worklist patterns are in the documentation.

Documentation

| | | |---|---| | Documentation home | Index of all guides | | Getting started | Environment, ports, install, test commands | | SDK overview | Entry points, REST vs local, TriSdk | | SDK usage (full reference) | API reference, callbacks, WebSocket, worklist | | Browser demo (test UI) | Demo server features and layout | | Testing | Jest targets and conformance pointers | | Contributing | How to contribute and project expectations |

Design depth:

• Requirements & BPMN subset
• Implementation notes (MongoDB)
• Conformance matrix (table)

HTTP API (sketch)

Typical /v1 operations (see SDK and server routes for full detail):

• POST /v1/definitions — deploy BPMN
• POST /v1/instances — start instance
• GET /v1/instances/:id / .../state — inspect instance
• POST /v1/instances/:id/work-items/:workItemId/complete — complete work
• POST /v1/instances/:id/decisions/:decisionId — XOR / external decision
• GET /v1/tasks — worklist query
• WebSocket /ws — CALLBACK_WORK / CALLBACK_DECISION push (REST mode SDK)

Contributing

We welcome issues and pull requests. Please read docs/contributing.md and run npm run test:unit (plus SDK/conformance tests when you touch runtime code) before submitting.

License

Copyright (c) 2024-present The Real Insight GmbH. See LICENSE for the full license and attribution requirements (startup notice, end-user products, and documentation).

Redistribution and derivative works must keep the license file, comply with attribution, and must not remove or hide the engine’s startup attribution (see src/attribution.ts).

Publishing note

CI may bump versions and publish to npm on pushes to the default branch; configure NPM_TOKEN in GitHub Actions secrets as described in your workflow files.