Workflow Editor & Visualizer

Relevant source files

The following files were used as context for generating this wiki page:

• apps/web/src/features/react-flow-visualization/store/app-store.ts
• apps/web/src/app/(protected)/(editor)/edit/components/EditModeSelector.tsx
• apps/web/src/app/(protected)/(editor)/edit/components/JSONEditor.tsx
• apps/web/src/features/react-flow-visualization/components/nodes/nodes.tsx
• apps/web/src/lib/workflows.ts
• packages/core/src/workflow/schema/workflow.types.ts
• apps/web/src/app/(protected)/(editor)/edit/[wf_version_id]/components/WorkflowEditor.tsx
• packages/core/src/workflow/actions/generate/formalizeWorkflow.ts

The Workflow Editor & Visualizer is a comprehensive web-based interface for designing, managing, and evaluating agentic workflows. It provides a dual-paradigm editing experience, allowing users to interact with workflows through a graphical, node-based canvas or a raw JSON editor. The system is built using React, with React Flow for the graph visualization and Zustand for robust state management.

This editor is the primary tool for creating and modifying the WorkflowConfig JSON structures that define the behavior of the autonomous workflow system. It supports loading existing workflow versions, creating new ones, and evaluating their performance. The editor seamlessly synchronizes state between its different views and persists changes to the backend via a set of dedicated API endpoints.

Architecture

The editor's architecture is centered around a Zustand-powered store (app-store.ts) that acts as a single source of truth for the workflow state. A top-level component, EditModeSelector, orchestrates which editor view—graph, json, or eval—is presented to the user and manages the data synchronization between them.

Sources: apps/web/src/app/(protected)/(editor)/edit/components/EditModeSelector.tsx, apps/web/src/features/react-flow-visualization/store/app-store.ts

Component and Data Flow

The following diagram illustrates the high-level architecture and data flow between the main components of the editor.

Sources: apps/web/src/app/(protected)/(editor)/edit/components/EditModeSelector.tsx:188-204, apps/web/src/features/react-flow-visualization/store/app-store.ts:438-466, 731-760

State Management

State is managed by a Zustand store defined in app-store.ts. This store holds the nodes, edges, workflow JSON, and UI state. It uses persist middleware to save a subset of the state to localStorage, enabling draft recovery and session persistence.

Sources: apps/web/src/features/react-flow-visualization/store/app-store.ts

AppState

The core state of the application is defined by the AppState type.

Property	Type	Description
nodes	AppNode[]	An array of nodes for the React Flow canvas.
edges	AppEdge[]	An array of edges connecting the nodes.
workflowJSON	string	The stringified JSON representation of the workflow.
currentWorkflowId	string	The ID of the workflow version currently being edited.
selectedNodeId	string	The ID of the currently selected node for the details panel.
workflowValidationErrors	WorkflowValidationError[]	A list of validation errors for the current workflow.
_hasHydrated	boolean	A flag indicating if the state has been rehydrated from localStorage.

Sources: apps/web/src/features/react-flow-visualization/store/app-store.ts:41-71

Key Actions

The AppActions type defines functions to manipulate the state. These actions encapsulate the core logic for loading, saving, and modifying workflows.

Action	Description
loadWorkflowFromData	Loads a WorkflowConfig object into the store, creating the necessary nodes and edges for the graph.
exportToJSON	Converts the current graph state (nodes and edges) into a WorkflowConfig JSON string.
syncJSONToGraph	Parses the workflowJSON string and updates the graph state to match it.
updateNode	Updates the data of a specific node and can handle renaming by updating all relevant edges.
organizeLayout	Triggers an automatic layout algorithm (layoutGraph) to arrange nodes on the canvas.
addValidationError	Adds a validation error to the state, which is then displayed in the UI.

Sources: apps/web/src/features/react-flow-visualization/store/app-store.ts:100-143

Editor Modes

The editor operates in one of three modes, controlled by the EditModeSelector component. The mode is stored as a URL query parameter (?mode=...).

Sources: apps/web/src/app/(protected)/(editor)/edit/components/EditModeSelector.tsx:145-161

