The Workflow Registry Store is a centralized Zustand store that manages workflow metadata and orchestrates workflow state hydration across workspace and workflow transitions. It maintains the registry of all workflows in the current workspace, tracks the active workflow, and coordinates with WorkflowStore and SubBlockStore to load and persist workflow state.
Scope: This document covers the registry store's architecture, hydration state machine, workspace switching, and clipboard operations. For actual workflow state management (blocks, edges, loops), see Workflow Fundamentals. For UI components that consume this store, see Workspace Navigation & Sidebar.
The registry acts as the "source of truth" for workflow metadata while delegating actual workflow state (blocks, edges) to separate stores. This separation enables efficient workspace switching and prevents data leakage between workspaces.
Title: Workflow Registry Architecture
Sources: apps/sim/stores/workflows/registry/store.ts70-72 apps/sim/stores/workflows/registry/types.ts94 apps/sim/stores/index.ts189-198
The registry store maintains the following state:
| Field | Type | Description |
|---|---|---|
workflows | Record<string, WorkflowMetadata> | Map of workflow IDs to metadata (name, color, workspaceId, etc.) |
activeWorkflowId | string | null | Currently active workflow ID |
error | string | null | Error message if hydration fails |
deploymentStatuses | Record<string, DeploymentStatus> | Deployment state per workflow |
hydration | HydrationState | Current hydration phase and context |
clipboard | ClipboardData | null | Copied blocks for paste operations |
pendingSelection | string[] | null | Block IDs to select after paste |
Sources: apps/sim/stores/workflows/registry/types.ts20-33 apps/sim/stores/workflows/registry/store.ts73-80
The registry uses a state machine to track workflow loading progress and prevent race conditions during workspace/workflow transitions.
Title: Hydration State Machine
| Phase | Description | workspaceId | workflowId | requestId |
|---|---|---|---|---|
idle | Initial state, no workspace loaded | null | null | null |
metadata-loading | Fetching workflow list for workspace | Set | null | null |
metadata-ready | Workflow list loaded, ready for workflow selection | Set | null | null |
state-loading | Fetching specific workflow state | Set | Set | Set |
ready | Workflow fully loaded and active | Set | Set | Set |
error | Hydration failed | Set | Previous | null |
Request ID Tracking: The state-loading phase generates a unique requestId via createRequestId() apps/sim/stores/workflows/registry/store.ts29 to discard stale API responses if the user switches workflows mid-load apps/sim/stores/workflows/registry/store.ts323-333
Sources: apps/sim/stores/workflows/registry/types.ts35-49 apps/sim/stores/workflows/registry/store.ts21-27 apps/sim/stores/workflows/registry/store.ts81-121
The switchToWorkspace() function performs a complete reset to prevent data leakage between workspaces:
Title: Workspace Switch Sequence
Race Condition Prevention: A module-level isWorkspaceTransitioning flag prevents concurrent workspace switches. A 5-second TRANSITION_TIMEOUT forces completion if the transition hangs apps/sim/stores/workflows/registry/store.ts32-33
Sources: apps/sim/stores/workflows/registry/store.ts36-51 apps/sim/stores/workflows/registry/store.ts57-68 apps/sim/stores/workflows/registry/store.ts136-181
The loadWorkflowState() function fetches workflow data from the API and hydrates all related stores:
Title: Workflow Hydration Sequence
Stale Request Handling: The requestId check at apps/sim/stores/workflows/registry/store.ts323-333 ensures that only the most recent load request updates the stores.
Sources: apps/sim/stores/workflows/registry/store.ts252-387 apps/sim/stores/workflows/registry/store.ts389-411
| Operation | Method | Key Actions |
|---|---|---|
| Update | updateWorkflow(id, metadata) | Optimistic update of local metadata map before API call apps/sim/stores/workflows/registry/store.ts658-716 |
| Remove | removeWorkflow(id) | Optimistic removal from map; resets active workflow if deleted apps/sim/stores/workflows/registry/store.ts559-648 |
| Duplicate | duplicateWorkflow(sourceId) | API call followed by metadata insertion and subblock value cloning apps/sim/stores/workflows/registry/store.ts416-557 |
| Redeploy | setWorkflowNeedsRedeployment(id, needs) | Marks a workflow as needing a fresh deployment after edits apps/sim/stores/workflows/registry/store.ts225-250 |
Sources: apps/sim/stores/workflows/registry/store.ts416-717 apps/sim/stores/workflows/registry/types.ts61-92
The registry provides cross-workflow copy/paste functionality for blocks, edges, loops, and parallels.
Title: Clipboard Copy/Paste Flow
Auto-Include Subflows: When copying a loop or parallel block, all nested blocks are automatically included via getDescendantBlockIds apps/sim/stores/workflows/registry/store.ts747-753
ID Regeneration: The regenerateBlockIds() utility generates new UUIDs and updates all references to ensure pasted blocks don't conflict with existing ones apps/sim/stores/workflows/registry/store.ts806-817
Sources: apps/sim/stores/workflows/registry/store.ts736-818 apps/sim/stores/workflows/registry/types.ts11-18
The registry coordinates with three other Zustand stores to manage complete workflow state:
Title: Store Inter-dependencies
The resetAllStores() helper is used during logout or major state transitions to purge all user data:
| Store | Reset Action |
|---|---|
useWorkflowRegistry | Reset to initialHydration and empty maps apps/sim/stores/index.ts203-215 |
useWorkflowStore | clear() structure apps/sim/stores/index.ts216 |
useSubBlockStore | clear() block values apps/sim/stores/index.ts217 |
useTerminalConsoleStore | Reset entry maps and location tracking apps/sim/stores/index.ts220-225 |
Sources: apps/sim/stores/index.ts201-229 apps/sim/stores/workflows/registry/store.ts36-51
The Sidebar initiates metadata loading for the current workspace on mount:
Sources: apps/sim/app/workspace/[workspaceId]/w/components/sidebar/sidebar.tsx:99, apps/sim/stores/workflows/registry/store.ts81-121
The main workflows page redirects to the first available workflow if no active ID is set:
Sources: apps/sim/app/workspace/[workspaceId]/w/page.tsx:15-55, apps/sim/stores/workflows/registry/store.ts389-411
Refresh this wiki