npm package: @kodeme-io/next-core-workflow
Description: Workflow, approval flows, and BPM for Next.js applications
Author: ABC Food
Latest version: 0.8.4

# @kodeme-io/next-core-workflow

Workflow, approval flows, and BPM (Business Process Management) for Next.js applications with TypeScript support and real-time updates.

## 🚀 Features

- **🔄 Workflow Engine** - Powerful workflow orchestration and state management
- **✅ Approval Flows** - Multi-step approval processes with role-based assignments
- **🎯 Conditional Logic** - Dynamic routing based on business rules
- **👥 Parallel Processing** - Handle multiple approval paths simultaneously
- **📝 Activity Tracking** - Complete audit trail of all workflow actions
- **⏰ SLA Management** - Track deadlines and escalation rules
- **📊 Analytics** - Workflow performance metrics and reporting
- **🔧 TypeScript Native** - Full type safety and IntelliSense support
- **📱 Real-time Updates** - Live workflow status updates

## 📦 Installation

```bash
npm install @kodeme-io/next-core-workflow
# or
yarn add @kodeme-io/next-core-workflow
# or
pnpm add @kodeme-io/next-core-workflow
```

## 🎯 Quick Start

### Basic Workflow Example

```tsx
'use client'

import {
  WorkflowEngine,
  WorkflowProvider,
  WorkflowViewer,
  ApprovalActions,
  WorkflowDefinition,
  type ApprovalAction
} from '@kodeme-io/next-core-workflow'

const expenseApprovalWorkflow: WorkflowDefinition = {
  id: 'expense-approval',
  name: 'Expense Approval Workflow',
  description: 'Process for approving employee expense reports',
  steps: [
    {
      id: 'submission',
      name: 'Employee Submission',
      type: 'action',
      status: 'completed',
      completedAt: new Date(),
      comments: 'Expense report submitted'
    },
    {
      id: 'manager-approval',
      name: 'Manager Approval',
      type: 'approval',
      assignee: 'manager@example.com',
      status: 'pending'
    },
    {
      id: 'finance-review',
      name: 'Finance Review',
      type: 'review',
      assignee: 'finance@example.com',
      status: 'draft'
    }
  ],
  currentStep: 1,
  status: 'pending',
  createdAt: new Date(),
  updatedAt: new Date(),
  createdBy: 'employee@example.com'
}

export default function ExpenseApprovalPage() {
  const engine = new WorkflowEngine()
  const [workflow, setWorkflow] = useState(expenseApprovalWorkflow)

  const handleApproval = async (action: ApprovalAction) => {
    try {
      const result = await engine.processAction(workflow.id, action)
      if (result.success) {
        setWorkflow(result.workflow)
      }
    } catch (error) {
      console.error('Approval action failed:', error)
    }
  }

  return (
    <WorkflowProvider engine={engine} workflowId={workflow.id}>
      <div className="max-w-4xl mx-auto p-6">
        <h1 className="text-2xl font-bold mb-6">Expense Approval</h1>

        <WorkflowViewer workflow={workflow} />

        <div className="mt-6">
          <ApprovalActions
            step={workflow.steps[workflow.currentStep!]}
            onAction={handleApproval}
            currentUserId="manager@example.com"
          />
        </div>
      </div>
    </WorkflowProvider>
  )
}
```

## 🎭 Real-World Use Cases

### 1. Employee Onboarding Workflow

```tsx
const onboardingWorkflow: WorkflowDefinition = {
  id: 'employee-onboarding',
  name: 'Employee Onboarding',
  description: 'Complete process for onboarding new employees',
  steps: [
    {
      id: 'offer-acceptance',
      name: 'Offer Acceptance',
      type: 'action',
      status: 'completed',
      completedAt: new Date(),
      comments: 'Offer accepted by candidate'
    },
    {
      id: 'hr-paperwork',
      name: 'HR Documentation',
      type: 'approval',
      assignee: 'hr@company.com',
      status: 'pending'
    },
    {
      id: 'it-setup',
      name: 'IT Account Setup',
      type: 'action',
      assignee: 'it@company.com',
      status: 'draft'
    },
    {
      id: 'facility-access',
      name: 'Facility Access',
      type: 'approval',
      assignee: 'facilities@company.com',
      status: 'draft'
    },
    {
      id: 'orientation',
      name: 'Orientation Session',
      type: 'review',
      assignee: 'hr@company.com',
      status: 'draft'
    }
  ],
  currentStep: 1,
  status: 'pending',
  createdAt: new Date(),
  updatedAt: new Date(),
  createdBy: 'recruiting@company.com'
}
```

