SmartEngine: a small BPMN engine shaped by internal use at Alibaba

An engine built for the inside of a large technology company

SmartEngine is a lightweight business orchestration engine, and the project states that it is used widely in Alibaba Group. That sentence is the most informative thing in the README, because it explains both the design and the audience.

The described uses are two. The first is orchestrating multiple services in a microservice architecture, starting and signalling a process instance in a high-performance way with low storage cost. The second is traditional process approval scenarios, the kind of multi-step human sign-off workflow that every large organisation runs internally.

Those two use cases pull in different directions, and the design philosophy section is where the project resolves the tension. It lists five commitments: keep it simple, standardize on BPMN 2.0 and a ubiquitous language, stay extensible in areas such as the parser, behaviour, storage and user integration, provide a simple way to improve performance and reduce storage cost in simple process scenarios, and depend on as little as possible.

The last one is phrased as an intention rather than a promise, since the project says that at the very beginning they tried their best to avoid JAR hell. Reading the code and the dependency tree is the way to see how well that held, and it is a reasonable thing to check before you adopt a library that will sit in the middle of your service mesh.

The code is Java, the build is Maven, and the licence is Apache 2.0.

The supported BPMN vocabulary is short, and that is a design choice

The feature list names the BPMN symbols that are supported: StartEvent, EndEvent, SequenceFlow, ExclusiveGateway, ParallelGateway, InclusiveGateway, ServiceTask and ReceiveTask.

That is eight element types, and the list is deliberately narrower than the BPMN 2.0 specification. The project states the goal as supporting basic BPMN symbols, and the design philosophy entry on standardization says the engine embraces BPMN 2.0 and specifies a ubiquitous language. The two statements sit together: the vocabulary is standard, but only the common part of it.

For a business process that is a sequence of steps with a couple of branching decisions and a service call, this covers everything. For a process that needs timers, boundary events, subprocesses, escalation or complex event handling, it does not, and the project does not claim otherwise.

The consequence is that a team should check its own diagrams against that list before evaluating anything else. A flow that a general purpose engine can draw in an afternoon may not be drawable here at all, and knowing that in the first conversation is cheaper than discovering it during an implementation.

The other feature worth noting from the same list is the emphasis on reducing storage cost. The project states this twice, once as a design principle and once as a feature, which suggests it is where the engineering effort went.

CQRS-style APIs separate commands from queries

The first item in the main feature list is CQRS-style APIs to start, signal, query process instance, task and activity. The naming convention tells you the shape of the API surface.

A CQRS-style design here means the write side and the read side are separate concerns. To start or signal a process, you issue a command, and to look at a process instance, a task or an activity, you issue a query. For a microservice estate, that split is not decoration. A service that orchestrates others should be able to answer questions about state without holding the write path, and should be able to accept a signal without exposing the whole model as a mutable object.

The verbs are also specific. Starting a process and signalling it are separate operations, which is what allows a process to be advanced by an external event rather than only by its own internal transitions. Querying is broken down by the entity you care about, instance, task or activity, rather than by one blob endpoint that returns a whole process graph.

This is the part of the API that has to match how your own services talk to each other, so it is worth reading the wiki documentation for the API details rather than guessing from names.

Four capabilities that go beyond drawing a diagram

The feature list ends with a short section headed Other, and it names four things that are not really BPMN diagram features at all: Process Jump, VariablePersister, TaskAssigneeDispatcher and Countersign.

These are the parts that make an engine useful for the approval scenarios the project mentions, and they are worth reading as a set.

Process Jump is about moving execution from one place to another rather than following the drawn path, which is what you need when a workflow has an escape route or a correction step. VariablePersister is about how process variables are stored, which connects directly to the low storage cost goal and to the storage extension point in the design philosophy.

TaskAssigneeDispatcher is about who a task goes to, separating the decision of assignment from the task itself, which is what lets you integrate with an organisational model or an external directory. Countersign is the multi-party sign-off, the case where a task has to be approved by several people rather than one.

A reader who only looks at the BPMN symbol list will underestimate this project. These four extensions are where a business orchestration engine earns its keep, and each of them maps onto a concrete problem in approval workflows. Whether the defaults fit your organisation is a separate question that the wiki documentation has to answer.

core, extension and docs are the three parts of the tree

The repository layout is small, and it maps onto the design philosophy more directly than most projects.

core/
extension/
pom.xml

The core directory holds the engine itself, the extension directory is where the optional pieces live, and pom.xml is the Maven build. A docs directory sits alongside them, and the README points at a GitHub wiki as the documentation home, so the documentation is not in the tree but next to it.

The extension directory is the visible expression of the extensibility commitment. The design philosophy names four extension areas explicitly, the parser, behaviour, storage and user integration, and each of those is a place where the behaviour of the engine can be changed without forking it. In practice that means you can substitute how a process definition is read, how a transition behaves, where process state is persisted, or how user identities are resolved, and keep the rest of the engine untouched.

Two more details in the tree are worth noting. There is a .run directory, which is the JetBrains IDE run configuration folder, so the project ships its own launch profiles. And there are two changelogs, CHANGELOG.md and CHANGELOG-zh.md, alongside a Chinese README, README-zh.md, with a link between the two READMEs at the top. The project is maintained bilingually, which is a small but real detail for anyone contributing.

Irregular release tags and a long gap before the 3.x line

The release history is where the project's own maintenance story has to be read carefully, because the tags are not consistent.

The most recent release is v4.0.0 from 2026-03-26. Before it is a tag written as v.3.5.0, titled release v.3.5.0, dated 2025-05-07, and before that v2.6.1 from 2021-12-15. So the version gap between the 2.x line and the 3.x line is more than three years, and the tags themselves use two different naming conventions.

The last push was on 2026-07-24 and the repository is not archived, so work is still happening on master, and the changelog files in the repository root are where the detail of what changed between those versions lives. Given that the gap is long and the version numbers jump, reading the changelog is not optional if you are evaluating the current state, because a great deal may have changed under the same API.

The licence is Apache 2.0, with the text in the LICENSE file at the root. The README closes by saying the project is inspired by Activiti, MyBatis and Netty, which is a useful hint about the shape of the code, the data mapping layer and the networking foundation, and it tells you where to look if you are trying to understand why a particular design choice was made.

Documentation lives in the GitHub wiki, and the README lists a WeChat group and a contact identifier for reaching the maintainers.

Editorial conclusion

Adopt SmartEngine when you need a process engine that stays out of the way, that you can extend at the parser, behaviour, storage or user integration points, and that has to run inside a microservice estate where process state should not be expensive to store. Do not adopt it if you need the full BPMN 2.0 specification, because the supported symbol list is short and deliberate, and treat the documentation in the wiki as the primary source, since the repository README is a summary. Before the first evaluation, read the CHANGELOG.md file to see what the jump from the 2.x line to 3.x and then 4.0 actually changed, and check the API you need against the four extra capabilities, since Process Jump, VariablePersister, TaskAssigneeDispatcher and Countersign are the parts most likely to matter to a business process.

Frequently asked questions

Official sources

1. alibaba/SmartEngine on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases