corrad-bp/CLAUDE.md

CLAUDE.md

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

Development Server

yarn dev              # Start development server
yarn build            # Build for production
yarn build:new        # Build with pre/post-build scripts
yarn preview          # Preview production build
yarn generate         # Generate static site

Database Operations

yarn prisma           # Pull DB schema, generate client, and start dev server
npx prisma generate   # Generate Prisma client only
npx prisma db pull    # Pull database schema
npx prisma studio     # Open Prisma Studio for database management

Code Quality

npx eslint .          # Run ESLint
npx prettier --write . # Format code with Prettier

Architecture Overview

Technology Stack

• Framework: Nuxt 3 with Vue 3 Composition API
• Database: MySQL with Prisma ORM
• State Management: Pinia stores
• UI Framework: Tailwind CSS + Custom Rose UI components
• Forms: FormKit with custom extensions
• Process Visualization: Vue Flow for BPMN diagrams
• Authentication: JWT-based with custom middleware

Core System Components

This is a Business Process Management (BPM) platform with two primary modules:

1. Process Builder (/process-builder/)

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.

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

Primary Stores:

• processBuilder.js: Process design, node management, auto-save, history tracking
• formBuilder.js: Form components, validation, custom scripts, preview data
• variableStore.js: Global process variables and data flow management
• user.js: Authentication and user session management

Store Patterns:

• All stores use Pinia with persistence
• Reactive state updates trigger UI changes automatically
• Centralized error handling and loading states
• Auto-save functionality prevents data loss

Database Schema (Prisma)

Core Entities:

• 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.

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 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:

• formComponents.json: Complete form structure for Malaysian Asnaf registration system
• processDefinition.json: BPMN process flow definitions with nodes and edges
• processVariables.json: 100+ process variables for data management
• customScript.js: Form conditional logic and field visibility rules

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:

• Use ref() for primitive reactive data
• Use shallowRef() for large objects (like Vue Flow nodes) to avoid deep reactivity
• Implement proper cleanup in onUnmounted() for timers and event listeners
• Use watch() for complex reactive logic, computed() for derived state

State Management Patterns:

• Store actions handle all business logic and API calls
• Components focus on presentation and user interaction
• Use store getters for computed values across components
• Implement optimistic updates with error rollback

Form Builder Patterns:

• FormKit schema generation from component configurations
• Conditional logic engine evaluates field visibility in real-time
• JavaScript API provides hooks for custom calculations and validations
• Custom script execution sandbox for security

Process Builder Patterns:

• 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

Authentication:

• JWT tokens with refresh mechanism
• Role-based access control (RBAC) through user/role/userrole models
• Route-level middleware protection

Data Security:

• XSS protection disabled for specific API routes (devtool, forms)
• Rate limiting: 200 requests per minute
• Input validation through FormKit and Prisma
• SQL injection protection through Prisma ORM

Script Execution:

• Form custom scripts run in 'safe' mode by default
• Script execution sandbox prevents direct DOM access
• Advanced mode available for power users with additional permissions

Key Implementation Details

Auto-save System:

• Debounced saves every 2 seconds after changes
• Unsaved changes protection with navigation guards
• Visual indicators for save status

Process Execution:

• 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
• Real-time validation and conditional logic
• Preview mode for form testing
• Import/export functionality for form templates

Performance Optimizations:

• Lazy loading for heavy components (modals, editors)
• Virtual scrolling for large lists
• Optimized API calls with loading states
• Bundle splitting for reduced initial load times

Development Tips

Working with Large Files:

• pages/process-builder/index.vue is ~40k tokens - consider code splitting
• Use component lazy loading for modal components
• Implement proper loading states for better UX

Database Changes:

• Always run npx prisma generate after schema changes
• Use migrations for production database updates
• Test with realistic data volumes

Testing Process Flows:

• 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.

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