Architecture Overview
This document describes the runtime architecture of the Rust BPM Engine. It focuses on execution semantics, not modeling tools or BPMN specifications.
Scope
This architecture document defines:
- How workflows are executed at runtime
- How state progresses via events
- How concurrency, failure, and recovery are handled
It explicitly does not cover:
- BPMN XML specifications
- Visual modeling or low-code tooling
- UI concerns
Core Abstractions
Process Definition
A static graph describing the workflow structure.
- Nodes (Start, Service, User, Gateway, End)
- Sequence flows
Process Instance
A running instance of a process definition.
- Holds variables
- Owns tokens
- Has a lifecycle (Running / Completed / Terminated)
Token
Token is the unit of execution.
A token represents execution authority at a specific node.
- Multiple tokens enable parallelism
- Tokens advance independently
Execution Model
- Tokens move through the process graph
- Nodes are executed by consuming a token
- Execution produces events
All state transitions are driven by events, not direct calls.
See: execution-model.md
Event-driven Core
- Engine reacts to immutable events
- Event handlers are deterministic and transactional
- Handlers may emit new events
This guarantees:
- Observability
- Replayability
- Crash safety
Concurrency Model
- Concurrency is token-scoped
- A token can only be executed by one executor at a time
- Optimistic locking (CAS) prevents conflicts
Parallel join is protected by uniqueness constraints.
Failure & Compensation
- Failures are first-class events
- Long-running consistency is achieved via Saga
- Compensation executes in reverse order
See: saga.md
Crash Recovery
- All engine state is persisted
- Tokens can be rehydrated after crashes
- Execution always continues forward
See: recovery.md
Design Principles
- Token over thread
- Event over call stack
- Compensation over rollback
- Persistence over memory
This document serves as the contract between architecture and implementation.