# Vue Flow Process Builder System Guide

## 📋 System Overview

This is a **Vue 3 + Nuxt 3** application that provides a visual process builder using **Vue Flow** library. The system allows users to create, edit, and manage business processes through a drag-and-drop interface with custom nodes and edges.

### 🏗️ **Core Architecture**
- **Frontend**: Vue 3 with Composition API + Nuxt 3
- **Flow Engine**: Vue Flow (Vue 3 compatible fork of React Flow)
- **Styling**: Tailwind CSS + Custom SCSS
- **State Management**: Pinia stores
- **Database**: Prisma ORM
- **UI Components**: Custom component library + FormKit

---

## 📁 File Structure & Key Locations

### **🎯 Main Process Builder**
```
pages/process-builder/
├── index.vue                    # Main process builder page
└── manage.vue                   # Process management page
```

### **🔧 Core Vue Flow Components**
```
components/process-flow/
├── ProcessFlowCanvas.vue         # Main Vue Flow canvas component
├── ArrowEdge.vue                # Custom edge component
├── custom/                      # Custom node components
│   ├── StartNode.vue            # Process start node
│   ├── EndNode.vue              # Process end node
│   ├── FormNode.vue             # Form task node
│   ├── ApiNode.vue              # API call node
│   ├── ScriptNode.vue           # Script execution node
│   ├── BusinessRuleNode.vue     # Business rule node
│   ├── NotificationNode.vue     # Notification node
│   ├── HtmlNode.vue             # HTML content node
│   ├── SubprocessNode.vue       # Subprocess node
│   ├── GatewayNode.vue          # Decision/gateway node
│   ├── TextAnnotation.vue       # Text annotation node
│   └── ProcessGroup.vue         # Process grouping node
├── notification/                # Notification system components
│   ├── NotificationManager.vue
│   ├── NotificationQueue.vue
│   └── NotificationLogs.vue
├── GatewayConditionManager.vue  # Gateway condition configuration UI
├── GatewayConditionManagerModal.vue # Modal for gateway setup
└── [25+ other process flow files]
```

### **📊 Configuration & Data**
```
composables/
├── processFlowNodes.js          # Node type definitions & configurations
├── nodeStyles.js                # Global CSS styles for all nodes
├── codemirrorThemes.js          # Code editor themes
└── themeList.js                 # UI theme configurations

docs/json/process-builder/
├── processDefinition.json       # Process structure schema
└── processVariables.json        # Process variable definitions

stores/
├── processBuilder.js            # Pinia store for process builder state
├── formBuilder.js               # Form builder state
└── layout.js                    # Layout configurations
```

### **🎨 Styling System**
```
assets/style/
├── css/                         # Compiled CSS
│   ├── tailwind.css
│   └── component/               # Component-specific styles
├── scss/
│   ├── main.scss                # Main SCSS entry point
│   └── custom/                  # Custom styling
│       ├── library/             # Third-party library styles
│       │   ├── _dropdown.scss
│       │   ├── _formkit.scss
│       │   └── _floatingvue.scss
│       └── transition/          # Animation styles
│           ├── fade.scss
│           └── page.scss

plugins/
├── process-flow-styles.client.js # Vue Flow styling injection
└── vue-codemirror.js            # Code editor plugin
```

### **⚙️ Server API**
```
server/api/
├── process/
│   ├── [id].get.js              # Get process definition
│   ├── [id].put.js              # Update process
│   ├── [id].delete.js           # Delete process
│   ├── [id]/
│   │   ├── publish.post.js      # Publish process
│   │   ├── duplicate.post.js    # Duplicate process
│   │   └── history.get.js       # Process history
│   └── dashboard/
│       └── summary.get.js       # Dashboard summary
└── forms/                       # Form-related APIs
    ├── [id].get.js
    ├── [id].put.js
    └── [id]/history.get.js
```

---

## 🔄 How the System Works

### **1. Vue Flow Integration**

#### **Main Canvas Component** (`ProcessFlowCanvas.vue`)
```vue
<template>
  <VueFlow
    v-model:nodes="nodes"
    v-model:edges="edges"
    :node-types="customNodeTypes"
    :edge-types="customEdgeTypes"
    @error="handleVueFlowError"
  >
    <Background />
    <Controls />
    <MiniMap />
  </VueFlow>
</template>

<script setup>
import { markRaw } from 'vue'
// Import all custom node components
import StartNode from './custom/StartNode.vue'
import FormNode from './custom/FormNode.vue'
// ... other imports

// Register node types with Vue Flow
const customNodeTypes = {
  'start': markRaw(StartNode),
  'form': markRaw(FormNode),
  'api': markRaw(ApiNode),
  // ... other node types
}
</script>
```

