Add Process Builder Documentation and Technical Appendix

- Created comprehensive documentation for the Process Builder, detailing its features, usage, and components.
- Included a user-friendly overview, quick start guide, and best practices for designing workflows.
- Developed a technical appendix outlining the architecture, technology stack, project structure, and component architecture.
- Documented state management and connection handling within the Process Builder for developers.
- Enhanced troubleshooting and error handling sections to assist users in resolving common issues.

doc/PROCESS_BUILDER_DOCUMENTATION.md

@@ -0,0 +1,174 @@
+# Process Builder Documentation
+
+## Overview
+
+The Process Builder is a visual workflow designer that allows you to create, edit, and manage business processes using the BPMN (Business Process Model and Notation) standard. With an intuitive drag-and-drop interface, you can design complex workflows that model your organization's business processes.
+
+## Getting Started
+
+### Accessing the Process Builder
+1. Navigate to `/process-builder` in your browser
+2. You'll see a three-panel interface:
+   - Left: Component Palette
+   - Middle: Process Canvas
+   - Right: Properties Panel
+
+### Quick Start Guide
+1. **Create a New Process**
+   - Click "New Process" in the header
+   - Enter a process name and description
+   - Start adding components
+
+2. **Add Process Elements**
+   - Drag components from the left panel onto the canvas
+   - Components include Start/End events, Tasks, Gateways, etc.
+   - Connect elements by dragging from one node's handle to another
+   - Handles appear when hovering over nodes:
+     - Top handle: Input connection point
+     - Bottom handle: Output connection point
+
+3. **Configure Elements**
+   - Click any element in the canvas to select it
+   - Use the right panel to configure its properties
+   - Changes are previewed in real-time
+
+4. **Save and Deploy**
+   - Click "Save Process" to store your changes
+   - Once ready, you can deploy the process for execution
+
+## Process Components
+
+### Events
+Events represent something that happens during the course of a process:
+
+- **Start Event** (Green Icon)
+  - Indicates where a process begins
+  - Only has output handle (bottom)
+  - Properties: Description, triggers
+
+- **End Event** (Red Icon)
+  - Indicates where a process path ends
+  - Only has input handle (top)
+  - Properties: Description, result types
+
+### Activities
+Activities represent work performed in a process:
+
+- **Task** (Blue Icon)
+  - A simple atomic activity within the process
+  - Has both input and output handles
+  - Properties: Assignee, description
+
+- **Form Task** (Purple Icon)
+  - A task that requires form data
+  - Has both input and output handles
+  - Properties: Form name, description
+
+- **Script Task** (Grey Icon)
+  - Automated task that executes code
+  - Has both input and output handles
+  - Properties: Language, description
+
+### Gateways
+Gateways control flow divergence and convergence:
+
+- **Gateway** (Orange Icon)
+  - Creates alternative paths based on conditions
+  - Has both input and output handles
+  - Properties: Conditions, description
+
+## Working with the Process Canvas
+
+### Navigation
+- **Pan**: Click and drag the canvas background or use middle mouse button
+- **Zoom**: Use mouse wheel or zoom controls in top-right
+- **Reset View**: Use the fit-view button in controls
+
+### Element Manipulation
+- **Select**: Click on an element
+- **Multi-select**: Hold Shift while clicking elements
+- **Move**: Drag selected elements
+- **Delete**: Press Delete key or double-click element
+- **Connect**: Drag from one node's handle to another's
+
+### Keyboard Shortcuts
+- **Delete**: Remove selected elements
+- **Shift**: Enable node selection
+- **Control**: Multi-select nodes
+
+### Connection Points
+- **Input Handle**: Located at the top of nodes (except Start)
+- **Output Handle**: Located at the bottom of nodes (except End)
+- **Creating Connections**:
+  1. Hover over a node to see handles
+  2. Click and drag from a handle
+  3. Drop on another node's handle
+  4. Connection automatically styles based on type
+
+## Process Properties
+
+### Basic Settings
+- Process name and description
+- Version information
+- Start conditions
+- Process timeouts
+
+### Variables
+- Process data variables
+- Input and output parameters
+- Data types and validation
+
+### Participants
+- User assignments
+- Role-based assignments
+- Group assignments
+
+## Best Practices
+
+### Process Design
+1. Start with a Start event and end with End event(s)
+2. Use clear, descriptive labels for all elements
+3. Connect nodes in a logical flow
+4. Use gateways to manage decision points
+5. Keep the process layout organized and clear
+
+### Flow Control
+1. Ensure all paths lead to an End event
+2. Validate connections make logical sense
+3. Use appropriate node types for each step
+4. Consider the process flow direction (typically top to bottom)
+
+### Visual Organization
+1. Maintain consistent spacing between nodes
+2. Align nodes for better readability
+3. Use the auto-arrange feature when available
+4. Keep related elements grouped together
+
+## Troubleshooting
+
+### Common Issues
+1. **Can't Create Connection**
+   - Verify you're dragging from a handle
+   - Check that source and target are compatible
+   - Ensure you're connecting to a handle, not the node body
+
+2. **Node Won't Delete**
+   - Make sure the node is selected
+   - Try using the Delete key
+   - Alternative: double-click the node
+
+3. **Connection Looks Wrong**
+   - Try repositioning nodes for better flow
+   - Check that connections are made to correct handles
+   - Consider using different connection types
+
+### Getting Help
+- Use the control panel hints in top-right
+- Review this documentation
+- Contact support team for additional assistance
+
+---
+
+For technical details about implementation and integration, please refer to the [Process Builder Technical Documentation](PROCESS_BUILDER_TECHNICAL_APPENDIX.md).
+
+Last updated: May 15, 2024 

