Enhance CLAUDE.md Documentation for AI Guidance and Process Builder

- Expanded CLAUDE.md to provide detailed AI guidance for developers, including best practices for schema adherence, node/component usage, and form component specifications.
- Added a comprehensive "Getting Started" section with setup instructions and resource references for new contributors.
- Updated the Process Builder section with an overview of available node types and their functionalities, enhancing clarity on process design capabilities.
- Included JSON data structure schemas for process definitions, variables, and custom components to aid in development and integration.
- Improved overall organization and accessibility of documentation to support better understanding of the BPM platform.

CLAUDE.md

@@ -1,6 +1,26 @@
 # CLAUDE.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+## AI Guidance
+- This documentation is for AI memory/context. Use it to answer questions, generate code, and reason about the system.
+- Always follow the schema and field descriptions exactly as written.
+- When in doubt, refer to the code locations provided in this file.
+- Do not invent new fields, types, or patterns unless explicitly documented here.
+- If a field or pattern is ambiguous, prefer the most common usage as shown in the codebase.
+- For process definitions, ensure there is exactly one start and one end node.
+- For form components, only use 'options' for select/radio/checkbox types.
+- If you encounter a new node/component type, check `/components/` for its implementation.
+- Avoid anti-patterns: do not use fields in the wrong context (e.g., 'options' in a text field), do not omit required fields, and do not mix node types inappropriately.
+- If unsure, ask for clarification or check the referenced code files.
+
+## Getting Started
+- Clone the repo and run `yarn install` to install dependencies.
+- Start the dev server with `yarn dev`.
+- For database setup, see the Database Operations section below.
+- Explore `/pages/` for main app entry points.
+- See `/docs/json/` for sample process and form definitions.
+- For custom components, see `/components/`.
+- For API endpoints, see `/server/api/`.
+- For contributing, follow project conventions and see comments in code.
 
 ## Common Development Commands
 
@@ -43,13 +63,41 @@ npx prettier --write . # Format code with Prettier
 This is a **Business Process Management (BPM) platform** with two primary modules:
 
 #### 1. Process Builder (`/process-builder/`)
-Visual BPMN workflow designer with three main pages:
+Professional BPMN-compliant workflow designer with comprehensive node types and sophisticated integration capabilities:
+
+**Main Pages:**
 - **index.vue**: Main process designer (drag-and-drop BPMN editor, ~40k tokens)
 - **manage.vue**: Process management dashboard with metrics and CRUD operations
 - **analytics/[id].vue**: Process analytics and journey visualization
 
+**Available Node Types:**
+- **Start/End Points**: Define process boundaries; start or finish a process.
+- **Form Tasks**: User input forms; integrate with form builder.
+- **API Calls**: Call external/internal APIs; supports authentication and error handling.
+- **Script Tasks**: Run JavaScript code; map input/output variables.
+- **Business Rules**: Evaluate conditions and set variables; supports AND/OR logic.
+- **Gateways**: Decision points; branch process flow based on conditions.
+- **Notifications**: Send messages (email, SMS, in-app) to users/roles.
+- **HTML Content**: Display custom HTML/CSS/JS content in the process.
+- **Sub Processes**: Run nested processes; supports variable mapping.
+- **Design Elements**: Visual aids (swimlanes, shapes, text annotations).
+
+> Node type implementations: `/components/process-flow/ProcessFlowNodes.js` and related Vue components.
+
 #### 2. Form Builder (`/form-builder/`)
-Dynamic form creator with conditional logic, validation, and JavaScript API integration
+Dynamic form creator with conditional logic, validation, and JavaScript API integration.
+
+**Form Component Types:**
+- **Text**: Single-line input.
+- **Select**: Dropdown selection.
+- **Radio**: Single-choice radio buttons.
+- **Checkbox**: Multi-choice checkboxes.
+- **Date**: Date picker.
+- **Repeating Group**: Dynamic list of grouped fields.
+- **Heading**: Section titles.
+- **Static/Display**: Read-only or info fields.
+
+> See `/components/FormBuilderComponents.vue` and `/components/formkit/` for implementations.
 
 ### State Management Architecture
 
@@ -68,48 +116,55 @@ Dynamic form creator with conditional logic, validation, and JavaScript API inte
 ### Database Schema (Prisma)
 
 **Core Entities:**
