BPM Module

A lightweight, reusable workflow management system built with React and XState.

Features

• Visual Workflow Designer - Drag-and-drop interface for creating workflow templates
• XState v5 Engine - Robust state machine execution with TypeScript support
• Flexible Storage - Pluggable storage adapters (Prisma, in-memory, custom)
• TypeScript First - Full type safety and excellent IDE support
• Customizable - Theme variables and localization support
• Framework Agnostic - Works with Next.js, Vite, NestJS, Express, and more

Quick Start

Installation

# Install all dependencies
pnpm install

# Build packages
pnpm build

Run Demo

# Start frontend demo
cd apps/demo/frontend
pnpm dev

# In another terminal, start backend demo
cd apps/demo/backend
pnpm dev

Packages

@bpm-module/designer

React components for visual workflow design.

import { WorkflowCanvas } from '@bpm-module/designer';
import '@bpm-module/designer/styles.css';

function MyDesigner() {
  const handleSave = async (definition) => {
    console.log('Saved workflow:', definition);
  };

  return (
    <WorkflowCanvas
      onSave={handleSave}
      locale="en"
      theme={{
        '--bpm-primary': '#722ed1',
      }}
    />
  );
}

@bpm-module/engine

Workflow execution engine with XState.

import { WorkflowEngine, MemoryAdapter } from '@bpm-module/engine';

const engine = new WorkflowEngine({
  storage: new MemoryAdapter(),
  onApprove: async (assetId) => {
    console.log(`Approved: ${assetId}`);
  },
});

// Create workflow instance
const instance = await engine.createInstance({
  templateId: 'template-123',
  assetId: 'asset-456',
});

// Submit approval
await engine.submitApproval({
  instanceId: instance.id,
  nodeId: 'approval-1',
  assigneeId: 'user-789',
  action: 'approved',
});

@bpm-module/storage-prisma

Prisma storage adapter for PostgreSQL.

import { PrismaAdapter } from '@bpm-module/storage-prisma';

const adapter = new PrismaAdapter(prismaClient);

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      Application Layer                       │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │  Designer   │  │   Admin     │  │  Approver   │         │
│  │    UI       │  │   UI        │  │    UI       │         │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘         │
└─────────┼────────────────┼────────────────┼─────────────────┘
          │                │                │
          ▼                ▼                ▼
┌─────────────────────────────────────────────────────────────┐
│                     Package Layer (npm)                      │
│                                                             │
│  @bpm-module/designer          @bpm-module/engine           │
│  ┌──────────────────┐          ┌──────────────────┐         │
│  │ WorkflowCanvas   │◄────────►│ WorkflowEngine   │         │
│  │ NodeComponents   │          │ StateMachine     │         │
│  └──────────────────┘          └────────┬─────────┘         │
│                                         │                   │
│                                         ▼                   │
│                            @bpm-module/storage-*            │
│                            ┌──────────────────┐             │
│                            │ StorageAdapter   │             │
│                            │ ├─ Prisma        │             │
│                            │ ├─ Memory        │             │
│                            │ └─ Custom        │             │
│                            └──────────────────┘             │
└─────────────────────────────────────────────────────────────┘

Customization

Theme Variables

Override CSS variables to customize the appearance:

<WorkflowCanvas
  theme={{
    '--bpm-primary': '#722ed1',      // Primary color
    '--bpm-success': '#52c41a',      // Success color
    '--bpm-warning': '#fa8c16',      // Warning color
    '--bpm-error': '#ff4d4f',        // Error color
    '--bpm-bg': '#ffffff',           // Background
    '--bpm-border': '#d9d9d9',       // Border color
    '--bpm-text': '#1f1f1f',         // Text color
  }}
/>

Localization

Supports English and Chinese:

<WorkflowCanvas locale="en" />  // or "zh"

Custom Storage Adapter

Implement the IStorageAdapter interface:

import { IStorageAdapter } from '@bpm-module/engine';

class MyCustomAdapter implements IStorageAdapter {
  // Implement required methods...
}

Development

# Build all packages
pnpm build

# Run tests
pnpm test

# Lint code
pnpm lint

License

MIT