### 2. Purchase Order Approval

```tsx
const purchaseOrderWorkflow: WorkflowDefinition = {
  id: 'po-approval',
  name: 'Purchase Order Approval',
  description: 'Multi-level approval for purchase orders',
  steps: [
    {
      id: 'po-creation',
      name: 'Purchase Order Creation',
      type: 'action',
      status: 'completed',
      completedAt: new Date(),
      comments: 'PO created for office supplies'
    },
    {
      id: 'manager-approval',
      name: 'Manager Approval',
      type: 'approval',
      assignee: 'manager@company.com',
      status: 'pending'
    },
    {
      id: 'finance-approval',
      name: 'Finance Approval',
      type: 'approval',
      assignee: 'finance@company.com',
      status: 'draft'
    },
    {
      id: 'procurement-review',
      name: 'Procurement Review',
      type: 'review',
      assignee: 'procurement@company.com',
      status: 'draft'
    }
  ],
  currentStep: 1,
  status: 'pending',
  createdAt: new Date(),
  updatedAt: new Date(),
  createdBy: 'requester@company.com'
}

// Enhanced with amount-based conditional routing
const createPurchaseOrderWorkflow = (amount: number): WorkflowDefinition => {
  const steps = [
    {
      id: 'po-creation',
      name: 'Purchase Order Creation',
      type: 'action' as const,
      status: 'completed' as const,
      completedAt: new Date(),
      comments: `PO created for amount: ${amount}`
    }
  ]

  // Add approval levels based on amount
  if (amount > 10000) {
    steps.push({
      id: 'manager-approval',
      name: 'Manager Approval',
      type: 'approval' as const,
      assignee: 'manager@company.com',
      status: 'pending' as const
    })
  }

  if (amount > 50000) {
    steps.push({
      id: 'director-approval',
      name: 'Director Approval',
      type: 'approval' as const,
      assignee: 'director@company.com',
      status: 'draft' as const
    })
  }

  if (amount > 100000) {
    steps.push({
      id: 'executive-approval',
      name: 'Executive Approval',
      type: 'approval' as const,
      assignee: 'ceo@company.com',
      status: 'draft' as const
    })
  }

  steps.push({
    id: 'procurement-review',
    name: 'Procurement Review',
    type: 'review' as const,
    assignee: 'procurement@company.com',
    status: 'draft' as const
  })

  return {
    id: `po-approval-${Date.now()}`,
    name: 'Purchase Order Approval',
    description: `Approval for purchase order of ${amount}`,
    steps,
    currentStep: 1,
    status: 'pending' as const,
    createdAt: new Date(),
    updatedAt: new Date(),
    createdBy: 'requester@company.com'
  }
}
```

### 3. Content Publishing Workflow

```tsx
const contentPublishingWorkflow: WorkflowDefinition = {
  id: 'content-publishing',
  name: 'Content Publishing',
  description: 'Blog post and article publishing workflow',
  steps: [
    {
      id: 'content-creation',
      name: 'Content Creation',
      type: 'action',
      status: 'completed',
      completedAt: new Date(),
      comments: 'Blog post draft completed'
    },
    {
      id: 'editorial-review',
      name: 'Editorial Review',
      type: 'review',
      assignee: 'editor@company.com',
      status: 'pending'
    },
    {
      id: 'legal-review',
      name: 'Legal Review',
      type: 'approval',
      assignee: 'legal@company.com',
      status: 'draft'
    },
    {
      id: 'final-approval',
      name: 'Final Approval',
      type: 'approval',
      assignee: 'content-manager@company.com',
      status: 'draft'
    },
    {
      id: 'publishing',
      name: 'Publishing',
      type: 'action',
      assignee: 'cms@company.com',
      status: 'draft'
    }
  ],
  currentStep: 1,
  status: 'pending',
  createdAt: new Date(),
  updatedAt: new Date(),
  createdBy: 'writer@company.com'
}
```

