The Workflow Execution Engine is the core system responsible for orchestrating and executing workflow definitions through a DAG-based (Directed Acyclic Graph) execution model. It manages the entire lifecycle from trigger reception through block-by-block execution to final output delivery, supporting multiple execution modes including streaming responses, background jobs, and human-in-the-loop pause/resume patterns.
The execution engine is structured around three primary layers: the entry layer (API routes and background jobs), the orchestration layer (preprocessing, snapshot management, and core execution), and the execution layer (DAG executor and block handlers).
The following diagram maps high-level execution concepts to the specific classes and functions implemented in the codebase.
Sources: apps/sim/app/api/workflows/[id]/execute/route.ts:74-75, apps/sim/lib/workflows/executor/execution-core.ts17-42 apps/sim/executor/execution/block-executor.ts51-67 apps/sim/executor/execution/executor.ts6-20 apps/sim/executor/index.ts1-7 apps/sim/background/workflow-execution.ts136-165 apps/sim/background/schedule-execution.ts139-225
The execution pipeline processes workflow requests through distinct phases: trigger reception, preprocessing, serialization, DAG execution, and output delivery.
Workflow executions are initiated via several entry points defined in the API and background workers:
| Trigger Type | Entry Point | Authentication | Execution Mode |
|---|---|---|---|
| Manual / API | POST /api/workflows/[id]/execute | checkHybridAuth | Inline or Async |
| Webhook | executeWebhookJob | Provider Signature | Background Job |
| Schedule | executeScheduleJob | Trigger.dev Internal | Background Job |
| Child Workflow | WorkflowBlockHandler | Internal Context | Inline Sub-execution |
Sources: apps/sim/app/api/workflows/[id]/execute/route.ts:5-15, apps/sim/executor/handlers/workflow/workflow-handler.ts38-68 apps/sim/background/workflow-execution.ts136-165 apps/sim/background/schedule-execution.ts139-157 apps/sim/app/api/webhooks/trigger/[path]/route.ts:161-182
All executions pass through preprocessExecution apps/sim/lib/execution/preprocessing.ts36 which validates requests and enforces constraints such as authentication, rate limits, and deployment status. In the API layer, the ExecuteWorkflowSchema apps/sim/app/api/workflows/[id]/execute/route.ts:76-116 validates the incoming payload before passing it to executeWorkflowCore.
The execution engine maintains state through ExecutionSnapshot, LoggingSession, and the ExecutionContext.
ExecutionSnapshot apps/sim/executor/execution/snapshot.ts1-50 encapsulates all data required to execute or resume a workflow. It includes blockStates, executedBlocks, blockLogs, and decisions (for routers and conditions).
LoggingSession apps/sim/lib/logs/execution/logging-session.ts37 manages execution log lifecycle and database persistence. It provides methods to ensure logs are written even if execution fails, as seen in background job implementations apps/sim/background/workflow-execution.ts188-193
The DAGExecutor apps/sim/executor/execution/executor.ts6 (aliased as Executor in apps/sim/executor/index.ts6) is the central orchestrator. It builds a dependency graph and executes nodes in topological order.
The BlockExecutor apps/sim/executor/execution/block-executor.ts51 handles the lifecycle of an individual block's execution:
BlockHandler via findHandler apps/sim/executor/execution/block-executor.ts74VariableResolver to resolve parameters apps/sim/executor/execution/block-executor.ts111handler.executeWithNode or handler.execute apps/sim/executor/execution/block-executor.ts133-135handleStreamingExecution apps/sim/executor/execution/block-executor.ts145-153NormalizedBlockOutput apps/sim/executor/execution/block-executor.ts155-160BlockStateWriter with results and duration apps/sim/executor/execution/block-executor.ts182The ConditionBlockHandler apps/sim/executor/handlers/condition/condition-handler.ts83 evaluates logic to determine the next execution path. It uses evaluateConditionExpression apps/sim/executor/handlers/condition/condition-handler.ts24-29 which leverages an isolated VM (via function_execute tool) to safely execute JavaScript conditions apps/sim/executor/handlers/condition/condition-handler.ts38-58
The engine supports complex control flow via specialized orchestrators:
for, forEach, while, and doWhile loops. It handles iteration indexing and exit conditions.The execution engine supports real-time output delivery through Server-Sent Events (SSE) and callback functions.
ExecutionContext apps/sim/executor/types.ts33-36 includes hooks for execution events:
onBlockStart: Fired when a block begins apps/sim/executor/execution/block-executor.ts90onBlockComplete: Fired when a block finishes apps/sim/executor/execution/block-executor.ts192-203onStream: Handles streaming content from blocks like Agents apps/sim/executor/execution/block-executor.ts144The useWorkflowExecution hook apps/sim/app/workspace/[workspaceId]/w/[workflowId]/hooks/use-workflow-execution.ts:104-104 manages the frontend execution state. It uses useExecutionStream apps/sim/app/workspace/[workspaceId]/w/[workflowId]/hooks/use-workflow-execution.ts:157-157 to process SSE events and updates the useExecutionStore and useTerminalConsoleStore to reflect block status and logs in the UI.
The WorkflowBlockHandler apps/sim/executor/handlers/workflow/workflow-handler.ts38 allows workflows to call other workflows inline.
validateCallChain apps/sim/executor/handlers/workflow/workflow-handler.ts87-93lazyCleanupInputMapping apps/sim/executor/handlers/workflow/workflow-handler.ts127-132Executor instance for the child workflow, propagating context and abort signals apps/sim/executor/handlers/workflow/workflow-handler.ts171-185The PauseResumeManager apps/sim/lib/workflows/executor/human-in-the-loop-manager.ts44 manages the lifecycle of "Human-in-the-loop" blocks.
contextId generated via generatePauseContextId apps/sim/executor/execution/block-executor.ts26SerializableExecutionState is saved when a workflow pauses apps/sim/executor/execution/types.ts28runFromBlock logic in the execute route loads the snapshot and restarts the DAGExecutor from the specified block apps/sim/app/api/workflows/[id]/execute/route.ts:94-115.Logs are processed into TraceSpan objects apps/sim/lib/logs/execution/trace-spans/trace-spans.ts6 for hierarchical display in the Terminal.
This diagram shows how execution events travel from the backend handlers to the frontend Terminal UI.
Sources: apps/sim/stores/terminal/console/store.ts144-160 apps/sim/app/workspace/[workspaceId]/w/[workflowId]/utils/workflow-execution-utils.ts:132-151, apps/sim/app/workspace/[workspaceId]/w/[workflowId]/hooks/use-workflow-execution.ts:110-119, apps/sim/hooks/use-execution-stream.ts1-16
useTerminalConsoleStore apps/sim/stores/terminal/console/store.ts1-26 maintains a list of ConsoleEntry items, which are updated in real-time as SSE events arrive apps/sim/app/workspace/[workspaceId]/w/[workflowId]/utils/workflow-execution-utils.ts:206-215.Sources: apps/sim/executor/types.ts29-36 apps/sim/stores/terminal/console/store.ts12-24 apps/sim/app/workspace/[workspaceId]/w/[workflowId]/utils/workflow-execution-utils.ts:189-204
Refresh this wiki