-- `process`: BPMN process definitions with JSON schema, versioning, and templates
+- **process**: BPMN process definitions (JSON schema, versioning, templates).
-- `form`: Dynamic form configurations with custom scripts and validation
+- **form**: Dynamic form configurations (fields, scripts, validation).
-- `caseInstance`: Process execution instances with status tracking
+- **caseInstance**: Tracks process execution instances and status.
-- `task`: User tasks within process cases
+- **task**: User tasks within process cases.
-- `user/role/userrole`: Authentication and RBAC system
+- **user/role/userrole**: Authentication and RBAC system.
+
+> See `/prisma/schema.prisma` for schema details.
 
 **Key Relationships:**
-- Forms can be embedded in process tasks
+- Forms can be embedded in process tasks.
-- Process variables flow between forms and process nodes
+- Process variables flow between forms and process nodes.
-- Complete audit trail through `processHistory` and `formHistory`
+- Complete audit trail through `processHistory` and `formHistory`.
-- Case timeline tracking for process execution monitoring
+- Case timeline tracking for process execution monitoring.
 
-### Component Architecture
+### RBAC & Permissions System
-
+- **Roles**: Define user access levels (e.g., admin, manager, user).
-**Process Flow Components (`/components/process-flow/`):**
+- **Permissions**: Assigned to roles; control access to features and data.
-- `ProcessFlowCanvas.vue`: Main BPMN editor using Vue Flow
+- **UserRole**: Maps users to roles.
-- `ProcessBuilderComponents.vue`: Draggable component palette
+- **Where to find**: `/prisma/schema.prisma` (models), `/server/api/role/` (API), `/stores/user.js` (frontend usage).
-- Node Configuration Modals: Specialized modals for each BPMN node type
-- `VariableManager.vue`: Process variable management interface
-
-**Form Components (`/components/formkit/`):**
-- Custom FormKit inputs with enhanced functionality
-- Conditional logic engine for dynamic field visibility
-- JavaScript API integration for real-time calculations
-
-**Rose UI Components (`/components/rs-*/`):**
-- Custom design system components (buttons, modals, cards, etc.)
-- Consistent styling and behavior across the application
 
 ### API Architecture (`/server/api/`)
 
 **RESTful Structure:**
-- `/api/forms/`: CRUD operations for forms with history tracking
+- `/api/forms/`: CRUD for forms, with history.
-- `/api/process/`: Process management, publishing, execution
+- `/api/process/`: Process management, publishing, execution.
-- `/api/tasks/`: Task assignment and completion
+- `/api/tasks/`: Task assignment and completion.
-- `/api/devtool/`: Development utilities (ORM, code editor, etc.)
+- `/api/devtool/`: Dev utilities (ORM, code editor, etc).
+
+**API Request/Response:**
+- Most endpoints accept/return JSON.
+- Auth via JWT in headers.
+- For request/response shapes, see handler files in `/server/api/` or use browser dev tools.
+- For OpenAPI/Swagger docs, see project root if available.
 
 **Special Endpoints:**
 - Form field extraction: `/api/forms/[formId]/fields.get.js`
 - Process analytics: `/api/process/dashboard/summary.get.js`
 - Version management: `/api/forms/[id]/history.get.js`
 
+### Process Execution Flow
+1. User starts a process (via UI or API).
+2. System creates a case instance and assigns initial tasks.
+3. User(s) complete form tasks, triggering API/script/business rule nodes as defined.
+4. Variables are updated and routed through gateways/conditions.
+5. Notifications and HTML content nodes are processed as needed.
+6. Process continues until end node is reached; case is closed.
+
+> For execution logic, see `/server/api/process/` and `/components/process-flow/`.
+
 ### Configuration Files (`/docs/json/`)
 
 **Critical System Configurations:**
@@ -120,6 +175,80 @@ Dynamic form creator with conditional logic, validation, and JavaScript API inte
 
 These JSON files define a production Malaysian welfare application system with complex business rules.
 