### 4. IT Service Request Workflow

```tsx
const itServiceRequestWorkflow: WorkflowDefinition = {
  id: 'it-service-request',
  name: 'IT Service Request',
  description: 'IT support and service request workflow',
  steps: [
    {
      id: 'request-submission',
      name: 'Request Submission',
      type: 'action',
      status: 'completed',
      completedAt: new Date(),
      comments: 'Laptop replacement requested'
    },
    {
      id: 'it-triage',
      name: 'IT Triage',
      type: 'review',
      assignee: 'it-support@company.com',
      status: 'pending'
    },
    {
      id: 'approval-required',
      name: 'Manager Approval',
      type: 'approval',
      assignee: 'manager@company.com',
      status: 'draft'
    },
    {
      id: 'procurement',
      name: 'Procurement',
      type: 'action',
      assignee: 'procurement@company.com',
      status: 'draft'
    },
    {
      id: 'delivery-setup',
      name: 'Delivery and Setup',
      type: 'action',
      assignee: 'it-support@company.com',
      status: 'draft'
    }
  ],
  currentStep: 1,
  status: 'pending',
  createdAt: new Date(),
  updatedAt: new Date(),
  createdBy: 'employee@company.com'
}
```

## 📚 Core Concepts

### Workflow Definition Structure

```typescript
interface WorkflowDefinition {
  id: string                    // Unique workflow identifier
  name: string                 // Workflow name
  description?: string          // Optional description
  steps: WorkflowStep[]        // Workflow steps
  currentStep?: number         // Current active step index
  status: WorkflowStatus       // Overall workflow status
  createdAt: Date              // Creation timestamp
  updatedAt: Date              // Last update timestamp
  createdBy: string            // Workflow creator
}
```

### Workflow Step Types

- `action` - User-performed actions (form submissions, uploads)
- `approval` - Single or multi-user approval steps
- `review` - Review steps without explicit approve/reject
- `condition` - Conditional branching logic

### Workflow Status

- `draft` - Workflow is being prepared
- `pending` - Workflow is active and awaiting action
- `approved` - Workflow completed successfully
- `rejected` - Workflow was rejected
- `cancelled` - Workflow was cancelled

### Step Structure

```typescript
interface WorkflowStep {
  id: string                    // Unique step identifier
  name: string                 // Step display name
  type: StepType              // Step type (action, approval, review, condition)
  assignee?: string | string[]  // Assigned user(s) or role(s)
  status: WorkflowStatus      // Step status
  completedAt?: Date          // Completion timestamp
  comments?: string           // Step comments/notes
}
```

## 🎨 Components

### WorkflowEngine

Core engine for managing workflow instances:

```tsx
const engine = new WorkflowEngine({
  notificationHandler: (notification) => {
    // Handle workflow notifications
    console.log('Workflow notification:', notification)
  }
})

// Create new workflow instance
const workflow = engine.createWorkflow({
  definition: workflowDefinition,
  initiator: 'user@example.com',
  context: { amount: 1000, department: 'sales' }
})

// Process workflow actions
const result = await engine.processAction(workflow.id, {
  stepId: 'manager-approval',
  action: 'approve',
  comments: 'Approved within budget',
  userId: 'manager@example.com',
  timestamp: new Date()
})
```

### WorkflowViewer

Visual component for displaying workflow status:

```tsx
<WorkflowViewer
  workflow={workflow}
  showSteps={true}
  showTimeline={true}
  compact={false}
  className="custom-workflow-viewer"
/>
```

### ApprovalActions

Interactive component for handling approvals:

```tsx
<ApprovalActions
  step={currentStep}
  onAction={handleApproval}
  currentUserId="user@example.com"
  showComments={true}
  requiredComments={false}
  className="approval-actions"
/>
```

