Workflow System

Relevant source files

• apps/sim/app/api/chat/[identifier]/route.test.ts
• apps/sim/app/api/chat/utils.test.ts
• apps/sim/app/api/webhooks/trigger/[path]/route.test.ts
• apps/sim/app/api/webhooks/trigger/[path]/route.ts
• apps/sim/app/api/workflows/[id]/execute/route.ts
• apps/sim/app/api/workflows/[id]/log/route.ts
• apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/editor/hooks/use-subflow-editor.ts
• apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/terminal/utils.ts
• apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/workflow-block/workflow-block.tsx
• apps/sim/app/workspace/[workspaceId]/w/[workflowId]/hooks/use-workflow-execution.ts
• apps/sim/app/workspace/[workspaceId]/w/[workflowId]/workflow.tsx
• apps/sim/background/schedule-execution.ts
• apps/sim/background/webhook-execution.ts
• apps/sim/background/workflow-execution.ts
• apps/sim/executor/dag/builder.test.ts
• apps/sim/executor/dag/builder.ts
• apps/sim/executor/dag/construction/edges.test.ts
• apps/sim/executor/dag/construction/edges.ts
• apps/sim/executor/dag/construction/nodes.ts
• apps/sim/executor/dag/construction/parallels.ts
• apps/sim/executor/dag/types.ts
• apps/sim/executor/execution/edge-manager.test.ts
• apps/sim/executor/execution/edge-manager.ts
• apps/sim/executor/execution/engine.test.ts
• apps/sim/executor/execution/engine.ts
• apps/sim/executor/execution/executor.ts
• apps/sim/executor/execution/state.ts
• apps/sim/executor/execution/types.ts
• apps/sim/executor/orchestrators/loop.ts
• apps/sim/executor/orchestrators/node.ts
• apps/sim/executor/orchestrators/parallel.ts
• apps/sim/executor/utils/parallel-expansion.ts
• apps/sim/executor/utils/subflow-utils.ts
• apps/sim/hooks/use-canvas-viewport.ts
• apps/sim/hooks/use-collaborative-workflow.ts
• apps/sim/hooks/use-execution-stream.ts
• apps/sim/lib/execution/preprocessing.ts
• apps/sim/lib/logs/execution/logging-factory.ts
• apps/sim/lib/logs/execution/logging-session.ts
• apps/sim/lib/webhooks/processor.ts
• apps/sim/lib/workflows/executor/execution-core.ts
• apps/sim/lib/workflows/executor/execution-events.ts
• apps/sim/lib/workflows/subblocks.ts
• apps/sim/stores/operation-queue/store.ts
• apps/sim/stores/workflows/utils.test.ts
• apps/sim/stores/workflows/utils.ts
• apps/sim/stores/workflows/workflow/store.test.ts
• apps/sim/stores/workflows/workflow/store.ts
• apps/sim/stores/workflows/workflow/types.ts
• apps/sim/stores/workflows/workflow/utils.test.ts
• apps/sim/stores/workflows/workflow/utils.ts

Overview

The Workflow System manages the complete lifecycle of AI-powered workflows from creation through execution. Workflows are directed acyclic graphs (DAGs) where nodes (blocks) represent operations and edges define execution dependencies.

This page covers the workflow lifecycle:

1. Creation & Editing: Visual canvas editing with workflow.tsx, real-time collaboration via useCollaborativeWorkflow, and state persistence through normalized tables
2. State Management: useWorkflowStore for graph structure, useSubBlockStore for user inputs, and useOperationQueue for collaborative sync
3. Serialization: Transform UI state into executable format via Serializer.serializeWorkflow()
4. Execution: DAG construction with DAGBuilder, orchestration by ExecutionEngine, and block-level handlers
5. Deployment: Immutable snapshots in workflowDeploymentVersion table with version control

Child Pages (detailed documentation):