Mode Switching Logic

When switching modes, the editor ensures data consistency between the views. For example, when moving from the graph to the JSON editor, the graph state is first exported to JSON.

Sources: apps/web/src/app/(protected)/(editor)/edit/components/EditModeSelector.tsx:206-226

1. Graph Mode

This is the default visual editing mode, powered by React Flow. It provides a canvas where users can drag, drop, and connect nodes to build a workflow's Directed Acyclic Graph (DAG).

Custom Nodes

The editor uses several custom node types defined in nodes.tsx. Each node type has a specific visual representation and behavior.

Node Type	Purpose
initial-node	The entry point of the workflow.
output-node	The terminal point of the workflow.
transform-node	A standard agent node that processes information.
branch-node	A node type that can have multiple output handles (not explicitly defined but supported by handle logic).
join-node	A node type that can have multiple input handles.

Sources: apps/web/src/features/react-flow-visualization/components/nodes/nodes.tsx:16-23

Node creation is handled by the addNodeByType action, which uses a predefined list of city names to generate unique, human-readable IDs for new nodes.

Sources: apps/web/src/features/react-flow-visualization/store/app-store.ts:208-238

2. JSON Mode

This mode provides a raw text editor (JSONEditor.tsx) for directly manipulating the WorkflowConfig JSON. It offers advanced features for power users:

• Real-time Validation: The JSON is parsed as the user types to provide immediate feedback on syntax errors.
• AI-Powered Optimization: Users can provide natural language feedback to have an AI agent refactor the workflow. This is powered by the /api/workflow/formalize endpoint.
• Backend Verification: A "Verify" button sends the current JSON to the /api/workflow/verify endpoint to check for structural and logical integrity against the core engine's rules.

Sources: apps/web/src/app/(protected)/(editor)/edit/components/JSONEditor.tsx:112-135, 172-205

AI-Powered Optimization Flow

Sources: apps/web/src/app/(protected)/(editor)/edit/components/JSONEditor.tsx:185-205, packages/core/src/workflow/actions/generate/formalizeWorkflow.ts:20-27

3. Eval Mode

The "eval" mode provides an interface for batch-testing a workflow against a dataset of inputs and expected outputs. It allows users to define a goal, load a dataset, and run the workflow against each test case to measure performance and accuracy.

Sources: apps/web/src/app/(protected)/(editor)/edit/components/EditModeSelector.tsx:403-495

Data Persistence

Workflows are persisted to a Supabase database. The editor interacts with the database through a set of API endpoints.

Workflow Configuration (WorkflowConfig)

The central data structure is WorkflowConfig. When saving, the editor's graph state is converted into this format. A key feature is the ui.layout object, which stores the x/y positions of each node, allowing the visual layout to be preserved.

// Simplified from packages/core/src/workflow/schema/workflow.types.ts
export interface WorkflowConfig {
  nodes: WorkflowNodeConfig[];
  entryNodeId: string;
  ui?: {
    layout?: {
      nodes: {
        nodeId: string;
        x: number;
        y: number;
      }[];
    };
  };
  // ... other properties
}

Sources: apps/web/src/features/react-flow-visualization/store/app-store.ts:634-641

The exportToJSON function in app-store.ts is responsible for this conversion, iterating through the graph nodes and capturing their positions.

Sources: apps/web/src/features/react-flow-visualization/store/app-store.ts:611-655

Saving a Workflow

Saving a workflow is an asynchronous process that involves converting the graph to JSON, validating it, and sending it to the backend.

Sources: apps/web/src/app/(protected)/(editor)/edit/components/EditModeSelector.tsx:228-245, apps/web/src/lib/workflows.ts:153-172, apps/web/src/features/react-flow-visualization/store/app-store.ts:842-875

Summary

The Workflow Editor & Visualizer is a powerful and flexible tool at the core of the lucky project's user experience. By offering both high-level graphical abstraction and low-level JSON control, it caters to a wide range of users. Its robust state management and tight integration with backend services for persistence, validation, and AI-assisted optimization make it a critical component for designing and evolving complex, multi-agent systems.