### WorkflowHistory

Component for displaying workflow activity:

```tsx
<WorkflowHistory
  history={workflowHistory}
  showUser={true}
  showTimestamp={true}
  groupByDate={false}
  className="workflow-history"
/>
```

## 🔄 Advanced Workflow Patterns

### Conditional Workflows

```tsx
const conditionalWorkflow: WorkflowDefinition = {
  id: 'conditional-approval',
  name: 'Conditional Approval Workflow',
  steps: [
    {
      id: 'initial-review',
      name: 'Initial Review',
      type: 'condition',
      status: 'pending'
    },
    {
      id: 'high-value-approval',
      name: 'High Value Approval',
      type: 'approval',
      assignee: 'senior-manager@example.com',
      status: 'draft'
    },
    {
      id: 'standard-approval',
      name: 'Standard Approval',
      type: 'approval',
      assignee: 'manager@example.com',
      status: 'draft'
    }
  ],
  currentStep: 0,
  status: 'pending',
  createdAt: new Date(),
  updatedAt: new Date(),
  createdBy: 'user@example.com'
}

// Usage with context for conditional routing
const workflow = engine.createWorkflow({
  definition: conditionalWorkflow,
  initiator: 'user@example.com',
  context: { amount: 5000, department: 'sales' }
})
```

### Parallel Approvals

```tsx
const parallelWorkflow: WorkflowDefinition = {
  id: 'parallel-approval',
  name: 'Parallel Approval Workflow',
  steps: [
    {
      id: 'submission',
      name: 'Document Submission',
      type: 'action',
      status: 'completed',
      completedAt: new Date()
    },
    {
      id: 'hr-approval',
      name: 'HR Approval',
      type: 'approval',
      assignee: 'hr@example.com',
      status: 'pending'
    },
    {
      id: 'finance-approval',
      name: 'Finance Approval',
      type: 'approval',
      assignee: 'finance@example.com',
      status: 'pending'
    },
    {
      id: 'final-approval',
      name: 'Final Approval',
      type: 'approval',
      assignee: 'director@example.com',
      status: 'draft'
    }
  ],
  currentStep: 1,
  status: 'pending',
  createdAt: new Date(),
  updatedAt: new Date(),
  createdBy: 'user@example.com'
}
```

### Multi-Level Escalation

```tsx
const escalationWorkflow: WorkflowDefinition = {
  id: 'escalation-workflow',
  name: 'Escalation Workflow',
  steps: [
    {
      id: 'level-1',
      name: 'Level 1 Approval',
      type: 'approval',
      assignee: 'manager@example.com',
      status: 'pending'
    },
    {
      id: 'level-2',
      name: 'Level 2 Approval',
      type: 'approval',
      assignee: 'senior-manager@example.com',
      status: 'draft'
    },
    {
      id: 'level-3',
      name: 'Level 3 Approval',
      type: 'approval',
      assignee: 'director@example.com',
      status: 'draft'
    }
  ],
  currentStep: 0,
  status: 'pending',
  createdAt: new Date(),
  updatedAt: new Date(),
  createdBy: 'user@example.com'
}
```

## 🔐 Permissions and Security

### Role-Based Access Control

```tsx
// Check user permissions
const canApprove = engine.canApproveStep(workflowId, stepId, userId)
const canView = engine.canViewWorkflow(workflowId, userId)
const canCancel = engine.canCancelWorkflow(workflowId, userId)

// Role-based assignments
const workflowWithRoles: WorkflowDefinition = {
  id: 'role-based-workflow',
  name: 'Role-Based Workflow',
  steps: [
    {
      id: 'dept-approval',
      name: 'Department Approval',
      type: 'approval',
      assignee: ['role:department-head', 'role:finance-manager'],
      status: 'pending'
    },
    {
      id: 'exec-approval',
      name: 'Executive Approval',
      type: 'approval',
      assignee: 'role:executive',
      status: 'draft'
    }
  ],
  // ... other properties
}
```

### User Assignment Strategies

