# 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
└── [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>
```

---

## 🎨 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
    
    // Custom properties
    customProperties: {}
  }
}
```

---

## 🐛 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.