Workflow Engine

The Workflow Orchestration Engine is a core component of Qarion, enabling users to define and execute complex business logic visually. It is built as a graph-based execution system.

Architecture

1. Graph Model

Workflows are represented as Directed Acyclic Graphs (DAGs) stored in JSONB.

• Nodes: Represent steps (e.g., Action, Decision, delay).
• Edges: Represent transitions between steps.

2. Execution Loop

The engine uses a stateless execution loop.

1. Hydration: Load the workflow instance and definition.
2. Validation: Verify the current state and inputs.
3. Step Execution: Execute the logic for the current node.
4. Transition: Determine the next node(s) and update the instance state.
5. Persistence: Save the new state to the database.

3. Hybrid Access Workflows

Our workflows support a "Hybrid Access" pattern, where steps can be automated (system actions) or manual (user approvals).

• Approvals: When a workflow hits an approval step, it enters a SUSPENDED state until a user provides input.
• Resumption: Upon approval, the engine "hydrates" the context and resumes execution from the next node.

Key Components

Dispatchers

The Dispatcher Bridge Pattern is used to trigger workflows from various events (API calls, Webhooks, Schedules). It decouples the trigger source from the execution engine.

Action Handlers

Each node type has a corresponding handler in the backend. These handlers are registered via a plugin system, allowing easy addition of new step types.

Hydration Traps

Standard #330: Context Preservation

A critical challenge in long-running workflows is context preservation. We strictly serialize all necessary context (variables, decisions) into the execution state to ensure that resumption (which might happen days later on a different server) has all required data.

Shadow NULL Attribute Trap

We enforce strict checks to ensure that decision nodes do not reference deleted keys or missing foreign keys, preventing runtime failures in active workflow instances.