PSA/docs/workflow/workflow-visualization.md

# Workflow Visualization Component -- OUTDATED -- CURRENTLY IMPLEMENTATION MAY DIFFER

The Workflow Visualization Component provides a visual representation of workflow definitions and their execution status. It is designed to be reusable across different parts of the application, from status displays for individual workflow executions to screens where users can view workflows as visualizations of business processes.

## 1. Overview

The visualization component uses ReactFlow to render workflow definitions as interactive graphs, with nodes representing states and actions, and edges representing transitions and dependencies. It can display both static workflow definitions and real-time execution status, with color-coding to indicate the state of each component.

### Key Features

- **View-only visualization** of workflow definitions and executions
- **Real-time status updates** through configurable polling
- **Color-coded representation** of workflow states and action statuses
- **Reusable component** for multiple contexts
- **Automatic layout** for complex workflows
- **Manual layout override** capabilities
- **Configurable display options** for different use cases

## 2. Component Structure

```
server/src/lib/workflow/visualization/
├── components/
│   ├── WorkflowVisualization.tsx       # Main component
│   ├── nodes/                          # Custom node components
│   │   ├── StateNode.tsx               # Workflow state node
│   │   ├── ActionNode.tsx              # Action node
│   │   ├── DecisionNode.tsx            # Conditional branch node
│   │   └── index.ts                    # Node type exports
│   ├── edges/                          # Custom edge components
│   │   ├── TransitionEdge.tsx          # State transition edge
│   │   ├── DependencyEdge.tsx          # Action dependency edge
│   │   └── index.ts                    # Edge type exports
│   └── controls/                       # UI controls
│       ├── ZoomControls.tsx            # Zoom and pan controls
│       ├── FilterControls.tsx          # Filtering options
│       └── LegendComponent.tsx         # Status color legend
├── adapters/
│   ├── definitionAdapter.ts            # Converts workflow definitions to ReactFlow format
│   ├── executionAdapter.ts             # Adds execution status to nodes and edges
│   └── layoutAdapter.ts                # Handles layout calculations and persistence
├── services/
│   ├── statusPollingService.ts         # Handles polling for status updates
│   ├── layoutService.ts                # Manages layout algorithms and persistence
│   └── visualizationDataService.ts     # Fetches and processes workflow data
├── hooks/
│   ├── useWorkflowVisualization.ts     # Main hook for visualization logic
│   ├── useStatusPolling.ts             # Hook for status polling
│   └── useWorkflowLayout.ts            # Hook for layout management
├── types/
│   ├── visualizationTypes.ts           # Type definitions for visualization components
│   └── statusMappingTypes.ts           # Types for status mapping
└── utils/
    ├── colorUtils.ts                   # Utilities for color mapping
    ├── layoutUtils.ts                  # Layout calculation utilities
    └── statusUtils.ts                  # Status mapping utilities
```

## 3. Data Flow

### 3.1 Workflow Definition → Visual Elements

1. The `definitionAdapter` transforms workflow definitions (states, transitions, actions) into ReactFlow nodes and edges
2. Layout algorithms position nodes for optimal visualization
3. The resulting graph is rendered using ReactFlow

```typescript
// Example transformation flow
WorkflowDefinition → definitionAdapter.transform() → ReactFlowElements → layoutAdapter.applyLayout() → PositionedReactFlowElements → ReactFlow
```

### 3.2 Execution Status → Visual Properties

1. The `executionAdapter` maps execution status to visual properties:
   - Current state: Highlighted border
   - Action status: Color coding (running: blue, success: green, failed: red)
   - Transition status: Line styles and animations
2. Status updates are applied to the visualization without full re-renders

```typescript
// Example status mapping flow
WorkflowExecution + ActionResults → executionAdapter.mapStatus() → StatusMappedElements → ReactFlow
```

### 3.3 Status Updates

1. The `statusPollingService` periodically fetches current execution status
2. Updates are applied to the visualization incrementally
3. Only changed elements are re-rendered

## 4. Integration with Existing Workflow System

The visualization component integrates with the following existing components:

### 4.1 State Machine (`stateMachine.ts`)

- Access to workflow states and transitions
- Current state information for active workflows
- Condition evaluation for transition display

### 4.2 Action Executor (`actionExecutor.ts`)

- Status of actions (running, completed, failed)
- Dependency information for visualization
- Error handling strategies for status display

### 4.3 Persistence Models

- `workflowExecutionModel.ts`: Overall workflow status
- `workflowEventModel.ts`: Event history for state transitions
- `workflowActionResultModel.ts`: Action execution results for status display
- `workflowTimerModel.ts`: Timer information for visualization

## 5. Component API

```typescript
interface WorkflowVisualizationProps {
  // Required props
  workflowDefinitionId: string;
  
  // Optional props with sensible defaults
  executionId?: string;                // If provided, shows execution status
  pollInterval?: number;               // Polling interval in ms (default: 5000)
  showControls?: boolean;              // Show zoom/pan controls (default: true)
  showLegend?: boolean;                // Show status legend (default: true)
  height?: string | number;            // Container height (default: 500px)
  width?: string | number;             // Container width (default: 100%)
  layout?: 'auto' | 'saved' | 'none';  // Layout strategy (default: 'auto')
  onNodeClick?: (nodeId: string, data: any) => void; // Optional interaction handler
  theme?: 'light' | 'dark';            // Visual theme (default: 'light')
  
  // Advanced options
  customNodeTypes?: Record<string, React.ComponentType<any>>;
  customEdgeTypes?: Record<string, React.ComponentType<any>>;
  layoutOptions?: any;                 // Advanced layout configuration
}
```