• Workflows, Blocks & Edges: Block types, configuration, and connections
• Workflow Canvas & Editor: ReactFlow-based visual editor and interactions
• Collaborative Editing: Multi-user editing with WebSocket synchronization
• Workflow Execution Engine: DAG orchestration and execution flow
• Loop & Parallel Execution: Iterative and concurrent patterns
• Workflow Triggers: Manual, API, webhook, and scheduled invocation
• Serialization & State Persistence: State transformation and storage
• Deployment & Versioning: Immutable deployments and rollback
• Execution Logging & Cost Tracking: Logs, trace spans, and billing
• Preprocessing & Validation: Pre-execution checks and guards
• Background Jobs & Async Execution: Trigger.dev integration for long-running workflows

Sources: apps/sim/app/workspace/[workspaceId]/w/[workflowId]/workflow.tsx, apps/sim/stores/workflows/workflow/store.ts apps/sim/lib/workflows/executor/execution-core.ts apps/sim/executor/execution/engine.ts

Workflow Lifecycle

Workflows progress through five distinct phases, each with specific storage patterns and execution modes:

Phase	Storage	Execution Mode	Key APIs
Draft	workflowBlocks, workflowEdges, workflowSubflows tables	Uses current draft state	PUT /api/workflows/:id/state
Testing	Same normalized tables	Manual execution from editor	POST /api/workflows/:id/execute?useDraftState=true
Deployed	workflowDeploymentVersion.stateSnapshot (immutable)	Production triggers use snapshot	POST /api/workflows/:id/deploy
Executing	Execution logs to workflowExecutionLogs	Real-time via SSE or async via Trigger.dev	POST /api/workflows/:id/execute
Paused	Execution state in workflowPauseTokens	Resume from snapshot	POST /api/workflows/:id/execute with resumeFromSnapshot

Sources: apps/sim/app/api/workflows/[id]/execute/route.ts:178-536, apps/sim/app/workspace/[workspaceId]/w/[workflowId]/hooks/use-workflow-execution.ts:287-406, apps/sim/lib/workflows/executor/execution-core.ts114-320

Diagram: Complete Workflow Lifecycle

Sources: apps/sim/app/workspace/[workspaceId]/w/[workflowId]/workflow.tsx:1-2145, apps/sim/app/api/workflows/[id]/deploy/route.ts, apps/sim/background/webhook-execution.ts95-380

---

System Architecture

The workflow system spans three major components: the visual canvas, state management layer, and execution engine.

Diagram: Workflow System Architecture (Code Entity View)

Sources: apps/sim/app/workspace/[workspaceId]/w/[workflowId]/workflow.tsx:226-1042, apps/sim/stores/workflows/workflow/store.ts108-567 apps/sim/hooks/use-collaborative-workflow.ts33-858 apps/sim/stores/operation-queue/store.ts50-406 apps/sim/lib/workflows/executor/execution-core.ts114-320 apps/sim/executor/execution/engine.ts20-179

Creation & Editing

Workflow creation and editing occurs in the ReactFlow-based canvas with real-time collaborative features.

Canvas Component Structure

Component	File	Responsibility
WorkflowContent	workflow.tsx226	Main canvas, ReactFlow provider, node/edge management
WorkflowBlock	workflow-block.tsx658	Individual block rendering, SubBlockRow display
WorkflowEdge	workflow-edge.tsx	Edge rendering with conditional styling
SubflowNodeComponent	subflow-node.tsx	Loop/parallel container rendering

Sources: apps/sim/app/workspace/[workspaceId]/w/[workflowId]/workflow.tsx:226-1042, apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/workflow-block/workflow-block.tsx:658-1084

State Mutation Operations

The useWorkflowStore provides atomic operations for graph manipulation:

Sources: apps/sim/stores/workflows/workflow/store.ts117-551

Collaborative Editing Flow

Multi-user editing synchronizes through a queue-based operation system:

Diagram: Collaborative Editing Synchronization

Sources: apps/sim/hooks/use-collaborative-workflow.ts660-717 apps/sim/stores/operation-queue/store.ts55-154