```tsx
// Dynamic assignment based on business rules
const assignStep = (workflowId: string, stepId: string, context: any) => {
  const assignee = determineAssignee(context)
  return engine.assignStep(workflowId, stepId, assignee)
}

function determineAssignee(context: any): string {
  // Business logic for assignment
  if (context.amount > 10000) {
    return 'senior-manager@example.com'
  } else if (context.department === 'finance') {
    return 'finance-head@example.com'
  } else {
    return 'manager@example.com'
  }
}
```

## 📊 Analytics and Reporting

### Workflow Performance Metrics

```tsx
const analytics = engine.getAnalytics(workflowId)

const metrics = {
  totalWorkflows: analytics.totalCount,
  averageCompletionTime: analytics.averageCompletionTime,
  approvalRate: analytics.approvalRate,
  rejectionRate: analytics.rejectionRate,
  bottleneckSteps: analytics.bottleneckSteps,
  slaCompliance: analytics.slaCompliance
}
```

### Custom Reporting

```tsx
const generateReport = async (dateRange: { start: Date; end: Date }) => {
  const report = await engine.generateReport({
    workflowType: 'expense-approval',
    dateRange,
    metrics: ['completion-time', 'approval-rate', 'sla-compliance'],
    groupBy: 'department'
  })

  return report
}
```

## 🎣 React Hooks

### useWorkflow Hook

The `useWorkflow` hook provides access to workflow context and state management:

```tsx
import { useWorkflow } from '@kodeme-io/next-core-workflow'

function WorkflowComponent() {
  const {
    engine,
    currentWorkflow,
    setCurrentWorkflow,
    processAction,
    refreshWorkflow,
    notifications,
    clearNotifications
  } = useWorkflow()

  const handleApprove = async () => {
    if (!currentWorkflow) return

    const success = await processAction({
      stepId: currentWorkflow.steps[currentWorkflow.currentStep!].id,
      action: 'approve',
      comments: 'Approved',
      userId: 'manager@example.com',
      timestamp: new Date()
    })

    if (success) {
      console.log('Action processed successfully')
    }
  }

  return (
    <div>
      {notifications.map((notif, idx) => (
        <div key={idx} className="notification">
          {notif.message}
        </div>
      ))}
      <button onClick={handleApprove}>Approve</button>
    </div>
  )
}
```

### Custom Hook Example

Create a custom hook for specific workflow types:

```tsx
import { useWorkflow } from '@kodeme-io/next-core-workflow'

function useExpenseWorkflow() {
  const { currentWorkflow, processAction } = useWorkflow()

  const approveExpense = async (comments: string) => {
    if (!currentWorkflow) return false

    return await processAction({
      stepId: currentWorkflow.steps[currentWorkflow.currentStep!].id,
      action: 'approve',
      comments,
      userId: 'manager@example.com',
      timestamp: new Date()
    })
  }

  const rejectExpense = async (reason: string) => {
    if (!currentWorkflow) return false

    return await processAction({
      stepId: currentWorkflow.steps[currentWorkflow.currentStep!].id,
      action: 'reject',
      comments: reason,
      userId: 'manager@example.com',
      timestamp: new Date()
    })
  }

  return {
    workflow: currentWorkflow,
    approveExpense,
    rejectExpense,
    isPending: currentWorkflow?.status === 'pending',
    currentStep: currentWorkflow?.steps[currentWorkflow?.currentStep || 0]
  }
}
```

## 🧪 Testing

The package includes comprehensive test coverage:

```bash
# Run tests
npm test

# Run with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch
```

### Testing Workflow Logic

```tsx
import { WorkflowEngine } from '@kodeme-io/next-core-workflow'

test('workflow approval process', async () => {
  const engine = new WorkflowEngine()
  const workflow = engine.createWorkflow({
    definition: testWorkflow,
    initiator: 'user@example.com'
  })

  // Simulate approval
  const action: ApprovalAction = {
    stepId: 'manager-approval',
    action: 'approve',
    comments: 'Approved',
    userId: 'manager@example.com',
    timestamp: new Date()
  }

  const result = await engine.processAction(workflow.id, action)

  expect(result.success).toBe(true)
  expect(result.workflow.status).toBe('approved')
})
```

