BPMN Process Engine for NestJS

Production-ready BPMN 2.0 Process Execution Engine for NestJS with comprehensive workflow orchestration capabilities. Built with TypeScript, PostgreSQL, Redis, and modern software engineering practices.

✨ Features

Core BPMN 2.0 Support

• ✅ Events: Start, End, Intermediate Events
• ✅ Tasks: User Tasks, Service Tasks, Script Tasks
• ✅ Gateways: Exclusive, Parallel, Inclusive Gateways
• ✅ Flows: Sequence Flows, Message Flows
• ✅ Advanced: Sub-processes, Call Activities

Process Management

• 🚀 Deploy and version BPMN process definitions
• ▶️ Start process instances with variables
• ⏸️ Suspend and resume running processes
• ⏹️ Terminate processes with reason tracking
• 🔍 Query and filter process instances
• 📊 Process execution history and audit trail

Task Management

• 📋 Create and manage user tasks
• 👤 Claim and assign tasks to users/groups
• ✅ Complete tasks with output variables
• 🔄 Delegate tasks to other users
• ⏰ Task priorities and due dates
• 🔍 Advanced task filtering and queries

Integration & Extensibility

• 🔗 REST API service task execution
• 📡 Webhook notifications for process events
• 🔌 Custom JavaScript expressions
• 🌐 External task workers pattern
• 🎯 Event-driven architecture

Enterprise Features

• 📈 Prometheus metrics and monitoring
• 📝 Winston logging with daily rotation
• ❤️ Health checks and readiness probes
• 🔒 Security with Helmet.js
• ⚡ Rate limiting and throttling
• 🐳 Full Docker support
• 📚 Auto-generated Swagger documentation

📦 Installation

npm install @alirezaaminzadeh/nest-bpmn-engine

🚀 Quick Start

1. Setup with Docker (Recommended)

Clone and start with Docker Compose:

# Create .env file
cp .env.example .env

# Edit .env and set your passwords
# DB_PASSWORD=your_secure_password
# REDIS_PASSWORD=your_redis_password

# Start all services
docker-compose up -d

The API will be available at http://localhost (port 80).

2. Manual Setup

# Install dependencies
npm install

# Setup database (PostgreSQL required)
# Create database: bpmn_engine

# Start development server
npm run start:dev

📖 Usage

Deploy a Process Definition

import { DeploymentService } from '@alirezaaminzadeh/nest-bpmn-engine';

const bpmnXml = `<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL">
  <process id="approval-process" name="Approval Process" isExecutable="true">
    <startEvent id="start"/>
    <userTask id="review" name="Review Request"/>
    <endEvent id="end"/>
  </process>
</definitions>`;

const deployment = await deploymentService.deployProcess({
  bpmnXml,
  category: 'approvals',
  deployedBy: 'admin',
});

Start a Process Instance

import { ProcessService } from '@alirezaaminzadeh/nest-bpmn-engine';

const instance = await processService.startProcess('approval-process', {
  businessKey: 'REQ-2024-001',
  variables: {
    requestId: '12345',
    amount: 1000,
    requestor: 'john.doe',
  },
  startedBy: 'system',
});

Manage Tasks

import { TaskService } from '@alirezaaminzadeh/nest-bpmn-engine';

// List tasks assigned to me
const tasks = await taskService.getAllTasks('john.doe', TaskState.ACTIVE);

// Claim a task
await taskService.claimTask(taskId, { assignee: 'john.doe' });

// Complete a task
await taskService.completeTask(taskId, {
  variables: { approved: true, comments: 'Approved' },
});

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Client Applications                       │
└────────────────────────────┬────────────────────────────────┘
                             │
                ┌────────────▼────────────┐
                │   NestJS REST API       │
                │   (Swagger Docs)        │
                └────────────┬────────────┘
                             │
        ┌────────────────────┼────────────────────┐
        │                    │                    │
┌───────▼────────┐  ┌────────▼────────┐  ┌───────▼────────┐
│  BPMN Engine   │  │  Process Mgmt   │  │   Task Mgmt    │
│   Executor     │  │    Service      │  │    Service     │
└───────┬────────┘  └────────┬────────┘  └───────┬────────┘
        │                    │                    │
        └────────────────────┼────────────────────┘
                             │
        ┌────────────────────┼────────────────────┐
        │                    │                    │