#### **Custom Node Structure**
Every custom node follows this pattern:

```vue
<script setup>
import { Handle, Position } from '@vue-flow/core'
import { computed } from 'vue'

// Props from Vue Flow
const props = defineProps([
  'id',           // Node ID
  'type',         // Node type
  'label',        // Node label  
  'selected',     // Selection state
  'data'          // Custom data object
])

// Shape class for dynamic styling
const shapeClass = computed(() => {
  const shape = props.data?.shape || 'rectangle'
  return `shape-${shape}`
})

// Node styling
const nodeStyle = computed(() => ({
  '--node-bg-color': props.data?.backgroundColor || 'white',
  '--node-border-color': props.data?.borderColor || '#ddd',
  '--node-text-color': props.data?.textColor || 'black'
}))
</script>

<template>
  <div 
    :class="['custom-node', 'node-form', shapeClass, { 'selected': selected }]"
    :style="nodeStyle"
  >
    <!-- Input handles -->
    <Handle type="target" :position="Position.Left" />
    
    <!-- Node content -->
    <div class="custom-node-content">
      <div class="custom-node-header">
        <span class="material-icons">description</span>
        <span class="custom-node-title">{{ data?.label || 'Form' }}</span>
      </div>
      <!-- Additional content -->
    </div>
    
    <!-- Output handles -->
    <Handle type="source" :position="Position.Right" />
  </div>
</template>
```

### **2. Node Shape System**

#### **Shape Configuration**
Nodes support multiple shapes through CSS `clip-path`:

```javascript
// Available shapes
const shapes = [
  'rectangle',      // Default rectangle
  'rounded-rectangle', // Rounded corners
  'circle',         // Circle shape
  'diamond',        // Diamond (gateway nodes)
  'hexagon',        // Hexagon shape
  'trapezoid',      // Trapezoid shape
  'parallelogram'   // Parallelogram shape
]
```

#### **Shape CSS Implementation** (`nodeStyles.js`)
```css
/* Rectangle (default) */
.custom-node.shape-rectangle {
  border-radius: 4px;
}

/* Hexagon shape */
.custom-node.shape-hexagon {
  background: none !important;
  border: none !important;
  border-radius: 0 !important;
}

.custom-node.shape-hexagon::before {
  content: '';
  position: absolute;
  top: 0; left: 0; right: 0; bottom: 0;
  background: var(--node-bg-color, white);
  border: 2px solid var(--node-border-color, #ddd);
  clip-path: polygon(25% 0%, 75% 0%, 100% 50%, 75% 100%, 25% 100%, 0% 50%);
  z-index: 0;
}

/* Node-type specific colors for shapes */
.node-form.shape-hexagon::before {
  border-left: 4px solid #9333ea; /* Purple */
}
```

### **3. Node Types & Configurations**

#### **Node Type Registry** (`processFlowNodes.js`)
```javascript
export const nodeTypes = {
  'start': {
    label: 'Start',
    icon: 'play_circle',
    color: '#10b981',
    allowedShapes: ['circle', 'rectangle'],
    defaultData: {
      label: 'Start',
      backgroundColor: '#dcfce7',
      borderColor: '#10b981'
    }
  },
  'form': {
    label: 'Form',
    icon: 'description',
    color: '#9333ea',
    allowedShapes: ['rectangle', 'rounded-rectangle', 'hexagon', 'trapezoid'],
    defaultData: {
      label: 'Form Task',
      formId: null,
      required: true
    }
  },
  // ... other node types
}
```

### **4. Process Builder State Management**

#### **Pinia Store** (`stores/processBuilder.js`)
```javascript
export const useProcessBuilderStore = defineStore('processBuilder', () => {
  // State
  const nodes = ref([])
  const edges = ref([])
  const selectedNode = ref(null)
  const processDefinition = ref({})
  
  // Actions
  const addNode = (nodeData) => {
    const newNode = {
      id: generateId(),
      type: nodeData.type,
      position: nodeData.position,
      data: { ...nodeTypes[nodeData.type].defaultData, ...nodeData.data }
    }
    nodes.value.push(newNode)
  }
  
  const updateNode = (nodeId, updates) => {
    const nodeIndex = nodes.value.findIndex(n => n.id === nodeId)
    if (nodeIndex > -1) {
      nodes.value[nodeIndex] = { ...nodes.value[nodeIndex], ...updates }
    }
  }
  
  return {
    nodes, edges, selectedNode, processDefinition,
    addNode, updateNode
  }
})
```

