gateway/docs/code-documentation/interactive-workflow-planning-ui.md

# Interactive Workflow Planning UI Documentation

This document describes how to build an interactive user interface for planning and managing automated workflows, including what's currently available in the gateway, what's missing, and requirements for a complete UI implementation.

## Table of Contents

1. [Overview](#overview)
2. [Current Gateway Capabilities](#current-gateway-capabilities)
3. [UI Requirements](#ui-requirements)
4. [Missing Gateway Features](#missing-gateway-features)
5. [Gateway API Endpoints Needed](#gateway-api-endpoints-needed)
6. [UI Implementation Guide](#ui-implementation-guide)
7. [Data Flow](#data-flow)
8. [Validation and Error Handling](#validation-and-error-handling)

---

## Overview

The interactive workflow planning UI allows users to visually create, edit, and manage automated workflows without manually writing JSON. The gateway must provide all necessary metadata, validation, and execution capabilities to support a fully dynamic frontend that requires no hardcoded logic.

**Key Principles:**
- **Gateway-First**: All business logic, validation, and metadata come from the gateway
- **No Frontend Hardcoding**: Action types, parameters, validation rules, and schemas are served dynamically
- **Progressive Enhancement**: UI should work with basic features and enhance as gateway capabilities expand
- **Real-time Validation**: Validate plans as users build them, not just on save

---

## Current Gateway Capabilities

### Available API Endpoints

The gateway currently provides these automation-related endpoints:

#### 1. Automation CRUD Operations
- **GET `/api/automations`**: List all automations (with pagination)
- **POST `/api/automations`**: Create new automation definition
- **GET `/api/automations/{automationId}`**: Get single automation by ID
- **PUT `/api/automations/{automationId}`**: Update automation definition
- **DELETE `/api/automations/{automationId}`**: Delete automation definition
- **POST `/api/automations/{automationId}/execute`**: Execute automation immediately

#### 2. Metadata Endpoints
- **GET `/api/automations/attributes`**: Get AutomationDefinition field definitions for form generation

#### 3. Connection Management
- **GET `/api/connections/`**: Get all user connections (for use in action parameters)
  - Returns list of `UserConnection` objects with connection metadata
  - Automatically refreshes expired OAuth tokens
  - Users can only see their own connections (security enforced)
  - Used by UI to populate connection selectors in action parameter forms

#### 4. File Management
- **GET `/api/files/list`**: Get all user files (for use in document references)
  - Returns paginated list of `FileItem` objects
  - Supports optional pagination, sorting, and filtering
  - Used by UI to populate file selectors when building document references
  - Enables users to reference existing files (e.g., `docItem:{id}:{filename}`)
- **POST `/api/files/upload`**: Upload new files to the system
  - Accepts file upload via multipart form data
  - Returns `FileItem` metadata with file ID and name
  - Handles duplicate detection (exact duplicates reuse existing file)
  - Optional `workflowId` parameter to associate file with workflow
  - Used by UI to allow users to upload files during workflow creation
  - After upload, UI should refresh file list to include newly uploaded file

### Available Data Structures

#### AutomationDefinition Model
```json
{
  "id": "uuid",
  "mandateId": "mandate-id",
  "label": "Workflow Name",
  "schedule": "0 22 * * *",
  "template": "Template text with <!--TEMPLATE_PLAN_START-->...<!--TEMPLATE_PLAN_END-->",
  "placeholders": {"KEY": "value"},
  "active": true,
  "eventId": "optional-event-id",
  "status": "active|inactive",
  "executionLogs": [...],
  "_createdBy": "user-id",
  "_createdAt": "timestamp",
  "_modifiedAt": "timestamp"
}
```

#### TaskPlan Structure (embedded in template)
```json
{
  "overview": "Plan description",
  "tasks": [
    {
      "id": "task1",
      "objective": "Task objective",
      "dependencies": ["task0"],
      "successCriteria": ["criteria1"],
      "estimatedComplexity": "simple|medium|complex",
      "userMessage": "User-facing message",
      "actions": [
        {
          "id": "action1",
          "execMethod": "ai",
          "execAction": "process",
          "execParameters": {...},
          "execResultLabel": "result_label",
          "expectedDocumentFormats": ["pdf"],
          "userMessage": "Action description"
        }
      ]
    }
  ],
  "userMessage": "Overall user message"
}
```

### Internal Capabilities (Not Yet Exposed)

The gateway has internal functions that could be exposed:

1. **Method Discovery**: `extractAvailableMethods()` - Returns available execMethod/execAction combinations
2. **Action Signatures**: `getActionSignature()` - Returns parameter schemas for actions
3. **Document Reference Resolution**: `getAvailableDocuments()` - Returns available document references
4. **Plan Validation**: `WorkflowValidator.validateTaskPlan()` - Validates TaskPlan structure

**Note**: Connection references are already available via the existing `GET /api/connections/` endpoint. The UI can format these into connection reference strings (e.g., `connection:msft:username`) based on the connection metadata returned by this endpoint.

---

## UI Requirements

### Core Features

#### 1. Workflow Builder Interface

**Visual Workflow Editor:**
- Drag-and-drop task creation
- Visual dependency graph (tasks connected by dependencies)
- Task and action configuration forms
- Real-time validation feedback
- Plan preview (JSON view)

**Task Management:**
- Add/remove/reorder tasks
- Configure task properties (id, objective, dependencies, success criteria)
- Visual dependency editor (select dependencies from dropdown)
- Task complexity indicator

**Action Management:**
- Add/remove actions within tasks
- Action type selector (method + action combination)
- Dynamic parameter forms based on action signature
- Document reference selector (dropdown of available references)
- Connection selector (dropdown of user connections)
- Result label configuration

#### 2. Automation Definition Management

**Form Fields:**
- Label (text input, required)
- Schedule (cron expression selector or manual input)
- Template (auto-generated from visual plan, editable)
- Placeholders (key-value editor)
- Active toggle (checkbox)

**Metadata Display:**
- Execution logs viewer
- Status indicator
- Created/modified timestamps
- Creator information

#### 3. Plan Validation

**Real-time Validation:**
- Required field checks
- Task ID uniqueness
- Dependency validation (no circular dependencies, valid task IDs)
- Action parameter validation
- Document reference validation
- Connection reference validation

**Error Display:**
- Inline field errors
- Task-level errors
- Action-level errors
- Summary error list

#### 4. Testing and Execution

**Test Execution:**
- "Test Run" button (executes without saving)
- Execution status monitoring
- Result preview
- Error display

**Save and Schedule:**
- Save as draft
- Activate automation
- Schedule configuration

### UI Components Needed

1. **Task List/Board**: Visual representation of tasks
2. **Task Editor**: Form for editing task properties
3. **Action Editor**: Dynamic form for action configuration
4. **Dependency Graph**: Visual representation of task dependencies
5. **Parameter Forms**: Dynamic forms based on action signatures
6. **Reference Selectors**: Dropdowns for documents and connections
7. **Validation Panel**: Real-time error display
8. **Plan Preview**: JSON view of generated plan
9. **Execution Monitor**: Status display for test runs

---

## Missing Gateway Features

### Critical Missing Endpoints

#### 1. **GET `/api/workflows/metadata/actions`**
**Purpose**: Get list of available actions for action selection in workflow plans

**Response Format**:
```json
{
  "actions": [
    {
      "compoundName": "ai.process",
      "method": "ai",
      "methodDescription": "AI processing capabilities",
      "action": "process",
      "actionDescription": "Process documents with AI",
      "signature": {
        "parameters": [
          {
            "name": "prompt",
            "type": "string",
            "required": true,
            "description": "AI prompt text",
            "default": null
          },
          {
            "name": "documentList",
            "type": "array[string]",
            "required": false,
            "description": "Document references",
            "default": []
          },
          {
            "name": "options",
            "type": "object",
            "required": false,
            "description": "Processing options",
            "default": {},
            "properties": {
              "operationType": {
                "type": "string",
                "enum": ["TEXT_ANALYSIS", "SUMMARIZATION", "TRANSLATION"],
                "description": "Type of operation"
              },
              "priority": {
                "type": "string",
                "enum": ["low", "normal", "high"],
                "default": "normal"
              }
            }
          }
        ],
        "returnType": "ActionResult"
      }
    },
    {
      "compoundName": "ai.analyze",
      "method": "ai",
      "methodDescription": "AI processing capabilities",
      "action": "analyze",
      "actionDescription": "Analyze documents and extract insights",
      "signature": {
        "parameters": [...]
      }
    },
    {
      "compoundName": "sharepoint.search",
      "method": "sharepoint",
      "methodDescription": "SharePoint integration capabilities",
      "action": "search",
      "actionDescription": "Search SharePoint for documents",
      "signature": {
        "parameters": [...]
      }
    }
  ],
  "groupedByMethod": {
    "ai": {
      "methodDescription": "AI processing capabilities",
      "actions": ["ai.process", "ai.analyze", "ai.generate"]
    },
    "sharepoint": {
      "methodDescription": "SharePoint integration capabilities",
      "actions": ["sharepoint.search", "sharepoint.download", "sharepoint.upload"]
    }
  }
}
```

**Implementation Notes**:
- Should call `extractAvailableMethods()` or `getMethodsList()` internally
- Should flatten the structure to prioritize actions (users select actions, not methods)
- Should include full parameter schemas from `getActionSignature()` for each action
- Should include parameter descriptions from docstrings
- Should include enum values for select fields
- Should indicate required vs optional parameters
- Should include `groupedByMethod` for UI grouping/filtering by method category
- Each action should include its parent method information for context

#### 2. **POST `/api/workflows/validate/plan`**
**Purpose**: Validate a TaskPlan JSON structure before saving

**Request Format**:
```json
{
  "plan": {
    "overview": "...",
    "tasks": [...]
  }
}
```

**Response Format**:
```json
{
  "valid": true,
  "errors": [],
  "warnings": [],
  "validationDetails": {
    "structureValid": true,
    "taskIdsUnique": true,
    "dependenciesValid": true,
    "actionsValid": true,
    "documentReferencesValid": true
  }
}
```

**Error Format**:
```json
{
  "valid": false,
  "errors": [
    {
      "level": "plan|task|action",
      "taskId": "task1",
      "actionId": "action1",
      "field": "execMethod",
      "message": "Invalid execMethod: 'invalid_method'",
      "code": "INVALID_METHOD"
    }
  ],
  "warnings": [
    {
      "level": "task",
      "taskId": "task1",
      "message": "Task has no dependencies but may depend on previous tasks",
      "code": "MISSING_DEPENDENCY"
    }
  ]
}
```

**Implementation Notes**:
- Should use `WorkflowValidator.validateTaskPlan()`
- Should validate action method/action combinations exist
- Should validate document references format (not existence, as workflow may not exist yet)
- Should check for circular dependencies
- Should validate parameter types match signatures

#### 3. **GET `/api/workflows/metadata/document-references`**
**Purpose**: Get available document reference patterns and examples

**Response Format**:
```json
{
  "referencePatterns": [
    {
      "pattern": "docList:round1_usercontext",
      "description": "All documents from user's first message",
      "example": "docList:round1_usercontext"
    },
    {
      "pattern": "docList:{label}",
      "description": "All documents with specific label from previous action",
      "example": "docList:extracted_content"
    },
    {
      "pattern": "docItem:{id}:{filename}",
      "description": "Specific document by ID and filename",
      "example": "docItem:123:report.pdf"
    }
  ],
  "availableReferences": [
    "docList:round1_usercontext"
  ]
}
```

**Implementation Notes**:
- For new workflows, only show `docList:round1_usercontext` (initial user documents)
- For existing workflows, show actual available references from workflow
- Should include pattern descriptions for UI tooltips

#### 4. **GET `/api/workflows/metadata/taskplan-schema`**
**Purpose**: Get JSON schema for TaskPlan structure

**Response Format**:
```json
{
  "schema": {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
      "overview": {
        "type": "string",
        "description": "Overall plan description"
      },
      "tasks": {
        "type": "array",
        "items": {
          "$ref": "#/definitions/TaskStep"
        }
      }
    },
    "definitions": {
      "TaskStep": {...},
      "ActionItem": {...}
    }
  },
  "fieldDescriptions": {
    "overview": "Brief description of the overall plan",
    "tasks[].id": "Unique task identifier (e.g., 'task1', 'extract_content')",
    "tasks[].objective": "What the task accomplishes"
  }
}
```

**Implementation Notes**:
- Should generate from Pydantic models (`TaskPlan`, `TaskStep`, `ActionItem`)
- Should include field descriptions from model docstrings
- Should include validation rules (required fields, types, enums)

#### 5. **GET `/api/workflows/metadata/action-signature/{method}/{action}`**
**Purpose**: Get detailed parameter schema for specific action

**Request**: `GET /api/workflows/metadata/action-signature/ai/process`

**Response Format**:
```json
{
  "method": "ai",
  "action": "process",
  "compoundName": "ai.process",
  "description": "Process documents with AI",
  "parameters": {
    "prompt": {
      "type": "string",
      "required": true,
      "description": "AI prompt text",
      "uiType": "textarea",
      "uiLabel": "Prompt",
      "uiPlaceholder": "Enter your prompt..."
    },
    "documentList": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "required": false,
      "description": "Document references",
      "uiType": "multiselect",
      "uiLabel": "Documents",
      "uiOptions": "document-references"
    },
    "options": {
      "type": "object",
      "required": false,
      "description": "Processing options",
      "properties": {
        "operationType": {
          "type": "string",
          "enum": ["TEXT_ANALYSIS", "SUMMARIZATION", "TRANSLATION"],
          "required": false,
          "default": "TEXT_ANALYSIS",
          "uiType": "select",
          "uiLabel": "Operation Type"
        }
      }
    }
  },
  "returnType": "ActionResult",
  "resultLabelRequired": false
}
```

**Implementation Notes**:
- Should extract from method action signatures
- Should include UI hints (uiType, uiLabel, uiPlaceholder)
- Should indicate which parameters reference documents/connections
- Should include default values
- Should include enum values for select fields

#### 6. **GET `/api/workflows/templates`**
**Purpose**: Provide pre-built workflow templates

**Response Format**:
```json
{
  "templates": [
    {
      "id": "template-doc-processing",
      "name": "Document Processing Pipeline",
      "description": "Extract, analyze, and generate report",
      "category": "document-processing",
      "plan": {...},
      "placeholders": ["DATE", "REPORT_TITLE"]
    }
  ]
}
```

## UI Implementation Guide

### Architecture Overview

```
┌─────────────────┐
│   UI Frontend    │
│  (React/Vue/etc)│
└────────┬─────────┘
         │
         │ HTTP API Calls
         │
┌────────▼─────────────────────────────────────┐
│         Gateway API Layer                     │
│  ┌─────────────────────────────────────────┐ │
│  │ Metadata Endpoints                       │ │
│  │ - /api/workflows/metadata/*             │ │
│  └─────────────────────────────────────────┘ │
│  ┌─────────────────────────────────────────┐ │
│  │ Validation Endpoints                    │ │
│  │ - /api/workflows/validate/*             │ │
│  └─────────────────────────────────────────┘ │
│  ┌─────────────────────────────────────────┐ │
│  │ Automation CRUD                         │ │
│  │ - /api/automations/*                    │ │
│  └─────────────────────────────────────────┘ │
└──────────────────────────────────────────────┘
```

### Data Flow

**Why Connection and File Management Routes Are Needed:**

The workflow planning UI requires access to existing connections and files for two critical purposes:

1. **Connection References**: Many actions require connection references (e.g., `connection:msft:username` for SharePoint actions). Users need to see their available connections to select them when configuring action parameters. The UI fetches connections via `GET /api/connections/` to populate connection selectors in action parameter forms.

2. **File References**: Users may need to reference specific files in document lists (e.g., `docItem:{id}:{filename}`). The UI fetches available files via `GET /api/files/list` to enable file selection when building document references. This is especially important when users want to reference files uploaded to the system rather than workflow-generated documents.

These routes are **existing gateway endpoints** that are already available and should be used by the UI rather than creating new metadata endpoints for the same purpose.

#### 1. Initial Load

```mermaid
sequenceDiagram
    participant User
    participant UI as UI Frontend
    participant Gateway as Gateway API
    
    User->>UI: Open workflow builder
    UI->>Gateway: GET /api/workflows/metadata/actions
    Gateway-->>UI: List of available actions
    UI->>Gateway: GET /api/connections/
    Gateway-->>UI: User's available connections
    UI->>Gateway: GET /api/files/list
    Gateway-->>UI: User's available files
    UI-->>User: UI Ready - Can build workflows
```

#### 2. Creating New Workflow

```mermaid
sequenceDiagram
    participant User
    participant UI as UI Frontend
    participant Gateway as Gateway API
    
    User->>UI: Click "New Workflow"
    UI->>UI: Create empty plan structure
    User->>UI: Add task
    User->>UI: Add action to task
    UI->>Gateway: GET /api/workflows/metadata/action-signature/{method}/{action}
    Gateway-->>UI: Action parameter schema
    UI->>UI: Render dynamic parameter form
    
    alt Action requires connections
        UI->>Gateway: GET /api/connections/
        Gateway-->>UI: User's available connections
        UI->>UI: Populate connection selector dropdown
    end
    
    alt Action requires document references
        UI->>Gateway: GET /api/files/list
        Gateway-->>UI: User's available files
        UI->>UI: Populate file/document selector dropdown
        
        alt User uploads new file
            User->>UI: Click "Upload File"
            User->>UI: Select file to upload
            UI->>Gateway: POST /api/files/upload (with file)
            Gateway-->>UI: Uploaded file metadata
            UI->>Gateway: GET /api/files/list (refresh list)
            Gateway-->>UI: Updated files list (includes new file)
            UI->>UI: Update file selector dropdown
        end
    end
    
    User->>UI: Fill parameters
    User->>UI: Select document references (from metadata + files)
    User->>UI: Select connections (from connections API)
    UI->>Gateway: POST /api/workflows/validate/plan
    Gateway-->>UI: Validation results (errors/warnings)
    UI->>UI: Display validation feedback
    User->>UI: Click "Save"
    UI->>UI: Embed plan in template field
    UI->>Gateway: POST /api/automations (with template)
    Gateway-->>UI: Created automation
    UI-->>User: Success message
```

#### 3. Editing Existing Workflow

```mermaid
sequenceDiagram
    participant User
    participant UI as UI Frontend
    participant Gateway as Gateway API
    
    User->>UI: Open automation
    UI->>Gateway: GET /api/automations/{id}
    Gateway-->>UI: AutomationDefinition with template
    UI->>UI: Extract plan from template field (client-side parsing)
    
    alt Need to resolve references in plan
        UI->>Gateway: GET /api/connections/
        Gateway-->>UI: User's available connections (for validation)
        UI->>Gateway: GET /api/files/list
        Gateway-->>UI: User's available files (for validation)
    end
    
    UI->>UI: Render plan in visual editor
    UI-->>User: Display workflow editor
    User->>UI: Edit plan
    
    alt User modifies action requiring connections/files
        UI->>Gateway: GET /api/connections/
        Gateway-->>UI: Updated connections list
        UI->>Gateway: GET /api/files/list
        Gateway-->>UI: Updated files list
    end
    
    UI->>Gateway: POST /api/workflows/validate/plan
    Gateway-->>UI: Validation results
    UI->>UI: Display validation feedback
    User->>UI: Click "Save"
    UI->>UI: Embed plan in template field
    UI->>Gateway: PUT /api/automations/{id} (with updated template)
    Gateway-->>UI: Updated automation
    UI-->>User: Success message
```

#### 4. Plan Validation

```mermaid
sequenceDiagram
    participant User
    participant UI as UI Frontend
    participant Gateway as Gateway API
    
    Note over UI: User edits workflow plan
    
    alt Real-time validation (on change)
        User->>UI: Modify plan (add/edit task/action)
        UI->>UI: Debounce timer (wait for pause in typing)
        UI->>Gateway: POST /api/workflows/validate/plan
        Note right of Gateway: Validates:<br/>- Structure<br/>- Task IDs uniqueness<br/>- Dependencies<br/>- Action methods/actions<br/>- Parameter types<br/>- Document references format
        Gateway-->>UI: Validation results (errors/warnings)
        alt Plan has errors
            UI->>UI: Display inline errors
            UI->>UI: Highlight invalid fields
            UI->>UI: Show error summary panel
            UI-->>User: Visual feedback (red indicators)
        else Plan has warnings only
            UI->>UI: Display warnings
            UI->>UI: Show warning summary panel
            UI-->>User: Visual feedback (yellow indicators)
        else Plan is valid
            UI->>UI: Clear all error indicators
            UI->>UI: Show success indicator
            UI-->>User: Visual feedback (green checkmark)
        end
    end
    
    alt Manual validation (before save/execute)
        User->>UI: Click "Save" or "Test Run"
        UI->>Gateway: POST /api/workflows/validate/plan (final check)
        Gateway-->>UI: Validation results
        alt Plan is invalid
            UI->>UI: Display validation errors prominently
            UI-->>User: Block save/execute, show errors
        else Plan is valid
            UI->>UI: Proceed with save/execute
        end
    end
```

#### 5. Testing Workflow

```mermaid
sequenceDiagram
    participant User
    participant UI as UI Frontend
    participant Gateway as Gateway API
    
    User->>UI: Click "Test Run"
    UI->>Gateway: POST /api/workflows/validate/plan
    Gateway-->>UI: Validation results
    alt Plan is valid
        UI->>UI: Embed plan in template field
        UI->>Gateway: POST /api/automations (temporary)
        Gateway-->>UI: Created automation
        UI->>Gateway: POST /api/automations/{id}/execute
        Gateway-->>UI: Workflow started
        loop Poll for status
            UI->>Gateway: GET /api/workflows/{workflowId}
            Gateway-->>UI: Workflow status
        end
        UI-->>User: Display execution results
    else Plan is invalid
        UI-->>User: Display validation errors
    end
```

### UI Component Structure

#### Component Hierarchy
```
WorkflowBuilder
├── WorkflowHeader (label, schedule, placeholders)
├── TaskList
│   ├── TaskCard (for each task)
│   │   ├── TaskHeader (id, objective, dependencies)
│   │   ├── ActionList
│   │   │   └── ActionCard (for each action)
│   │   │       ├── ActionSelector (method/action dropdown)
│   │   │       ├── ParameterForm (dynamic based on signature)
│   │   │       ├── DocumentReferenceSelector
│   │   │       ├── ConnectionSelector
│   │   │       └── ResultLabelInput
│   │   └── DependencySelector
│   └── AddTaskButton
├── ValidationPanel
├── PlanPreview (JSON view)
└── ActionBar (Save, Test, Execute)
```

#### Key Components

**1. ActionSelector Component**
```typescript
// Fetches from: GET /api/workflows/metadata/actions
interface ActionOption {
  compoundName: string;  // e.g., "ai.process"
  method: string;         // e.g., "ai"
  methodDescription: string;
  action: string;         // e.g., "process"
  actionDescription: string;
}

// Renders dropdown with actions as primary selection:
// [ai.process - Process documents with AI ▼]
// [ai.analyze - Analyze documents and extract insights ▼]
// [sharepoint.search - Search SharePoint for documents ▼]
// 
// Can be grouped/filtered by method using groupedByMethod from response
```

**2. ParameterForm Component**
```typescript
// Fetches from: GET /api/workflows/metadata/action-signature/{method}/{action}
interface ParameterSchema {
  name: string;
  type: string;
  required: boolean;
  description: string;
  uiType: 'text' | 'textarea' | 'select' | 'multiselect' | 'object';
  uiLabel: string;
  enum?: string[];
  properties?: ParameterSchema[]; // For nested objects
}

// Dynamically renders form fields based on schema
```

**3. DocumentReferenceSelector Component**
```typescript
// Fetches from: GET /api/workflows/metadata/document-references
interface DocumentReference {
  pattern: string;
  description: string;
  example: string;
}

// Renders dropdown with:
// - docList:round1_usercontext (All documents from user's first message)
// - docList:{label} (Custom label input)
// - docItem:{id}:{filename} (Specific document)
```

**4. ValidationPanel Component**
```typescript
// Validates via: POST /api/workflows/validate/plan
interface ValidationError {
  level: 'plan' | 'task' | 'action';
  taskId?: string;
  actionId?: string;
  field?: string;
  message: string;
  code: string;
}

// Displays errors inline and in summary panel
```

### State Management

#### Plan State Structure
```typescript
interface WorkflowPlanState {
  plan: {
    overview: string;
    userMessage: string;
    tasks: TaskStep[];
  };
  metadata: {
    actions: ActionMetadata[];
    documentReferences: DocumentReference[];
    connectionReferences: ConnectionReference[];
    schema: JSONSchema;
  };
  validation: {
    errors: ValidationError[];
    warnings: ValidationWarning[];
    isValid: boolean;
  };
  ui: {
    selectedTaskId: string | null;
    selectedActionId: string | null;
    expandedTasks: Set<string>;
    viewMode: 'visual' | 'json';
  };
}
```

#### State Updates Flow
```
User Action
  ↓
Update Local State
  ↓
Debounced Validation Call
  ↓
POST /api/workflows/validate/plan
  ↓
Update Validation State
  ↓
Update UI (show errors, enable/disable save)
```

### Form Generation Strategy

#### Dynamic Form Generation
1. **Fetch Schema**: Get action signature from gateway
2. **Generate Fields**: Create form fields based on parameter types
3. **Apply UI Hints**: Use uiType, uiLabel, uiPlaceholder from schema
4. **Handle Special Types**:
   - `documentList` → DocumentReferenceSelector
   - `connections` → ConnectionSelector
   - `enum` → Select dropdown
   - `object` → Nested form or JSON editor
5. **Validate**: Use schema types for client-side validation
6. **Submit**: Format as execParameters object

#### Example: AI Process Action Form
```typescript
// Schema from: GET /api/workflows/metadata/action-signature/ai/process
{
  "prompt": {
    "type": "string",
    "required": true,
    "uiType": "textarea",
    "uiLabel": "Prompt"
  },
  "documentList": {
    "type": "array",
    "uiType": "multiselect",
    "uiOptions": "document-references"
  },
  "options": {
    "type": "object",
    "properties": {
      "operationType": {
        "type": "string",
        "enum": ["TEXT_ANALYSIS", "SUMMARIZATION"],
        "uiType": "select"
      }
    }
  }
}

// Generated Form:
<Form>
  <TextareaField name="prompt" required />
  <DocumentReferenceSelector name="documentList" multiple />
  <ObjectField name="options">
    <SelectField name="operationType" options={["TEXT_ANALYSIS", "SUMMARIZATION"]} />
  </ObjectField>
</Form>
```

---

## Validation and Error Handling

### Validation Levels

#### 1. Client-Side Validation (Immediate)
- Required field checks
- Type validation (string, number, array, object)
- Format validation (task IDs, document references)
- Basic structure validation

#### 2. Gateway Validation (On Change/Save)
- Full structure validation
- Method/action existence
- Parameter type matching
- Dependency validation
- Reference format validation

#### 3. Execution Validation (On Execute)
- Document reference existence
- Connection availability
- Parameter completeness

### Error Display Strategy

#### Inline Errors
- Show errors next to fields
- Highlight invalid fields
- Show error messages in tooltips

#### Task/Action Level Errors
- Show error badges on task/action cards
- Expand to show details
- Highlight affected fields

#### Summary Panel
- List all errors grouped by level
- Allow clicking to navigate to error location
- Show error codes for debugging

### Error Recovery

#### Validation Errors
- Prevent save until resolved
- Allow test run with warnings
- Show suggestions for fixing errors

#### Execution Errors
- Display in execution log
- Allow retry
- Show error details

---

## Implementation Checklist

### Gateway Implementation

- [ ] **Phase 1: Critical Endpoints**
  - [ ] Implement `GET /api/workflows/metadata/actions`
  - [ ] Implement `GET /api/workflows/metadata/action-signature/{method}/{action}`
  - [ ] Implement `POST /api/workflows/validate/plan`
  - [ ] Implement `GET /api/workflows/metadata/document-references`

- [ ] **Phase 2: High Priority**
  - [ ] Implement `GET /api/workflows/metadata/taskplan-schema`
  - [ ] Implement `GET /api/workflows/templates`

### UI Implementation

- [ ] **Core Components**
  - [ ] WorkflowBuilder container
  - [ ] TaskList component
  - [ ] TaskCard component
  - [ ] ActionList component
  - [ ] ActionCard component

- [ ] **Form Components**
  - [ ] ActionSelector dropdown
  - [ ] Dynamic ParameterForm generator
  - [ ] DocumentReferenceSelector
  - [ ] ConnectionSelector
  - [ ] DependencySelector

- [ ] **Validation Components**
  - [ ] ValidationPanel
  - [ ] Inline error display
  - [ ] Error summary

- [ ] **Utility Components**
  - [ ] PlanPreview (JSON view)
  - [ ] PlanEditor (visual editor)
  - [ ] ExecutionMonitor

- [ ] **State Management**
  - [ ] Plan state management
  - [ ] Metadata caching
  - [ ] Validation state
  - [ ] UI state

- [ ] **API Integration**
  - [ ] Metadata fetching
  - [ ] Plan validation
  - [ ] Plan save/load
  - [ ] Automation CRUD
  - [ ] Execution monitoring

---

## Example Implementation Flow

### Scenario: User Creates Document Processing Workflow

1. **User opens workflow builder**
   - UI fetches: methods, document references, connection references, schema
   - UI renders empty workflow builder

2. **User adds first task**
   - User clicks "Add Task"
   - UI creates task with ID "task1"
   - User enters objective: "Extract content from documents"

3. **User adds action to task**
   - User clicks "Add Action" in task1
   - UI shows action selector dropdown
   - User selects "extraction.extractContent"
   - UI fetches action signature
   - UI renders parameter form:
     - documentList: DocumentReferenceSelector (shows "docList:round1_usercontext")
     - options: Object editor with processDocumentsIndividually, chunkAllowed
   - User selects "docList:round1_usercontext"
   - User sets resultLabel: "extracted_content"

4. **User adds second task**
   - User clicks "Add Task"
   - UI creates task with ID "task2"
   - User enters objective: "Analyze extracted content"
   - User sets dependency: ["task1"]
   - User adds action "ai.process"
   - UI renders parameter form:
     - prompt: Textarea
     - documentList: DocumentReferenceSelector (shows "docList:extracted_content" from task1)
     - options: Object editor
   - User enters prompt
   - User selects "docList:extracted_content"
   - User sets resultLabel: "analysis_result"

5. **User validates plan**
   - UI automatically validates on change
   - POST /api/workflows/validate/plan
   - Gateway returns: valid=true, no errors
   - UI shows green checkmark

6. **User saves workflow**
   - User enters label: "Document Analysis Workflow"
   - User sets schedule: "0 22 * * *"
   - User clicks "Save"
   - UI embeds plan in template field (client-side, wraps JSON in HTML comment markers)
   - UI calls POST /api/automations (creates automation with template field)
   - UI shows success message

7. **User tests workflow**
   - User clicks "Test Run"
   - UI calls POST /api/automations/{id}/execute
   - UI monitors execution status
   - UI displays results

---

## Conclusion

This documentation outlines the complete requirements for building an interactive workflow planning UI. The gateway must provide comprehensive metadata, validation, and plan management endpoints to support a fully dynamic frontend. By implementing the critical endpoints first, a basic UI can be built, with enhanced features added incrementally.

**Key Takeaways:**
1. Gateway must serve all metadata (actions, schemas, document references)
2. Gateway must provide validation before save/execute
3. UI handles plan extraction/embedding client-side (parsing template field)
4. UI should be fully dynamic based on gateway responses
5. No hardcoded logic in frontend - everything comes from gateway

**Required Gateway Endpoints:**
1. `GET /api/workflows/metadata/actions` - Action selection
2. `POST /api/workflows/validate/plan` - Plan validation
3. `GET /api/workflows/metadata/document-references` - Document reference patterns
4. `GET /api/workflows/metadata/taskplan-schema` - TaskPlan schema
5. `GET /api/workflows/metadata/action-signature/{method}/{action}` - Action parameter schemas
6. `GET /api/workflows/templates` - Pre-built templates

**Next Steps:**
1. Implement critical gateway endpoints (Phase 1)
2. Build basic UI components
3. Integrate validation
4. Add template library support