## 6. Status Mapping

| Element Type | Status | Visual Representation |
|--------------|--------|------------------------|
| State Node | Current | Highlighted border, bold text |
| State Node | Past | Normal appearance |
| State Node | Future | Faded appearance |
| Action Node | Not Started | Gray fill |
| Action Node | Running | Blue fill, pulsing animation |
| Action Node | Success | Green fill |
| Action Node | Failed | Red fill |
| Edge | Not Traversed | Gray, dashed line |
| Edge | Traversed | Solid line |
| Edge | Active | Animated line |

## 7. Implementation Strategy

### 7.1 Phase 1: Core Visualization

1. Set up the basic ReactFlow integration
2. Create custom node and edge components
3. Implement the definition adapter to transform workflow definitions into ReactFlow elements
4. Add basic styling and layout

### 7.2 Phase 2: Status Display

1. Implement the execution adapter to map workflow status to visual properties
2. Create the status polling service
3. Add visual indicators for different states (colors, animations)
4. Implement the status legend component

### 7.3 Phase 3: Integration and Reusability

1. Create container components for different contexts
2. Implement the props API for customization
3. Add layout optimization and persistence
4. Create documentation and examples

### 7.4 Instrumentation Enhancement

1. Leverage the existing TypeScript workflow definitions and AST to explicitly instrument workflow code.
2. Detect action proxy calls as action points and conditional/switch statements as decision points.
3. Map these instrumentation points as nodes in the ReactFlow visualization.
4. Enhance the visualization to clearly delineate these explicit actions and decisions along with static states.

## 8. Performance Considerations

### 8.1 Rendering Optimization

1. **Memoization**: Use React.memo and useMemo to prevent unnecessary re-renders
2. **Incremental Updates**: Only update changed nodes rather than re-rendering the entire workflow
3. **Virtualization**: For large workflows, implement virtualization to only render visible nodes

### 8.2 Data Fetching Optimization

1. **Throttling**: Limit update frequency for status changes
2. **Incremental Loading**: Load detailed information only when needed
3. **Caching**: Cache workflow definitions and layouts to reduce server load

### 8.3 Layout Optimization

1. **Automatic Layout**: Use efficient layout algorithms for complex workflows
2. **Layout Persistence**: Save and reuse layouts to avoid recalculation
3. **Incremental Layout**: Update only affected parts of the layout when the workflow changes

## 9. Accessibility Considerations

### 9.1 Keyboard Navigation

1. Implement keyboard shortcuts for navigation (arrow keys, tab)
2. Add focus indicators for keyboard users
3. Ensure all interactive elements are keyboard accessible

### 9.2 Screen Reader Support

1. Add appropriate ARIA attributes to nodes and edges
2. Provide text alternatives for visual status indicators
3. Implement descriptive announcements for status changes

### 9.3 Color and Contrast

1. Ensure sufficient contrast for all status colors
2. Use patterns in addition to colors for status indication
3. Support high contrast mode

### 9.4 Alternative Views

1. Provide a text-based or table view as an alternative to the graphical representation
2. Allow switching between different view modes
3. Implement zoom controls for users with visual impairments

## 10. Usage Examples

### 10.1 Basic Usage

```tsx
import { WorkflowVisualization } from 'server/src/lib/workflow/visualization';

function WorkflowStatusPage({ workflowId, executionId }) {
  return (
    <div className="workflow-status-container">
      <h1>Workflow Status</h1>
      <WorkflowVisualization
        workflowDefinitionId={workflowId}
        executionId={executionId}
        height={600}
        width="100%"
      />
    </div>
  );
}
```

### 10.2 Definition-Only View

```tsx
import { WorkflowVisualization } from 'server/src/lib/workflow/visualization';

function WorkflowDefinitionViewer({ workflowId }) {
  return (
    <div className="workflow-definition-container">
      <h1>Workflow Definition</h1>
      <WorkflowVisualization
        workflowDefinitionId={workflowId}
        // No executionId means definition-only view
        showControls={true}
        theme="light"
      />
    </div>
  );
}
```

### 10.3 Custom Styling

```tsx
import { WorkflowVisualization } from 'server/src/lib/workflow/visualization';
import { CustomStateNode, CustomActionNode } from './customNodes';

function CustomStyledWorkflow({ workflowId, executionId }) {
  return (
    <WorkflowVisualization
      workflowDefinitionId={workflowId}
      executionId={executionId}
      customNodeTypes={{
        state: CustomStateNode,
        action: CustomActionNode,
      }}
      theme="dark"
    />
  );
}
```

## 11. Conclusion

The Workflow Visualization Component provides a flexible, reusable way to visualize workflow definitions and their execution status. By leveraging ReactFlow and integrating with the existing workflow system, it offers a powerful tool for understanding and monitoring workflows throughout the application.