---

## 🛠️ Implementation Patterns

### **1. Adding a New Node Type**

#### **Step 1: Create Node Component**
```bash
# Create new component file
touch components/process-flow/custom/YourNewNode.vue
```

```vue
<!-- YourNewNode.vue -->
<script setup>
import { Handle, Position } from '@vue-flow/core'
import { computed } from 'vue'

const props = defineProps(['id', 'type', 'label', 'selected', 'data'])

const shapeClass = computed(() => {
  const shape = props.data?.shape || 'rectangle'
  return `shape-${shape}`
})
</script>

<template>
  <div :class="['custom-node', 'node-yournew', shapeClass, { 'selected': selected }]">
    <Handle type="target" :position="Position.Left" />
    <div class="custom-node-content">
      <span class="material-icons">your_icon</span>
      <span>{{ data?.label || 'Your Node' }}</span>
    </div>
    <Handle type="source" :position="Position.Right" />
  </div>
</template>
```

#### **Step 2: Register in ProcessFlowCanvas.vue**
```javascript
// Import the component
import YourNewNode from './custom/YourNewNode.vue'

// Add to customNodeTypes
const customNodeTypes = {
  // ... existing types
  'yournew': markRaw(YourNewNode),
}
```

#### **Step 3: Add Node Configuration**
```javascript
// In processFlowNodes.js
export const nodeTypes = {
  // ... existing types
  'yournew': {
    label: 'Your New Node',
    icon: 'your_icon',
    color: '#your-color',
    allowedShapes: ['rectangle', 'circle'],
    defaultData: {
      label: 'Your New Node',
      yourProperty: 'default-value'
    }
  }
}
```

#### **Step 4: Add Styling**
```css
/* In nodeStyles.js */
.node-yournew {
  background: white;
  border: 1px solid #ddd;
  border-left: 4px solid #your-color;
}
```

### **2. Adding Shape Support**

#### **Step 1: Define Shape CSS**
```css
/* In nodeStyles.js */
.custom-node.shape-yourshape {
  background: none !important;
  border: none !important;
  border-radius: 0 !important;
}

.custom-node.shape-yourshape::before {
  content: '';
  position: absolute;
  top: 0; left: 0; right: 0; bottom: 0;
  background: var(--node-bg-color, white);
  border: 2px solid var(--node-border-color, #ddd);
  clip-path: polygon(/* your shape points */);
  z-index: 0;
}
```

#### **Step 2: Add to Shape Lists**
```javascript
// In processFlowNodes.js or relevant config
const availableShapes = [
  // ... existing shapes
  'yourshape'
]

// Add to node type configurations
'form': {
  allowedShapes: ['rectangle', 'hexagon', 'yourshape']
}
```

### **3. Customizing Node Properties**

#### **Properties Panel Integration**
```vue
<!-- In node component -->
<script setup>
const props = defineProps(['id', 'type', 'label', 'selected', 'data'])

// Computed properties for dynamic behavior
const isRequired = computed(() => props.data?.required || false)
const formId = computed(() => props.data?.formId)
const customProperties = computed(() => props.data?.customProperties || {})
</script>

<template>
  <div class="custom-node">
    <!-- Display based on properties -->
    <div v-if="isRequired" class="required-indicator">*</div>
    <div class="node-content">
      {{ data?.label || 'Default Label' }}
    </div>
  </div>
</template>
```

### **4. Gateway Decision Logic**