+### JSON Data Structure Schemas
+
+#### Process Definition Schema
+- **nodes**: Array<Node> (required) — List of all process steps.
+  - Node:
+    - id: String (required) — Unique node identifier.
+    - type: String (required) — Node type (e.g., 'form', 'api', 'start', etc.).
+    - label: String (optional) — Display label for the node.
+    - position: { x: Number, y: Number } (required) — Canvas position.
+    - data: Object — Type-specific config (see below).
+      - For 'form': formId, formName, assignedRoles, etc.
+      - For 'api': apiUrl, apiMethod, headers, etc.
+      - For 'gateway': conditions, defaultPath, etc.
+- **edges**: Array<Edge> (required) — Connections between nodes.
+  - Edge:
+    - id: String (required) — Unique edge identifier.
+    - type: String (required) — Edge type (usually 'custom').
+    - source: String (required) — Source node id.
+    - target: String (required) — Target node id.
+    - sourceHandle: String (optional) — Source connection handle.
+    - targetHandle: String (optional) — Target connection handle.
+    - animated: Boolean (optional) — Animate edge.
+    - label: String (optional) — Edge label.
+    - data: Object (optional) — Extra edge metadata.
+- **viewport**: { x: Number, y: Number, zoom: Number } (required) — Canvas viewport settings.
+
+> For real-world examples, see `/docs/json/process-builder/` and `/components/process-flow/`.
+
+#### Process Variable Schema
+- **variableName**: Object (key is variable name)
+  - type: String (required, e.g. string, number, boolean, object, array) — Data type.
+  - value: Any (optional) — Initial value.
+  - description: String (optional) — Human-readable description.
+  - scope: String (optional, e.g. 'global') — Variable scope.
+  - name: String (optional, usually matches the key).
+
+#### Form Builder Custom Component Schema
+- **type**: String (required) — Component type (e.g., 'text', 'select', 'repeating-group').
+- **props**: Object (required) — Component properties.
+  - name: String (required) — Field name (unique).
+  - label: String (required) — Field label.
+  - type: String (required) — Should match component type.
+  - placeholder: String (optional) — Placeholder text.
+  - validation: String (optional) — Validation rules (e.g., 'required').
+  - help: String (optional) — Helper text.
+  - width: String (optional) — Field width (e.g., '100%').
+  - gridColumn: String (optional) — Grid layout column span.
+  - options: Array<{ label: String, value: Any }> (optional, for select/radio/checkbox) — Choices for selection fields.
+  - conditionalLogic: { action: String, enabled: Boolean, operator: String, conditions: Array } (optional) — Show/hide logic.
+  - fields: Array<Component> (optional, for repeating-group) — Nested fields.
+  - maxItems: Number (optional, for repeating-group) — Max items allowed.
+  - minItems: Number (optional, for repeating-group) — Min items required.
+  - buttonText: String (optional, for repeating-group) — Add button label.
+  - removeText: String (optional, for repeating-group) — Remove button label.
+  - level: Number (optional, for heading components) — Heading level.
+  - value: Any (optional, for static fields) — Static value.
+
+> Some fields are required only for certain types (e.g., 'options' for select/radio, 'fields' for repeating-group).
+> For more, see `/docs/json/form/` and `/components/FormBuilder*`.
+
+#### Custom Script Schema
+- JavaScript using these helpers (in form script context):
+  - this.hideField(fieldName) — Hide a field.
+  - this.showField(fieldName) — Show a field.
+  - this.onFieldChange(fieldName, callback) — Run callback on field change.
+  - getField(fieldName) — Get field value.
+  - hideField(fieldName) — (Global) Hide a field.
+  - showField(fieldName) — (Global) Show a field.
+  - onFieldChange(fieldName, callback) — (Global) Field change handler.
+- Scripts run in the form context; `this` refers to the script engine. Global helpers are also available.
+- Use for field visibility, conditional logic, and dynamic form behavior.
+
+> For script examples, see `/docs/json/form/customScript.js` and `/components/FormScriptEngine.vue`.
+
 ### Development Patterns
 
 **Vue 3 Composition API Usage:**
@@ -141,10 +270,21 @@ These JSON files define a production Malaysian welfare application system with c
 - Custom script execution sandbox for security
 
 **Process Builder Patterns:**