doc/PROCESS_BUILDER_TECHNICAL_APPENDIX.md

@@ -0,0 +1,344 @@
+# Process Builder Technical Appendix
+
+This document provides technical implementation details for developers working with the Process Builder system.
+
+> For user documentation and usage guidelines, please refer to [Process Builder Documentation](PROCESS_BUILDER_DOCUMENTATION.md)
+
+## Architecture Overview
+
+### Technology Stack
+- **Frontend Framework**: Nuxt 3 / Vue 3
+- **State Management**: Pinia
+- **Flow Visualization**: Vue Flow
+- **UI Framework**: Tailwind CSS
+- **Icons**: Material Design Icons
+- **Validation**: Zod
+
+### Key Dependencies
+```json
+{
+  "@vue-flow/core": "^1.42.5",
+  "@vue-flow/background": "^1.3.2",
+  "@vue-flow/controls": "^1.1.2",
+  "@vue-flow/minimap": "^1.5.3",
+  "@pinia/nuxt": "^0.4.11",
+  "uuid": "^10.0.0",
+  "zod": "^3.22.2"
+}
+```
+
+## Project Structure
+
+```
+pages/
+├── process-builder/
+│   ├── index.vue           # Main builder interface
+│   └── manage.vue          # Process management
+components/
+├── process-flow/
+│   ├── ProcessFlowCanvas.vue     # Flow canvas
+│   └── ProcessFlowNodes.js       # Custom node types
+stores/
+└── processBuilder.js       # State management
+composables/
+└── useProcessValidation.js # Process validation
+types/
+└── process-builder.d.ts    # TypeScript definitions
+```
+
+## Component Architecture
+
+### Core Components
+
+1. **ProcessFlowCanvas.vue**
+```vue
+<script setup>
+import { ref, onMounted } from 'vue';
+import { VueFlow, useVueFlow, Panel } from '@vue-flow/core';
+import { Background } from '@vue-flow/background';
+import { Controls } from '@vue-flow/controls';
+import { MiniMap } from '@vue-flow/minimap';
+import { nodeTypes } from './ProcessFlowNodes';
+
+// Initialize Vue Flow with options
+const {
+  nodes,
+  edges,
+  addNodes,
+  addEdges,
+  removeNodes,
+  removeEdges,
+  onNodesChange,
+  onEdgesChange,
+  onConnect,
+  fitView,
+  project
+} = useVueFlow({
+  defaultEdgeOptions: {
+    animated: true,
+    type: 'smoothstep'
+  },
+  deleteKeyCode: 'Delete',
+  selectionKeyCode: 'Shift',
+  multiSelectionKeyCode: 'Control',
+  connectionMode: 'loose'
+});
+
+// Flow configuration
+const flowOptions = {
+  defaultZoom: 1,
+  minZoom: 0.2,
+  maxZoom: 4,
+  fitViewOnInit: true,
+  snapToGrid: true,
+  snapGrid: [15, 15],
+  connectionMode: 'loose',
+  elementsSelectable: true,
+  nodesDraggable: true,
+  nodesConnectable: true
+};
+
+// Event handlers for node/edge changes
+onNodesChange((changes) => {
+  emit('nodesChange', changes, nodes.value);
+});
+
+onEdgesChange((changes) => {
+  emit('edgesChange', changes, edges.value);
+});
+
+// Handle new connections
+const handleConnect = (connection) => {
+  if (!connection.source || !connection.target) return;
+  
+  const newEdge = {
+    id: `${connection.source}-${connection.target}`,
+    source: connection.source,
+    target: connection.target,
+    type: 'smoothstep',
+    animated: true
+  };
+
+  addEdges([newEdge]);
+};
+</script>
+```
+
+2. **ProcessFlowNodes.js**
+```javascript
+import { h, markRaw } from 'vue';
+import { Handle, Position } from '@vue-flow/core';
+
+// Custom node renderer with handles
+const CustomNode = markRaw({
+  template: `
+    <div :class="['custom-node', 'node-' + type]">
+      <Handle
+        v-if="type !== 'start'"
+        type="target"
+        position="top"
+      />
+      
+      <div class="custom-node-header">
+        <div class="custom-node-icon">
+          <slot name="icon"></slot>
+        </div>
+        <div class="custom-node-title">{{ label }}</div>
+      </div>
+      
+      <div class="custom-node-content">
+        <slot></slot>
+      </div>
+
+      <Handle
+        v-if="type !== 'end'"
+        type="source"
+        position="bottom"
+      />
+    </div>
+  `,
+  props: ['id', 'type', 'label', 'data'],
+  components: { Handle }
+});
+
+// Node type definitions
+export const nodeTypes = markRaw({
+  task: TaskNode,
+  start: StartNode,
+  end: EndNode,
+  gateway: GatewayNode,
+  form: FormNode,
+  script: ScriptNode
+});
+```
+
+## State Management
+
+### Process Builder Store
+```typescript
+export const useProcessBuilderStore = defineStore('processBuilder', {
+  state: () => ({
+    processes: [],
+    currentProcess: null,
+    selectedNodeId: null,
+    selectedEdgeId: null,
+    unsavedChanges: false
+  }),
+  
+  actions: {
+    createProcess(name, description) {
+      const process = {
+        id: uuidv4(),
+        name,
+        description,
+        nodes: [],
+        edges: [],
+        createdAt: new Date().toISOString()
+      };
+      this.processes.push(process);
+      this.currentProcess = process;
+    },
+    
+    updateNode(nodeData) {
+      if (!this.currentProcess || !nodeData.id) return;
+      
+      const nodeIndex = this.currentProcess.nodes.findIndex(
+        node => node.id === nodeData.id
+      );
+      
+      if (nodeIndex > -1) {
+        this.currentProcess.nodes[nodeIndex] = {
+          ...this.currentProcess.nodes[nodeIndex],
+          ...nodeData
+        };
+        this.unsavedChanges = true;
+      }
+    },
+    
+    // Additional actions...
+  }
+});
+```
+
+## Node Types and Styles
+
+### Node Configuration
+```typescript
+interface NodeConfig {
+  type: 'start' | 'end' | 'task' | 'form' | 'script' | 'gateway';
+  label: string;
+  icon: string;
+  iconColor: string;
+  data: {
+    description?: string;
+    assignee?: string;
+    formName?: string;
+    language?: string;
+    conditions?: string[];
+  };
+}
+
+const nodeConfigs: Record<string, NodeConfig> = {
+  start: {
+    type: 'start',
+    label: 'Start',
+    icon: 'play_circle_filled',
+    iconColor: 'text-green-500',
+    data: { description: 'Process starts here' }
+  },
+  task: {
+    type: 'task',
+    label: 'Task',
+    icon: 'assignment',
+    iconColor: 'text-blue-500',
+    data: { description: 'Task node', assignee: '' }
+  },
+  // Additional node configurations...
+};
+```
+
+## Connection Handling
+
+### Connection Logic
+```typescript
+// Connection validation
+function validateConnection(connection: Connection): boolean {
+  if (!connection.source || !connection.target) return false;
+  if (connection.source === connection.target) return false;
+  
+  const sourceNode = nodes.value.find(n => n.id === connection.source);
+  const targetNode = nodes.value.find(n => n.id === connection.target);
+  
+  if (!sourceNode || !targetNode) return false;
+  
+  // Prevent connecting to start node's input or from end node's output
+  if (targetNode.type === 'start') return false;
+  if (sourceNode.type === 'end') return false;
+  
+  return true;
+}
+
+// Create new connection
+function createConnection(connection: Connection): Edge {
+  return {
+    id: `${connection.source}-${connection.target}`,
+    source: connection.source,
+    target: connection.target,
+    type: 'smoothstep',
+    animated: true,
+    style: { stroke: '#555' }
+  };
+}
+```
+
+## Event Handling
+
+### Node Events
+```typescript
+// Node selection
+function onNodeClick(node: Node): void {
+  selectedNode.value = node;
+  emit('nodeSelected', node);
+}
+
+// Node deletion
+function onNodeDelete(nodes: Node[]): void {
+  removeNodes(nodes);
+  emit('nodesChange', nodes.value);
+}
+
+// Node dragging
+function onNodeDragStop(node: Node): void {
+  updateNodePosition(node);
+  emit('nodePositionChange', node);
+}
+```
+
+## Development Guidelines
+
+### Best Practices
+1. Use Vue Flow's built-in features instead of custom implementations
+2. Handle all node/edge updates through the store
+3. Maintain proper typings for all components
+4. Follow Vue 3 Composition API patterns
+5. Implement proper validation for all process changes
+
+### Performance Considerations
+1. Use `markRaw` for node components
+2. Minimize reactive wrapping of node data
+3. Use proper key bindings for lists
+4. Implement efficient node filtering
+5. Optimize canvas rendering
+
+### Error Handling
+1. Validate all connections before creation
+2. Handle edge cases in node operations
+3. Provide meaningful error messages
+4. Implement proper error boundaries
+5. Log errors appropriately
+
+---
+
+For user documentation and usage guidelines, please refer to [Process Builder Documentation](PROCESS_BUILDER_DOCUMENTATION.md).
+
+Last updated: May 15, 2024