#### **Gateway Configuration UI Components**
```vue
<!-- GatewayConditionManager.vue - Main condition builder -->
<template>
  <div class="gateway-condition-manager">
    <!-- Empty state when no paths defined -->
    <div v-if="localConditions.length === 0" class="text-center p-6">
      <h3>No Decision Paths Defined</h3>
      <p>Your process will always follow the default path</p>
      <button @click="addConditionGroup">Add Your First Path</button>
    </div>
    
    <!-- Decision paths list -->
    <div v-else class="conditions-list">
      <div v-for="(group, groupIndex) in localConditions" :key="group.id">
        <!-- Path header with collapse/expand -->
        <div class="path-header" @click="toggleGroupCollapse(group.id)">
          <span>Path {{ groupIndex + 1 }}</span>
          <span v-if="group.output">{{ group.output }}</span>
        </div>
        
        <!-- Path details when expanded -->
        <div v-if="!isGroupCollapsed(group.id)" class="path-details">
          <!-- Path name input -->
          <input v-model="group.output" placeholder="Path label (e.g. 'Yes', 'Approved')" />
          
          <!-- Conditions list -->
          <div class="conditions-list">
            <div v-for="(condition, conditionIndex) in group.conditions" :key="condition.id">
              <!-- Variable selection -->
              <VariableBrowser v-model="condition.variable" :availableVariables="availableVariables" />
              
              <!-- Operator selection -->
              <select v-model="condition.operator">
                <option v-for="op in getOperatorsForType(condition.valueType)" :key="op.value" :value="op.value">
                  {{ op.label }}
                </option>
              </select>
              
              <!-- Value input -->
              <input v-model="condition.value" :placeholder="getValuePlaceholder(condition)" />
              
              <!-- Logical operator for multiple conditions -->
              <div v-if="conditionIndex > 0">
                <label>Combine with: AND/OR</label>
                <input type="radio" v-model="condition.logicalOperator" value="and" /> AND
                <input type="radio" v-model="condition.logicalOperator" value="or" /> OR
              </div>
            </div>
          </div>
        </div>
      </div>
    </div>
  </div>
</template>
```

#### **Condition Evaluation Process**
```javascript
// Workflow execution evaluates gateway conditions
function evaluateConditionGroup(conditionGroup, variables) {
  if (!conditionGroup.conditions || conditionGroup.conditions.length === 0) {
    return false;
  }
  
  // If only one condition, evaluate it directly
  if (conditionGroup.conditions.length === 1) {
    return evaluateCondition(conditionGroup.conditions[0], variables);
  }
  
  // For multiple conditions, evaluate based on logical operators
  let result = evaluateCondition(conditionGroup.conditions[0], variables);
  
  for (let i = 1; i < conditionGroup.conditions.length; i++) {
    const condition = conditionGroup.conditions[i];
    const conditionResult = evaluateCondition(condition, variables);
    const operator = condition.logicalOperator || 'and';
    
    if (operator === 'and') {
      result = result && conditionResult;
    } else if (operator === 'or') {
      result = result || conditionResult;
    }
  }
  
  return result;
}

// Single condition evaluation
function evaluateCondition(condition, variables) {
  const { variable, operator, value, valueType } = condition;
  const variableValue = variables[variable];
  
  // Handle boolean type conversions
  let compareValue = value;
  if (valueType === 'boolean') {
    if (typeof value === 'string') {
      compareValue = value.toLowerCase() === 'true';
    } else {
      compareValue = Boolean(value);
    }
  }
  
  // Evaluate based on operator
  switch (operator) {
    case 'eq':
      return variableValue == compareValue;
    case 'gt':
      return Number(variableValue) > Number(compareValue);
    case 'is_true':
      return Boolean(variableValue) === true;
    // ... other operators
  }
}
```

#### **Decision Path Selection**
```javascript
// Determine which path to follow based on conditions
function getNextNodeIdForDecision(currentNodeId) {
  const currentNodeObj = workflowData.nodes.find(n => n.id === currentNodeId);
  const outgoingEdges = getOutgoingEdges(currentNodeId);
  
  if (!currentNodeObj || !outgoingEdges.length) return null;
  
  const { conditions = [] } = currentNodeObj.data || {};
  
  // Evaluate condition groups (each group represents a path)
  for (const conditionGroup of conditions) {
    if (evaluateConditionGroup(conditionGroup, variables)) {
      // Find the edge that matches this condition group's output label
      const edge = outgoingEdges.find(e => e.label === conditionGroup.output);
      if (edge) return edge.target;
    }
  }
  
  // If no conditions match, use default path
  const defaultEdge = outgoingEdges.find(e => e.data?.isDefault);
  if (defaultEdge) return defaultEdge.target;
  
  // Fallback to first edge
  return outgoingEdges[0]?.target || null;
}
```

---

## 🎨 Styling System

### **CSS Architecture**
1. **Global Styles** (`nodeStyles.js`) - Injected globally via plugin
2. **Component Styles** - Scoped styles in individual `.vue` files
3. **Tailwind Classes** - Utility classes for layout and spacing
4. **CSS Variables** - Dynamic theming support