## 🔧 API Reference

### Core Classes

```typescript
class WorkflowEngine {
  constructor(options?: WorkflowEngineOptions)

  // Workflow management
  createWorkflow(options: CreateWorkflowOptions): WorkflowDefinition
  getWorkflow(id: string): WorkflowDefinition
  updateWorkflow(id: string, updates: Partial<WorkflowDefinition>): WorkflowDefinition
  deleteWorkflow(id: string): boolean

  // Action processing
  processAction(workflowId: string, action: ApprovalAction): Promise<ProcessActionResult>
  getNextStep(workflowId: string): WorkflowStep | null
  getActiveSteps(workflowId: string): WorkflowStep[]

  // Permissions
  canViewWorkflow(workflowId: string, userId: string): boolean
  canApproveStep(workflowId: string, stepId: string, userId: string): boolean
  canRejectStep(workflowId: string, stepId: string, userId: string): boolean
  canCancelWorkflow(workflowId: string, userId: string): boolean

  // Analytics
  getAnalytics(workflowId?: string): WorkflowAnalytics
  generateReport(options: ReportOptions): Promise<WorkflowReport>
}
```

### Types

```typescript
// Core types
export type WorkflowStatus = 'draft' | 'pending' | 'approved' | 'rejected' | 'cancelled'
export type StepType = 'approval' | 'review' | 'action' | 'condition'
export type ActionType = 'approve' | 'reject' | 'request_changes'

// Action interface
export interface ApprovalAction {
  stepId: string
  action: ActionType
  comments?: string
  userId: string
  timestamp: Date
}

// History interface
export interface WorkflowHistory {
  id: string
  workflowId: string
  actions: ApprovalAction[]
}
```

### Component Props

```typescript
// WorkflowViewer props
export interface WorkflowViewerProps {
  workflow: WorkflowDefinition
  showSteps?: boolean
  showTimeline?: boolean
  compact?: boolean
  className?: string
}

// ApprovalActions props
export interface ApprovalActionsProps {
  step: WorkflowStep
  onAction: (action: ApprovalAction) => void
  currentUserId: string
  showComments?: boolean
  requiredComments?: boolean
  className?: string
}
```

## 🔍 Troubleshooting

### Common Issues

1. **Workflow Not Progressing**
   - Check if the current step is assigned to the correct user
   - Verify the action is valid for the current step type
   - Ensure workflow status allows progression

2. **Permission Errors**
   - Verify user has required permissions for the action
   - Check role assignments and user mappings
   - Ensure workflow is not in a terminal state

3. **Performance Issues**
   - Use workflow indexing for large datasets
   - Implement pagination for workflow history
   - Cache frequently accessed workflow data

### Debug Mode

Enable debug logging:

```tsx
const engine = new WorkflowEngine({
  debug: true,
  logLevel: 'verbose'
})
```

## 🔄 Integration Examples

### Database Integration

```tsx
import { WorkflowEngine } from '@kodeme-io/next-core-workflow'

class DatabaseWorkflowEngine extends WorkflowEngine {
  constructor(private db: Database) {
    super({
      notificationHandler: this.handleDatabaseNotifications.bind(this)
    })
  }

  async createWorkflow(options: CreateWorkflowOptions): Promise<WorkflowDefinition> {
    const workflow = super.createWorkflow(options)

    // Save to database
    await this.db.workflows.create({
      data: {
        id: workflow.id,
        definition: workflow,
        status: workflow.status,
        createdAt: workflow.createdAt,
        createdBy: workflow.createdBy
      }
    })

    return workflow
  }

  async loadWorkflowsFromDatabase(): Promise<void> {
    const workflows = await this.db.workflows.findMany()
    workflows.forEach(dbWorkflow => {
      this.workflows.set(dbWorkflow.id, dbWorkflow.definition)
    })
  }

  private async handleDatabaseNotifications(notification: WorkflowNotification) {
    await this.db.notifications.create({
      data: {
        type: notification.type,
        workflowId: notification.workflowId,
        userId: notification.userId,
        message: notification.message,
        timestamp: notification.timestamp
      }
    })
  }
}
```

