diff --git a/doc/PROCESS_BUILDER_DOCUMENTATION.md b/doc/PROCESS_BUILDER_DOCUMENTATION.md new file mode 100644 index 0000000..52d9785 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/doc/PROCESS_BUILDER_TECHNICAL_APPENDIX.md b/doc/PROCESS_BUILDER_TECHNICAL_APPENDIX.md new file mode 100644 index 0000000..407e6cf --- /dev/null +++ b/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 + +``` + +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: ` +
+ + +
+
+ +
+
{{ label }}
+
+ +
+ +
+ + +
+ `, + 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 = { + 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 \ No newline at end of file