Operation Queue Mechanics

The operation queue ensures FIFO ordering and handles network failures:

Retry policies:

• Subblock/variable updates: 5 retries, linear backoff (1s, 2s, 3s), max 3s delay
• Structural operations: 3 retries, exponential backoff (2^n * 1000ms)
• Timeout: 15s for subblock/variable, 5s for structural

Sources: apps/sim/stores/operation-queue/store.ts7-257

---

Workflow Structure

A workflow is a directed acyclic graph (DAG) composed of four structural elements that define the execution topology:

Core Graph Elements

Element	Purpose	TypeScript Type
Blocks	Individual operations (nodes in the graph)	BlockState
Edges	Directed connections defining execution order	Edge
Loops	Containers for iterative execution of child blocks	Loop
Parallels	Containers for concurrent execution of child blocks	Parallel

Sources: apps/sim/stores/workflows/workflow/types.ts73-142

Diagram: Workflow Graph Structure

Sources: apps/sim/stores/workflows/workflow/types.ts apps/sim/executor/dag/builder.ts

BlockState Type

Blocks are the fundamental execution units:

For detailed block configuration including subblocks and outputs, see Workflows & Blocks.

Sources: apps/sim/stores/workflows/workflow/types.ts73-87

Edge Type

Edges define execution flow and handle-to-handle connections:

The sourceHandle determines conditional routing:

• source/success: Normal execution path
• error: Error handling path
• condition: Conditional branching (condition block)

Sources: apps/sim/executor/constants.ts181-194 apps/sim/executor/execution/edge-manager.ts14-48

Loop and Parallel Types

Containers group child blocks for special execution patterns. See Loop & Parallel Execution for detailed semantics.

Sources: apps/sim/stores/workflows/workflow/types.ts125-142

---

Block Types and Categories

Sim includes 150+ block types organized into three categories:

Block Categories

Category	Purpose	Count	Example Blocks
blocks	Core workflow operations	~20	agent, function, api, condition, router, evaluator
tools	External service integrations	~130	slack, github, gmail, notion, airtable, hubspot
triggers	Workflow invocation entry points	~10	start_trigger, webhook, schedule, rss, email_polling

Sources: apps/sim/blocks/types.ts15 apps/sim/blocks/registry.ts

Common Block Types

Core Execution Blocks

Block Type	Purpose	Handler
agent	LLM-based AI agent with tool calling	AgentHandler
function	JavaScript/Python code execution	FunctionHandler
api	HTTP API requests	ApiHandler
condition	Conditional branching	ConditionHandler
router	Multi-branch routing with descriptions	RouterHandler

Sources: apps/sim/executor/constants.ts3-30 apps/sim/executor/handlers/

Control Flow Blocks

Block Type	Purpose	Orchestrator
loop	Iterative execution (for, forEach, while, doWhile)	LoopOrchestrator
parallel	Concurrent execution of branches	ParallelOrchestrator
workflow	Invoke another workflow	WorkflowBlockHandler

Sources: apps/sim/executor/orchestrators/loop.ts apps/sim/executor/orchestrators/parallel.ts apps/sim/executor/handlers/workflow/workflow-handler.ts

Trigger Blocks

Block Type	Purpose	See
start_trigger	Manual execution entry point	Workflow Triggers
webhook	HTTP webhook endpoint	Workflow Triggers
schedule	Cron-based scheduled execution	Workflow Triggers

Sources: apps/sim/lib/workflows/triggers/triggers.ts

BlockConfig Schema

Each block type is defined by a BlockConfig object that specifies its UI, inputs, outputs, and execution behavior. See Workflows & Blocks for the complete schema.

Sources: apps/sim/blocks/types.ts312-345

---

DAG-Based Execution Model

The workflow execution engine transforms the visual graph into an executable DAG and orchestrates block execution based on dependencies.

Execution Pipeline

Diagram: Workflow Execution Pipeline