### **CSS Variable System**
```css
/* Node supports dynamic styling via CSS variables */
.custom-node {
  background: var(--node-bg-color, white);
  border-color: var(--node-border-color, #ddd);
  color: var(--node-text-color, black);
}
```

```javascript
// Set in component
const nodeStyle = computed(() => ({
  '--node-bg-color': props.data?.backgroundColor || 'white',
  '--node-border-color': props.data?.borderColor || '#ddd',
  '--node-text-color': props.data?.textColor || 'black'
}))
```

### **Shape Override Pattern**
```css
/* Base node styles */
.node-form {
  background: white;
  border: 1px solid #ddd;
  border-radius: 4px;
}

/* Shape overrides */
.node-form.shape-hexagon {
  background: none !important;
  border: none !important;
  border-radius: 0 !important;
}
```

---

## 🔌 Plugin System

### **Vue Flow Styles Plugin** (`process-flow-styles.client.js`)
```javascript
export default defineNuxtPlugin(() => {
  // Inject global styles for Vue Flow nodes
  if (process.client) {
    const { injectGlobalStyles } = useNodeStyles()
    injectGlobalStyles()
  }
})
```

### **CodeMirror Integration** (`vue-codemirror.js`)
```javascript
export default defineNuxtPlugin(() => {
  // Register CodeMirror for script editing
  // Used in ScriptNode and ApiNode components
})
```

---

## 📊 Data Flow

### **Process Definition Structure**
```json
{
  "id": "process-uuid",
  "name": "Process Name",
  "version": "1.0.0",
  "nodes": [
    {
      "id": "node-1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": {
        "label": "Start Process",
        "backgroundColor": "#dcfce7",
        "shape": "circle"
      }
    }
  ],
  "edges": [
    {
      "id": "edge-1",
      "source": "node-1",
      "target": "node-2",
      "type": "default"
    }
  ],
  "variables": {},
  "settings": {}
}
```

### **Node Data Structure**
```javascript
// Standard node data properties
{
  id: 'unique-node-id',
  type: 'form|api|script|gateway|etc',
  position: { x: number, y: number },
  data: {
    // Universal properties
    label: 'Node Label',
    shape: 'rectangle|circle|hexagon|etc',
    backgroundColor: '#ffffff',
    borderColor: '#dddddd',
    textColor: '#000000',
    
    // Type-specific properties
    formId: 'form-uuid',        // For form nodes
    apiEndpoint: 'url',         // For API nodes
    scriptCode: 'javascript',   // For script nodes
    conditions: [],             // For gateway nodes (see Gateway Conditions section)
    
    // Custom properties
    customProperties: {}
  }
}
```

### **Gateway Conditions Structure**
```javascript
// Gateway node conditions format (group-based)
{
  id: 'gateway-node-id',
  type: 'gateway',
  data: {
    label: 'Decision Point',
    conditions: [
      {
        id: 'condition-group-1',
        output: 'Path Label',           // Label for this decision path
        conditions: [                   // Array of conditions for this path
          {
            id: 'condition-1',
            variable: 'processVariable', // Process variable to evaluate
            operator: 'eq',             // Comparison operator
            value: 'expectedValue',     // Value to compare against
            valueType: 'string',        // Data type (string, boolean, number, etc.)
            logicalOperator: 'and'      // How to combine with next condition (and/or)
          }
          // ... more conditions for this path
        ]
      }
      // ... more condition groups (paths)
    ],
    defaultPath: 'Default'              // Default path if no conditions match
  }
}
```

### **Supported Condition Operators**
```javascript
// String operators
'eq', 'equals', '=='           // Equal to
'neq', 'not_equals', '!='      // Not equal to
'contains'                     // Contains substring
'not_contains'                 // Does not contain
'starts_with'                  // Starts with
'ends_with'                    // Ends with
'empty'                        // Is empty/null
'not_empty'                    // Is not empty/null
'regex'                        // Matches regex pattern

// Numeric operators
'gt', 'greater_than', '>'      // Greater than
'lt', 'less_than', '<'         // Less than
'gte', 'greater_than_or_equal', '>=' // Greater than or equal
'lte', 'less_than_or_equal', '<='    // Less than or equal
'between'                      // Between two values
'not_between'                  // Not between two values

// Boolean operators
'is_true'                      // Is true
'is_false'                     // Is false

// Date operators
'today'                        // Is today
'this_week'                    // Is this week
'this_month'                   // Is this month
'this_year'                    // Is this year

// Object operators
'has_property'                 // Has specific property
'property_equals'              // Property equals value
```

