Lightweight visual workflow engine for orchestrating long-running project lifecycles. Designed as a standalone library that integrates into Apitomy products (starting with Axiom).
- Defines workflows as directed graphs with conditional edge routing
- Executes workflows through a stateless engine (state in, state out)
- Supports human-in-the-loop tasks and external event correlation
- Provides a visual drag-and-drop editor and read-only instance viewer
- Validates workflow definitions with 27 structural and semantic rules
Two independent components, side by side:
| Component | Path | Technology | Purpose |
|---|---|---|---|
| Engine | engine/ |
Java 21 / Maven | Stateless workflow execution library |
| Visual Editor | ui/ |
React 19 / TypeScript / Vite | Editor and viewer components |
The engine is a pure Java library with no framework dependencies (no Quarkus, CDI, JPA). All dependencies (node executors, event listeners, error handler) are passed via constructor. Workflow instance state is a single JSON document — the consuming application handles persistence.
The visual editor is a React component library exporting WorkflowEditor and WorkflowViewer.
It uses @xyflow/react for the canvas and PatternFly 6
for UI chrome.
| Type | Purpose |
|---|---|
| Start | Entry point with input schema. Supports conditional routing based on initial context. |
| Action | Automated work. Delegates to a NodeExecutor provided by the host application. |
| Human Task | Blocks until a human responds. Engine interprets description, inputs (label-to-expression map), and outputs (form schema) from config. |
| Receive Event | Blocks until a matching external event arrives. Supports EL-based correlation. |
| Wait | Blocks for a configured duration (ISO 8601). The consuming application schedules the wake-up. |
| End | Terminal state with outcome metadata. |
- Java 21+
- Maven 3.9+
- Node.js 22+
./build.shThis builds both the engine (Maven) and the UI (npm + Vite).
To build components individually:
# Engine only
cd engine && mvn clean install
# UI only
cd ui && npm install && npm run lint && npm test && npm run buildTo run the visual editor dev app:
cd ui
npm install
npm run devThe dev server starts at http://localhost:5173 with a sample CVE triage workflow loaded in both the editor and viewer tabs.
// Create executors for your action types
NodeExecutor analyzeExecutor = new NodeExecutor() {
public String actionType() { return "analyze-cve"; }
public NodeResult execute(NodeExecutionContext context) {
// do work...
return new NodeResult(NodeResultStatus.COMPLETED, Map.of("severity", "high"));
}
};
// Build the engine
WorkflowEngine engine = new WorkflowEngine(
NodeExecutorProvider.fromList(analyzeExecutor), // node executor provider
List.of(myEventListener), // event listeners
myErrorHandler // error handler (optional)
);
// Start a workflow
WorkflowInstance instance = engine.startWorkflow(workflowDefinition, Map.of("cveId", "CVE-2024-1234"));
// Complete a human task
instance = engine.completeCurrentNode(workflowDefinition, instance,
new NodeResult(NodeResultStatus.COMPLETED, Map.of("affected", true)));
// Check if an event matches a waiting instance
boolean matches = engine.matchesEvent(workflowDefinition, instance, eventPayload);
// Cancel a workflow
instance = engine.cancelWorkflow(workflowDefinition, instance);engine/ Java workflow engine library
src/main/java/io/apitomy/flow/
model/ Workflow, WorkflowNode, WorkflowEdge, WorkflowInstance, HumanTaskInfo, ReceiveEventInfo
engine/ WorkflowEngine, ConditionEvaluator, JsonNodeELResolver
spi/ NodeExecutor, WorkflowEventListener, WorkflowErrorHandler
validation/ WorkflowValidator (47 rules)
ui/ React visual editor components
src/
components/ WorkflowEditor, WorkflowViewer, custom nodes/edges, panels
validation/ TypeScript workflow validator (46 rules)
types/ TypeScript types mirroring the Java model
See CONTRIBUTING.md for guidelines on how to contribute to this project.