From ab5a257283a4cec169e57142defdcf5720a93dc9 Mon Sep 17 00:00:00 2001 From: Md Afiq Iskandar Date: Wed, 16 Jul 2025 07:17:49 +0800 Subject: [PATCH] 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 | 267 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 223 insertions(+), 44 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 13c89d0..2893b92 100644 --- a/CLAUDE.md +++ b/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 -- `form`: Dynamic form configurations with custom scripts and validation -- `caseInstance`: Process execution instances with status tracking -- `task`: User tasks within process cases -- `user/role/userrole`: Authentication and RBAC system +- **process**: BPMN process definitions (JSON schema, versioning, templates). +- **form**: Dynamic form configurations (fields, scripts, validation). +- **caseInstance**: Tracks process execution instances and status. +- **task**: User tasks within process cases. +- **user/role/userrole**: Authentication and RBAC system. + +> See `/prisma/schema.prisma` for schema details. **Key Relationships:** -- Forms can be embedded in process tasks -- Process variables flow between forms and process nodes -- Complete audit trail through `processHistory` and `formHistory` -- Case timeline tracking for process execution monitoring +- Forms can be embedded in process tasks. +- Process variables flow between forms and process nodes. +- Complete audit trail through `processHistory` and `formHistory`. +- Case timeline tracking for process execution monitoring. -### Component Architecture - -**Process Flow Components (`/components/process-flow/`):** -- `ProcessFlowCanvas.vue`: Main BPMN editor using Vue Flow -- `ProcessBuilderComponents.vue`: Draggable component palette -- 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 +### RBAC & Permissions System +- **Roles**: Define user access levels (e.g., admin, manager, user). +- **Permissions**: Assigned to roles; control access to features and data. +- **UserRole**: Maps users to roles. +- **Where to find**: `/prisma/schema.prisma` (models), `/server/api/role/` (API), `/stores/user.js` (frontend usage). ### API Architecture (`/server/api/`) **RESTful Structure:** -- `/api/forms/`: CRUD operations for forms with history tracking -- `/api/process/`: Process management, publishing, execution -- `/api/tasks/`: Task assignment and completion -- `/api/devtool/`: Development utilities (ORM, code editor, etc.) +- `/api/forms/`: CRUD for forms, with history. +- `/api/process/`: Process management, publishing, execution. +- `/api/tasks/`: Task assignment and completion. +- `/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 (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 (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 (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 -- Node configuration through specialized modal components -- Auto-save with debouncing to prevent data loss -- History tracking for undo/redo functionality +- Vue Flow integration for professional BPMN rendering with Vue 3 Composition API +- Node configuration through specialized modal components for each node type +- Smart connection system with 4-directional handles and type validation +- 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 -- Task assignment and routing based on process definition -- Variable management throughout process lifecycle -- Integration points for external APIs and services +- BPMN-compliant process engine with standards-based execution +- Task assignment and routing based on process definition and business rules +- Variable management throughout process lifecycle with type safety +- 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 -- Create test cases in `/execution/` interface -- Monitor variables through the Variable Manager +- Use the process management dashboard for testing and monitoring +- Create test cases in `/execution/` interface with realistic data +- 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. \ No newline at end of file +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 \ No newline at end of file