Visual Workflow Editor
Relevant source files
The following files were used as context for generating this wiki page:
- frontend/src/features/workflows/components/WorkflowFlowEditor.tsx
- frontend/src/features/workflows/components/BlockLibraryDialog.tsx
- frontend/src/features/workflows/hooks/useFlowEditorState.ts
- frontend/src/features/workflows/containers/WorkflowEditorPageContainer.tsx
- frontend/src/features/workflows/hooks/useWorkflowsPage.ts
- convex/schema.ts
- frontend/src/features/workflows/utils/workflowImportExport.ts
The Visual Workflow Editor is a core component of the bot-auto-ig platform, providing a node-based interface for designing automation sequences. It allows users to visually construct complex logic by connecting different "Activity" blocks to a "Start" node, defining the execution path for Instagram automation tasks.
The editor is built on top of reactflow and integrates deeply with the Convex backend to persist workflow definitions, which consist of nodes (positions and configurations) and edges (logical connections).
Sources: frontend/src/features/workflows/components/WorkflowFlowEditor.tsx:1-40, convex/schema.ts:80-85
System Architecture
The workflow editor follows a provider-pattern architecture to manage state and canvas interactions. The WorkflowEditorProvider wraps the canvas, settings panels, and dialogs to provide a shared context for node operations.
Component Hierarchy
The diagram shows the component hierarchy from the route container down to the individual node types.
Sources: frontend/src/features/workflows/components/WorkflowFlowEditor.tsx:43-100, frontend/src/features/workflows/containers/WorkflowEditorPageContainer.tsx:64-97
State Management and Hooks
The editor's logic is encapsulated in the useFlowEditorState hook, which manages the lifecycle of nodes and edges, viewport persistence, and user interactions.
Key Hook Modules
| Hook Function | Responsibility |
|---|---|
useFlowEditorState | Main orchestrator for the editor UI state and canvas operations. |
useNodeInsertion | Logic for calculating positions and adding new activity blocks to the graph. |
useNodeDeletion | Handles node removal with a 5-second undo toast mechanism. |
useViewportPersistence | Saves and restores the user's zoom/pan position using localStorage. |
useInitialGraphData | Normalizes raw database workflow data into ReactFlow-compatible objects. |
Sources: frontend/src/features/workflows/hooks/useFlowEditorState.ts:60-310
Viewport Persistence
The editor saves the viewport state (x, y coordinates and zoom level) to localStorage keyed by the workflow ID. This ensures that users return to the same visual context when reopening a specific workflow.
Sources: frontend/src/features/workflows/hooks/useFlowEditorState.ts:16-40
Workflow Data Model
Workflows are stored in the workflows table in Convex. The data structure is designed to be flexible, using v.any() for nodes and edges to accommodate the complex objects generated by the frontend.
Schema Definition
| Field | Type | Description |
|---|---|---|
name | string | The display name of the workflow. |
nodes | any | Array of ReactFlow nodes (positions, types, and activity configs). |
edges | any | Array of ReactFlow edges defining connections. |
status | union | Current execution state (idle, pending, running, etc.). |
nodeStates | any | Map of nodeId to its individual execution state/progress. |
Sources: convex/schema.ts:80-120
Interaction Flows
Adding an Activity Block
When a user adds a block (either via the Start node's plus button or the global toolbar), the system determines the insertion position based on the context.
This flow illustrates the logic for placing new nodes relative to the current view or existing nodes.
Sources: frontend/src/features/workflows/hooks/useFlowEditorState.ts:74-110, frontend/src/features/workflows/components/BlockLibraryDialog.tsx
Import/Export Mechanism
The editor supports a custom .workflow.json format for portability. The system enforces strict validation during import to ensure graph integrity.
// Example of the export envelope structure
export interface WorkflowImportEnvelope {
format: 'bot-auto-ig.workflow',
version: '1.0',
exportedAt: string,
workflow: {
name: string,
description?: string,
nodes: Record<string, unknown>[],
edges: Record<string, unknown>[]
}
}
Sources: frontend/src/features/workflows/utils/workflowImportExport.ts:10-25
Validation Rules for Import:
- File Size: Maximum 2MB.
- Start Node: Must contain exactly one node of type
startor IDstart_node. - Activity IDs: Every activity ID in the JSON must be recognized by the current version of the software.
- Deduplication: If a workflow with the same name exists, the imported one is renamed with a timestamp suffix (e.g., "My Workflow (imported 2024-05-20 10:00)").
Sources: frontend/src/features/workflows/utils/workflowImportExport.ts:80-150, frontend/src/features/workflows/utils/workflowImportExport.ts:258-280
Implementation Details
Node Deletion Logic
The system uses a "soft-delete" UI pattern. When a node is deleted, it is removed from the state immediately, but a toast notification provides a "Undo" button that restores the node and all its previously associated edges.
Sources: frontend/src/features/workflows/hooks/useFlowEditorState.ts:133-165
Save Operation
The WorkflowEditorPageContainer handles the save operation by calling the Convex update mutation. It transforms the local ReactFlow state back into the database format.
Sources: frontend/src/features/workflows/containers/WorkflowEditorPageContainer.tsx:73-90
Conclusion
The Visual Workflow Editor provides a robust, stateful environment for defining automation logic. By combining reactflow for the UI and Convex for reactive data persistence, it enables complex graph management with features like viewport persistence, automated re-naming on import, and transient deletion recovery.