┌───────▼────────┐  ┌────────▼────────┐  ┌───────▼────────┐
│   PostgreSQL   │  │      Redis      │  │   Bull Queue   │
│  (Process DB)  │  │   (Cache/Jobs)  │  │  (Async Tasks) │
└────────────────┘  └─────────────────┘  └────────────────┘

📡 API Endpoints

Deployments

• POST /api/v1/deployments - Deploy process definition
• GET /api/v1/deployments - List all deployments
• GET /api/v1/deployments/:id - Get deployment details
• DELETE /api/v1/deployments/:id - Delete deployment

Processes

• POST /api/v1/processes/:key/start - Start process instance
• GET /api/v1/processes/instances - List instances
• GET /api/v1/processes/instances/:id - Get instance details
• POST /api/v1/processes/instances/:id/suspend - Suspend instance
• POST /api/v1/processes/instances/:id/resume - Resume instance
• DELETE /api/v1/processes/instances/:id - Terminate instance

Tasks

• GET /api/v1/tasks - List tasks (with filters)
• GET /api/v1/tasks/:id - Get task details
• POST /api/v1/tasks/:id/claim - Claim task
• POST /api/v1/tasks/:id/complete - Complete task
• POST /api/v1/tasks/:id/delegate - Delegate task

Monitoring

• GET /api/v1/health - Health check
• GET /api/v1/metrics - Prometheus metrics

Full API documentation available at /api/docs when running the server.

🧪 Testing

# Unit tests
npm run test

# E2E tests
npm run test:e2e

# Test coverage
npm run test:cov

🔧 Configuration

Environment variables (see .env.example):

# Application
NODE_ENV=development
PORT=3000
API_PREFIX=api/v1

# Database
DATABASE_HOST=postgres
DATABASE_PORT=5432
DATABASE_NAME=bpmn_engine
DATABASE_USER=bpmn_user
DATABASE_PASSWORD=your_password

# Redis
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=your_redis_password

# Security
JWT_SECRET=your_secret
RATE_LIMIT_TTL=60
RATE_LIMIT_MAX=100

# Logging
LOG_LEVEL=info
LOG_DIR=logs

🐳 Docker Support

Development

docker-compose up -d

Production

docker build -f docker/Dockerfile -t bpmn-engine:latest .
docker run -p 3000:3000 bpmn-engine:latest

📊 Monitoring

Prometheus Metrics

Access metrics at http://localhost:3000/api/v1/metrics

Available metrics:

• bpmn_process_started_total - Total processes started
• bpmn_process_completed_total - Total processes completed
• bpmn_process_failed_total - Total processes failed
• bpmn_active_processes - Currently active processes
• bpmn_task_created_total - Total tasks created
• bpmn_task_completed_total - Total tasks completed
• bpmn_process_duration_seconds - Process execution duration

Logs

Logs are stored in the logs/ directory:

• application-YYYY-MM-DD.log - All logs
• error-YYYY-MM-DD.log - Error logs only

🔒 Security

• ✅ Input validation with class-validator
• ✅ SQL injection prevention (parameterized queries)
• ✅ XSS protection
• ✅ Rate limiting (100 req/min per IP)
• ✅ Helmet.js security headers
• ✅ CORS configuration
• ✅ Environment-based secrets
• ✅ Non-root Docker user

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👤 Author

Alireza Aminzadeh

• Email: [email protected]
• GitHub: @syeedalireza

🙏 Acknowledgments

• Built with NestJS
• BPMN engine powered by bpmn-engine
• Inspired by enterprise workflow orchestration needs

📈 Roadmap

• [ ] BPMN 2.0 Timer Events
• [ ] Message and Signal Events
• [ ] Multi-instance activities
• [ ] DMN (Decision Model and Notation) support
• [ ] Process migration tools
• [ ] Advanced analytics dashboard
• [ ] GraphQL API support

💬 Support

For issues, questions, or contributions:

• 🐛 Report a bug
• 💡 Request a feature
• 📧 Email: [email protected]

Made with ❤️ by Alireza Aminzadeh