Claude-Code-Workflow/docs/features/orchestrator.md

Orchestrator

One-Liner

The Orchestrator is a visual workflow template editor with React Flow, featuring drag-drop node palette, property panel, and template library for designing automation flows.

---

Pain Points Solved

Pain Point	Current State	Orchestrator Solution
No visual workflow design	Manual configuration file editing	Drag-and-drop canvas interface
Hard to understand flows	Text-based configuration	Visual node graphs with connections
No template reuse	Recreate flows from scratch	Template library for quick start
Complex node configuration	Remember all options	Contextual property panel
Accidental edits during execution	Can modify while running	Canvas lock during execution

---

Page Overview

Location: ccw/frontend/src/pages/orchestrator/OrchestratorPage.tsx

Purpose: Visual workflow template editor for creating, editing, and managing automation flows.

Access: Navigation → Orchestrator

Layout

+--------------------------------------------------------------------------+
|  Flow Toolbar (save, load, template library, execution controls)             |
+--------------------------------------------------------------------------+
|  +-------+------------------------------------------------------+-------+  |
|  | Node  |  Flow Canvas (React Flow)                     | Prop  |  |
|  | Palet |  +----+    +----+    +----+                     | Panel |  |
|  | (coll)|  | N1 | -->| N2 | -->| N3 |                     | (cond)|  |
|  |       |  +----+    +----+    +----+                     |       |  |
|  |       |                                                |       |  |
|  +-------+------------------------------------------------------+-------+  |
+--------------------------------------------------------------------------+

---

Core Features

Feature	Description
Node Palette (Left Sidebar)	Collapsible panel with categorized nodes (templates, nodes tabs)
Flow Canvas (Center)	ReactFlow graph with zoom/pan, minimap, controls, grid background
Property Panel (Right Overlay)	Contextual property editor that appears when node is selected
Template Library	Dialog for browsing and loading saved templates
Drag-and-Drop	Drag nodes from palette to canvas to add them
Connection Handles	Connect nodes by dragging from output to input handles
Interaction Modes	Toggle between pan and selection modes (Ctrl to temporarily reverse)
Execution Lock	Canvas is read-only during flow execution
Layout Persistence	Sidebar width persists in local storage
Snap to Grid	Nodes align to 15px grid for neat layouts

---

Usage Guide

Basic Workflow

1. Open Orchestrator: Navigate to Orchestrator page (flows auto-load)
2. Add Nodes: Drag nodes from palette OR double-click palette items
3. Connect Nodes: Drag from output handle to input handle
4. Configure Nodes: Click node to open property panel, edit properties
5. Save Flow: Click save button in toolbar
6. Use Templates: Open template library to browse/load templates

Key Interactions

Interaction	How to Use
Add node (drag)	Drag node from palette to canvas
Add node (double-click)	Double-click palette item
Connect nodes	Drag from source output handle to target input handle
Select node	Click node (opens property panel)
Deselect	Click canvas background
Move node	Drag node (when not executing)
Delete node/edge	Select and press Backspace/Delete (when not executing)
Zoom in/out	Use zoom controls or mouse wheel
Fit view	Click fit view button
Pan canvas	Drag canvas (pan mode) or use middle mouse button
Toggle interaction mode	Click mode toggle button or hold Ctrl (temporarily reverse)
Collapse palette	Click collapse button (or click expand button when collapsed)
Open template library	Click template library button in toolbar

Node Categories

The node palette organizes nodes into categories:

• Prompt Templates - Pre-built prompt templates with variables
• Commands - Slash command invocations
• Tools - External tool integrations
• Custom - User-defined nodes

Canvas Controls

Control	Location	Function
Zoom In/Out	Controls (bottom-right)	Zoom canvas in/out
Fit View	Controls (bottom-right)	Fit all nodes in view
Interactive Mode	Controls (bottom-right)	Toggle pan/selection mode
Mini Map	Bottom-right	Overview of entire flow
Grid Background	Canvas	Visual reference for alignment

---

Property Panel

The property panel appears as an overlay when a node is selected. It provides:

Common Properties

Property	Description
Node Name	Display name for the node
Node ID	Unique identifier (auto-generated)
Execution Mode	How node executes (sync/async/etc.)
Instructions	Prompt instructions with template support
Variables	Input/output variable definitions
Tags	Custom tags for organization
Commands	Associated slash commands

Template Editor Features

• Built-in Templates: Pre-defined instruction templates
• Custom Tags: Tag-based instruction system (e.g., {{$INPUT}})
• Variable Inputs: Template variables with custom values
• Preview: Live preview of rendered instructions

---

Components Reference

Main Components

Component	Location	Purpose
OrchestratorPage	@/pages/orchestrator/OrchestratorPage.tsx	Main orchestrator page
FlowToolbar	@/pages/orchestrator/FlowToolbar.tsx	Top toolbar with actions
LeftSidebar	@/pages/orchestrator/LeftSidebar.tsx	Collapsible node palette
FlowCanvas	@/pages/orchestrator/FlowCanvas.tsx	ReactFlow graph canvas
PropertyPanel	@/pages/orchestrator/PropertyPanel.tsx	Node property editor overlay
TemplateLibrary	@/pages/orchestrator/TemplateLibrary.tsx	Template browser dialog
NodeLibrary	@/pages/orchestrator/NodeLibrary.tsx	Node palette content
InlineTemplatePanel	@/pages/orchestrator/InlineTemplatePanel.tsx	Template palette content
InteractionModeToggle	@/pages/orchestrator/InteractionModeToggle.tsx	Pan/selection mode toggle

Node Types

Node Type	Purpose
PromptTemplateNode	Unified prompt template node with instructions
Custom nodes	Extended from base node types

State Management

• Local state (OrchestratorPage):

  • isTemplateLibraryOpen: boolean

• Zustand stores (useFlowStore):

  • nodes - Flow nodes array
  • edges - Flow edges array
  • selectedNodeId - Currently selected node
  • isPaletteOpen - Palette expanded state
  • isPropertyPanelOpen - Property panel visibility
  • leftPanelTab - Active palette tab ('templates' | 'nodes')
  • interactionMode - Pan or selection mode

• Execution store (useExecutionStore):

  • isExecuting - Whether flow is currently executing (locks canvas)

---

Configuration

Keyboard Shortcuts

Key	Action
Backspace/Delete	Delete selected node/edge (when not executing)
Ctrl/Cmd (hold)	Temporarily reverse interaction mode
Mouse wheel	Zoom in/out
Middle mouse drag	Pan canvas

Canvas Settings

{
  snapToGrid: true,
  snapGrid: [15, 15],  // 15px grid alignment
  nodesDraggable: !isExecuting,
  nodesConnectable: !isExecuting,
  elementsSelectable: !isExecuting
}

---

Related Links

• Terminal Dashboard - Terminal-first execution monitoring
• Sessions - Workflow session management
• Commands Management - Slash command configuration