-- Vue Flow integration for professional BPMN rendering
+- Vue Flow integration for professional BPMN rendering with Vue 3 Composition API
-- Node configuration through specialized modal components
+- Node configuration through specialized modal components for each node type
-- Auto-save with debouncing to prevent data loss
+- Smart connection system with 4-directional handles and type validation
-- History tracking for undo/redo functionality
+- Auto-save with debouncing to prevent data loss (2-second intervals)
+- History tracking for undo/redo functionality with change descriptions
+- Real-time variable usage tracking and dependency analysis
+- Drag-and-drop component palette with visual feedback
+- Mobile-responsive design with collapsible panels and touch support
+
+**Process-Form Integration Patterns:**
+- Bidirectional data flow: Process variables ↔ Form fields
+- Dynamic form behavior based on process state and variables
+- Shared variable system with type validation and scope management
+- Real-time synchronization between process nodes and form configurations
+- Form field mapping in process tasks with input/output variable assignment
 
 ### Security Considerations
 
@@ -172,10 +312,14 @@ These JSON files define a production Malaysian welfare application system with c
 - Visual indicators for save status
 
 **Process Execution:**
-- BPMN-compliant process engine
+- BPMN-compliant process engine with standards-based execution
-- Task assignment and routing based on process definition
+- Task assignment and routing based on process definition and business rules
-- Variable management throughout process lifecycle
+- Variable management throughout process lifecycle with type safety
-- Integration points for external APIs and services
+- Integration points for external APIs and services with authentication
+- Case instance tracking with complete audit trail
+- Dynamic user/role assignment with conditional logic
+- Decision logic with complex branching (AND/OR condition combinations)
+- Sub-process execution with variable inheritance and mapping
 
 **Form System:**
 - Dynamic component rendering from JSON schema
@@ -202,13 +346,48 @@ These JSON files define a production Malaysian welfare application system with c
 - Test with realistic data volumes
 
 **Testing Process Flows:**
-- Use the process management dashboard for testing
+- Use the process management dashboard for testing and monitoring
-- Create test cases in `/execution/` interface
+- Create test cases in `/execution/` interface with realistic data
-- Monitor variables through the Variable Manager
+- Monitor variables through the Variable Manager with real-time updates
+- Test node configurations through specialized modal interfaces
+- Validate API integrations with authentication and error handling
+- Test conditional logic and gateway decision paths
+- Verify form-process integration with variable mapping
+- Use process analytics for performance monitoring and optimization
 
 **Custom Scripts:**
 - Test in 'safe' mode first before enabling 'advanced' mode
 - Use the JavaScript API documentation for available functions
 - Implement proper error handling for custom scripts
 
-This codebase represents a sophisticated, production-ready BPM platform with comprehensive process design, form building, and execution capabilities.
+This codebase represents a sophisticated, production-ready BPM platform with comprehensive process design, form building, and execution capabilities.
+
+### Process Builder Node Architecture Details
+
+**Node Connection System:**
+- **Handle Types**: 4-directional connection points (top, bottom, left, right)
+- **Connection Validation**: Type-safe connections with business rule enforcement
+- **Edge Management**: Interactive edges with labels, conditions, and repositioning
+- **Smart Routing**: Automatic handle assignment based on node type and flow direction
+
+**Variable System Integration:**
+- **Variable Types**: String, Integer, Decimal, Boolean, Date, DateTime, Object
+- **Scoping**: Global process-level variables with inheritance to sub-processes
+- **Usage Tracking**: Real-time analysis of where variables are used across nodes
+- **Type Validation**: Constraint enforcement and automatic type conversion
+- **Dependency Analysis**: Visual indication of variable dependencies between nodes
+
+**Advanced Process Features:**
+- **Template System**: Reusable process templates with variable mapping
+- **Version Control**: Process versioning with rollback capability and change tracking
+- **Export/Import**: Process definition portability with JSON schema validation
+- **Process Analytics**: Execution metrics, performance tracking, and bottleneck analysis
+- **Integration Capabilities**: RESTful API calls, database operations, webhook support
+- **Notification System**: Multi-channel messaging with template support and user preferences
+
+**Mobile and Responsive Design:**
+- **Collapsible Panels**: Left (components) and right (properties) panels with toggle controls
+- **Touch Support**: Mobile-optimized drag-and-drop with gesture recognition
+- **Keyboard Shortcuts**: Ctrl+1/2/3 for panel management, standard undo/redo support
+- **Responsive Canvas**: Adaptive grid layout with zoom and pan capabilities
+- **Device Preview**: Mobile, tablet, and desktop preview modes for form integration testing