Sources: apps/sim/serializer/index.ts apps/sim/executor/dag/builder.ts apps/sim/executor/execution/engine.ts apps/sim/executor/execution/executor.ts

Serialization & Execution Preparation

Before execution, the UI graph undergoes transformation into an executable format.

Serializer Transformation

The Serializer class converts BlockState objects into SerializedBlock format:

Key transformations:

1. subBlocks → inputs: User-entered values become execution inputs
2. type → config.tool: Block type maps to handler registry
3. data.parentId → Container relationships preserved for loop/parallel orchestration
4. Reference resolution: <blockName.field> expressions validated and mapped

Sources: apps/sim/serializer/index.ts37-218 apps/sim/stores/workflows/workflow/types.ts76-90

Workflow State Loading

Two loading paths exist based on execution context:

Sources: apps/sim/lib/workflows/persistence/utils.ts apps/sim/lib/workflows/executor/execution-core.ts160-183

DAG Construction Phase

The DAGBuilder constructs the directed acyclic graph:

The DAG includes:

• Nodes: Each DAGNode has incoming and outgoing edges
• Dependency tracking: Nodes track which predecessors must complete first
• Cycle detection: Validates that no cycles exist

Sources: apps/sim/executor/dag/builder.ts51-190

Diagram: DAG Node Structure

Sources: apps/sim/executor/dag/types.ts apps/sim/executor/dag/builder.ts

Execution Orchestration

The ExecutionEngine implements a queue-based traversal of the DAG with dependency tracking.

Execution Engine Architecture

Sources: apps/sim/executor/execution/engine.ts20-179

Queue Processing Loop

Diagram: Execution Engine Queue Processing

Sources: apps/sim/executor/execution/engine.ts103-247

Edge Activation Logic

The EdgeManager determines which downstream nodes become ready:

Sources: apps/sim/executor/execution/edge-manager.ts9-160

Parallel Execution Strategy

Independent nodes execute concurrently:

Concurrency benefits:

• Independent branches execute simultaneously
• Reduces total workflow duration
• Natural parallelism in DAG topology

Sources: apps/sim/executor/execution/engine.ts249-343

Block Handler Registry

Block execution is delegated to type-specific handlers:

Handler	Block Types	File	Key Logic
AgentHandler	agent, router, evaluator	agent-handler.ts	LLM orchestration, tool calling, max 20 iterations
FunctionHandler	function	function-handler.ts	JavaScript/Python sandbox execution via isolated-vm
ApiHandler	api	api-handler.ts	HTTP requests with retry logic
ConditionHandler	condition	condition-handler.ts	JavaScript expression evaluation for branching
LoopOrchestrator	loop	loop.ts	Iterative execution: for, forEach, while, doWhile
ParallelOrchestrator	parallel	parallel.ts	Concurrent branch execution

Handler selection:

Sources: apps/sim/executor/orchestrators/node.ts1-234 apps/sim/executor/handlers/

For detailed execution mechanics, see Workflow Execution Engine.

---

Execution Lifecycle

A workflow progresses through distinct phases from creation to production execution:

Diagram: Workflow Lifecycle States

Sources: apps/sim/app/workspace/[workspaceId]/w/[workflowId]/workflow.tsx, apps/sim/app/api/workflows/[id]/deploy/route.ts

State Persistence

Workflow state persists across sessions using a normalized database schema.

Normalized Table Schema

Table	Purpose	Key Columns
workflows	Workflow metadata	id, name, userId, workspaceId, isDeployed
workflowBlocks	Block definitions	id, workflowId, type, name, position, subBlocks, outputs
workflowEdges	Edge connections	id, workflowId, source, target, sourceHandle, targetHandle
workflowSubflows	Loop/parallel configs	id, workflowId, type, config (JSONB: loopType, iterations, etc.)

Persistence flow:

1. User edits trigger collaborativeBatchAddBlocks() → useOperationQueue
2. Queue emits Socket.IO event with operationId
3. Server processes event → PUT /api/workflows/:id/state
4. Upserts to normalized tables
5. Server confirms → emit('operation-confirmed', {operationId})
6. Client removes from queue

Sources: apps/sim/app/api/workflows/[id]/state/route.ts, apps/sim/stores/operation-queue/store.ts274-339

SubBlock Value Storage

User-entered values are stored separately from block structure:

Merge pattern for execution:

Sources: apps/sim/stores/workflows/subblock/store.ts apps/sim/lib/workflows/subblocks.ts

Testing & Manual Execution

Manual execution from the editor uses draft state and streams results in real-time.

Execution Request Flow

Diagram: Manual Execution Request Path

Sources: apps/sim/app/workspace/[workspaceId]/w/[workflowId]/hooks/use-workflow-execution.ts:287-654, apps/sim/app/api/workflows/[id]/execute/route.ts:178-697, apps/sim/lib/workflows/executor/execution-core.ts114-403

Server-Sent Events (SSE) Format

Real-time execution updates stream to the client:

Client handling:

Sources: apps/sim/lib/workflows/executor/execution-events.ts apps/sim/app/api/workflows/[id]/execute/route.ts:541-697

Deployment & Production Execution

Production workflows execute from immutable snapshots stored in the workflowDeploymentVersion table.

Deployment Snapshot Creation

Snapshot deduplication benefits:

• Storage efficiency for workflows with few changes
• Atomic rollback to previous versions
• Version history preserved even for identical states

Sources: apps/sim/app/api/workflows/[id]/deploy/route.ts, apps/sim/lib/workflows/persistence/utils.ts

Trigger Activation

Deployment activates configured triggers:

Trigger Type	Activation	Invocation Path
Webhook	Create/update record in webhook table with path	POST /api/webhooks/trigger/:path → Trigger.dev → webhook-execution task
Schedule	Create/update record in workflowSchedule table	Cron job polls table → Trigger.dev → schedule-execution task
API	Deployment marks workflow as isDeployed=true	Direct API call → POST /api/workflows/:id/execute

Background execution via Trigger.dev:

Sources: apps/sim/background/webhook-execution.ts95-380 apps/sim/background/schedule-execution.ts apps/sim/app/api/webhooks/trigger/[path]/route.ts:37-176

---

API Reference

Core endpoints for workflow lifecycle management:

Endpoint	Method	Purpose	Key Parameters
POST /api/workflows	POST	Create new workflow	name, workspaceId
GET /api/workflows/:id	GET	Load workflow metadata and state from normalized tables	-
PUT /api/workflows/:id/state	PUT	Save draft state (upserts to workflowBlocks, workflowEdges, workflowSubflows)	blocks, edges, loops, parallels
POST /api/workflows/:id/execute	POST	Execute workflow	useDraftState, input, stream, triggerType
POST /api/workflows/:id/deploy	POST	Create immutable deployment snapshot	-
GET /api/workflows/:id/deployments	GET	List deployment versions	-
POST /api/workflows/:id/revert	POST	Revert to previous deployment	deploymentVersionId
DELETE /api/workflows/:id	DELETE	Delete workflow and cleanup triggers	-

Execution modes:

Sources: apps/sim/app/api/workflows/[id]/route.ts, apps/sim/app/api/workflows/[id]/state/route.ts, apps/sim/app/api/workflows/[id]/execute/route.ts:178-536, apps/sim/app/api/workflows/[id]/deploy/route.ts

---

Summary

The Core Workflow System provides:

• Structural Model: Blocks, edges, loops, and parallels defining workflow topology
• State Persistence: Normalized database schema with atomic save/load operations
• Nested Workflows: Recursive execution with depth limits and input mapping
• Resource Sync: Automatic webhook and schedule configuration management
• Import/Export: JSON and YAML portability with validation
• Frontend Integration: React hooks for execution and state management

This foundation enables all higher-level workflow operations including execution, debugging, deployment, and collaboration.