This document describes the Zustand-based state management architecture used throughout Sim Studio. The system employs a multi-store pattern with specialized stores for different concerns: workflow metadata and navigation (WorkflowRegistry), workflow structure (WorkflowStore), runtime values (SubBlockStore), and collaborative operations (OperationQueue).
For information about real-time synchronization between clients, see Real-time Collaboration System. For database persistence patterns, see Database Schema.
The state management layer is divided into specialized stores, each with distinct responsibilities and update patterns. This separation enables fine-grained subscriptions, reduces unnecessary re-renders, and supports the real-time collaboration model.
Title: Multi-Store Data Flow
Sources: apps/sim/stores/workflows/registry/store.ts70-230 apps/sim/stores/workflows/workflow/store.ts114-542 apps/sim/stores/operation-queue/store.ts84-450 apps/sim/app/workspace/[workspaceId]/w/[workflowId]/workflow.tsx:79-90, apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/workflow-block/workflow-block.tsx:51-53, apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/editor/editor.tsx:52-55
The WorkflowRegistry store manages workspace-level workflow metadata and navigation state. It maintains the list of workflows in the current workspace, tracks the active workflow, handles clipboard operations, and orchestrates the workflow loading lifecycle.
The registry tracks metadata and hydration status apps/sim/stores/workflows/registry/types.ts9-14
Sources: apps/sim/stores/workflows/registry/store.ts70-80
The hydration field tracks the workflow loading lifecycle through phases defined in HydrationState apps/sim/stores/workflows/registry/store.ts21-27
Title: Workflow Hydration Lifecycle
Sources: apps/sim/stores/workflows/registry/store.ts81-134 apps/sim/stores/workflows/registry/store.ts21-27
The WorkflowStore manages the structural graph of the active workflow: blocks, edges, loop containers, and parallel containers. It provides batch operations for collaborative editing and maintains referential stability for React rendering.
The store holds the normalized graph structure apps/sim/stores/workflows/workflow/types.ts23-26
Sources: apps/sim/stores/workflows/workflow/store.ts104-112 apps/sim/stores/workflows/workflow/types.ts23-26
The primary method for adding blocks supports edges, subblock values, and parent-child relationships apps/sim/stores/workflows/workflow/store.ts204-310 It utilizes prepareBlockState to initialize default sub-blocks and outputs from the block registry apps/sim/stores/workflows/utils.ts113-204
Moving blocks into/out of containers (like loops or parallel blocks) requires updating parentId and extent via batchUpdateBlocksWithParent apps/sim/stores/workflows/workflow/store.ts154-186
The store validates all edges to prevent cycles using wouldCreateCycle apps/sim/stores/workflows/workflow/utils.ts32 Edge validation is performed during batchAddEdges apps/sim/stores/workflows/workflow/store.ts432-462 using the validateEdges utility apps/sim/stores/workflows/utils.ts12
The SubBlockStore maintains runtime values for block parameters (sub-blocks) separate from the structural WorkflowStore. This separation allows the UI to update inputs without triggering a full graph re-render.
Initial values for sub-blocks are resolved based on configuration using resolveInitialSubblockValue apps/sim/stores/workflows/workflow/store.ts68-102 This function handles cloning default values and generating initial IDs for complex types like input-format apps/sim/stores/workflows/workflow/store.ts85-95
Dynamic handle sub-blocks (like condition rows) are synced via syncDynamicHandleSubblockValue apps/sim/stores/workflows/workflow/store.ts494-515 The store manages workflowValues indexed by workflowId and blockId apps/sim/stores/workflows/subblock/store.ts49-50
The OperationQueue store manages optimistic updates for collaborative editing. It queues operations, tracks their lifecycle, handles retries, and triggers failure states when the server becomes unavailable.
When a user modifies the workflow, the system performs a local update and queues a network operation apps/sim/stores/operation-queue/store.ts89-189
Title: Optimistic Update and Sync
Sources: apps/sim/stores/operation-queue/store.ts89-189 apps/sim/hooks/use-collaborative-workflow.ts114-158 apps/sim/stores/operation-queue/store.ts191-216
Operations have specific timeouts and retry limits based on their type apps/sim/stores/operation-queue/store.ts18-28
SUBBLOCK_VARIABLE_TIMEOUT_MS), 5 retries.STRUCTURAL_TIMEOUT_MS), 3 retries.If retries are exhausted, failOperation is called to handle the error state apps/sim/stores/operation-queue/store.ts218-306
The useCollaborativeWorkflow hook bridges the store layer and WebSocket layer. It listens for remote operations and applies them to local stores while avoiding infinite loops using isApplyingRemoteChange apps/sim/hooks/use-collaborative-workflow.ts140-178
The hook maps incoming socket events to store actions apps/sim/hooks/use-collaborative-workflow.ts181-450:
Target (OPERATION_TARGETS) | Operation (BLOCK_OPERATIONS) | Store Action |
|---|---|---|
BLOCK | UPDATE_NAME | updateBlockName |
BLOCKS | BATCH_ADD_BLOCKS | batchAddBlocks |
EDGES | BATCH_ADD_EDGES | batchAddEdges |
SUBBLOCK | subblock-update | updateSubblockValue |
VARIABLE | variable-update | updateVariable |
Sources: apps/sim/hooks/use-collaborative-workflow.ts181-450 apps/sim/socket/constants.ts11-19
When switching workspaces via switchToWorkspace, the registry calls resetWorkflowStores() to clear all workflow and subblock data to prevent data leakage apps/sim/stores/workflows/registry/store.ts36-51
The registry uses isWorkspaceTransitioning and a TRANSITION_TIMEOUT (5 seconds) to ensure only one workspace switch happens at a time apps/sim/stores/workflows/registry/store.ts31-68
Sources: apps/sim/stores/workflows/registry/store.ts31-68 apps/sim/stores/workflows/registry/store.ts136-181
Refresh this wiki