---

## 🐛 Common Issues & Solutions

### **1. Nodes Not Displaying in Production**
**Problem**: Custom nodes show as empty boxes in production build.
**Solution**: Use file-based components with `markRaw()` wrapper.

```javascript
// ❌ Wrong - breaks in production
const nodeTypes = {
  'form': {
    template: '<div>Form Node</div>'
  }
}

// ✅ Correct - works in production
import FormNode from './custom/FormNode.vue'
const nodeTypes = {
  'form': markRaw(FormNode)
}
```

### **2. Shapes Not Displaying**
**Problem**: Node shapes remain rectangular despite shape selection.
**Solution**: Ensure shape CSS overrides base styles with `!important`.

```css
/* ❌ Wrong - base styles override */
.custom-node.shape-hexagon {
  border-radius: 0;
  background: none;
}

/* ✅ Correct - overrides base styles */
.custom-node.shape-hexagon {
  border-radius: 0 !important;
  background: none !important;
  border: none !important;
}
```

### **3. Handle Connection Issues**
**Problem**: Nodes can't connect to each other.
**Solution**: Ensure handles have proper `type` and `position`.

```vue
<!-- ✅ Correct handle setup -->
<Handle 
  type="target" 
  :position="Position.Left"
  :isConnectable="true"
/>
<Handle 
  type="source" 
  :position="Position.Right"
  :isConnectable="true"
/>
```

---

## 🚀 Deployment Checklist

### **Production Readiness**
- [ ] All custom nodes are file-based components (not inline)
- [ ] Node types registered with `markRaw()` wrapper
- [ ] Global styles injected via plugin system
- [ ] CSS variables used for dynamic theming
- [ ] Shape overrides use `!important` declarations
- [ ] Handle connections properly configured
- [ ] Error boundaries implemented for Vue Flow errors
- [ ] Process validation before save/publish

### **Performance Optimization**
- [ ] Large node sets use virtual scrolling
- [ ] Debounced auto-save functionality
- [ ] Optimized re-renders with `computed` properties
- [ ] Proper Vue 3 reactivity patterns
- [ ] Memory leak prevention with proper cleanup

---

## 📚 Key Dependencies

```json
{
  "@vue-flow/core": "^1.x.x",
  "@vue-flow/background": "^1.x.x", 
  "@vue-flow/controls": "^1.x.x",
  "@vue-flow/minimap": "^1.x.x",
  "vue": "^3.x.x",
  "nuxt": "^3.x.x",
  "@pinia/nuxt": "^0.x.x",
  "@formkit/nuxt": "^1.x.x",
  "tailwindcss": "^3.x.x"
}
```

---

## 📖 Reference Links

- **Vue Flow Documentation**: https://vueflow.dev/
- **Vue 3 Composition API**: https://vuejs.org/guide/
- **Nuxt 3**: https://nuxt.com/docs
- **Pinia Store**: https://pinia.vuejs.org/
- **Tailwind CSS**: https://tailwindcss.com/docs

---

**📝 Last Updated**: Current as of the Vue Flow custom nodes migration and shape system implementation.

**🔄 Version**: 1.0 - Comprehensive system documentation

**👥 For New Team Members**: This document contains everything needed to understand and work with the Vue Flow Process Builder system. Start with the "File Structure" section and follow the implementation patterns for any new features.

---

## 🧪 Testing Gateway Decisions

### **Form Field Integration**
To test gateway decisions, add form fields that map to process variables:

```json
// Form component with gateway test field
{
  "type": "checkbox",
  "props": {
    "name": "todoStatus",
    "label": "Test Gateway Decision",
    "help": "Toggle to test gateway paths"
  }
}
```

### **Process Variable Mapping**
Map form fields to process variables for gateway testing:

```json
// Form node output mappings
{
  "outputMappings": [
    { "formField": "todoStatus", "processVariable": "todoStatus" }
  ]
}
```

### **Gateway Testing Scenarios**
1. **"Completed" Path**: Check the test field → `todoStatus = true` → Follow "Completed" path
2. **"Not Completed" Path**: Leave test field unchecked → `todoStatus = false` → Follow "Not Completed" path

### **Workflow Execution**
The workflow execution engine (`pages/workflow/[id].vue`) automatically:
- Evaluates gateway conditions based on current process variables
- Shows visual feedback of which conditions are true/false
- Follows the first matching path
- Falls back to default path if no conditions match