### Email/Notification Integration

```tsx
import nodemailer from 'nodemailer'

const workflowEngine = new WorkflowEngine({
  notificationHandler: async (notification) => {
    // Send email notification
    const transporter = nodemailer.createTransporter({
      service: 'gmail',
      auth: {
        user: process.env.EMAIL_USER,
        pass: process.env.EMAIL_PASS
      }
    })

    await transporter.sendMail({
      from: 'workflow@company.com',
      to: notification.userId,
      subject: `Workflow Update: ${notification.message}`,
      text: `Your workflow requires attention: ${notification.message}`
    })

    // Send push notification (if using push service)
    if (notification.type === 'step_assigned') {
      await sendPushNotification(notification.userId, {
        title: 'New Task Assigned',
        body: notification.message,
        data: { workflowId: notification.workflowId }
      })
    }
  }
})
```

### REST API Integration

```tsx
// Next.js API route
import { NextApiRequest, NextApiResponse } from 'next'
import { WorkflowEngine } from '@kodeme-io/next-core-workflow'

const engine = new WorkflowEngine()

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const { method } = req
  const { workflowId, stepId } = req.query

  switch (method) {
    case 'POST':
      // Process approval action
      const { action, comments, userId } = req.body

      const result = await engine.processAction(workflowId as string, {
        stepId: stepId as string,
        action,
        comments,
        userId,
        timestamp: new Date()
      })

      return res.status(200).json(result)

    case 'GET':
      // Get workflow details
      const workflow = engine.getWorkflow(workflowId as string)
      if (!workflow) {
        return res.status(404).json({ error: 'Workflow not found' })
      }

      return res.status(200).json(workflow)

    default:
      res.setHeader('Allow', ['GET', 'POST'])
      return res.status(405).end(`Method ${method} Not Allowed`)
  }
}
```

## 🚀 Performance Tips

1. **Workflow Caching** - Cache workflow definitions and instances
2. **Database Optimization** - Use proper indexing for workflow queries
3. **Real-time Updates** - Implement WebSocket connections for live updates
4. **Batch Operations** - Process multiple workflow actions in batches

```tsx
// Caching example
const workflowCache = new Map<string, WorkflowDefinition>()

const getCachedWorkflow = (id: string): WorkflowDefinition => {
  if (workflowCache.has(id)) {
    return workflowCache.get(id)!
  }

  const workflow = engine.getWorkflow(id)
  workflowCache.set(id, workflow)
  return workflow
}
```

### Database Performance Optimization

```sql
-- Add indexes for better performance
CREATE INDEX idx_workflows_status ON workflows(status);
CREATE INDEX idx_workflows_created_by ON workflows(created_by);
CREATE INDEX idx_workflows_created_at ON workflows(createdAt);
CREATE INDEX idx_workflow_actions_workflow_id ON workflow_actions(workflow_id);
CREATE INDEX idx_workflow_actions_user_id ON workflow_actions(user_id);
```

### Batch Processing Example

```tsx
async function processBatchActions(
  engine: WorkflowEngine,
  actions: Array<{ workflowId: string; action: ApprovalAction }>
): Promise<ProcessActionResult[]> {
  const results = await Promise.allSettled(
    actions.map(({ workflowId, action }) =>
      engine.processAction(workflowId, action)
    )
  )

  return results.map(result =>
    result.status === 'fulfilled'
      ? result.value
      : { success: false, error: result.reason, workflow: {} as WorkflowDefinition }
  )
}
```

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

## 📄 License

MIT License - see LICENSE file for details

## 🔗 Related Packages

- [@kodeme-io/next-core-forms](../forms/README.md) - Form components and validation
- [@kodeme-io/next-core-analytics](../analytics/README.md) - Analytics and reporting
- [@kodeme-io/next-core-ui](../ui/README.md) - UI components

## 📞 Support

- Documentation: [Full documentation](https://docs.abc-food.com/next-core/workflow)
- Issues: [GitHub Issues](https://github.com/abc-food/next-core/issues)
- Discord: [Community Discord](https://discord.gg/abc-food)