parcepatacore-workflow-engine-react

Official React Component SDK and Programmatic Client for the Athena KYC Orchestration & State Machine Workflow Engine.

1. Installation

npm install parcepatacore-workflow-engine-react
# or
yarn add parcepatacore-workflow-engine-react
# or
pnpm add parcepatacore-workflow-engine-react

Peer Dependencies

Ensure your host project has react, react-dom, and lucide-react installed:

npm install react react-dom lucide-react

2. Quick Start (React Component Integration)

Wrap your application or workflow view tree with <WorkflowEngineProvider>:

import React from 'react';
import {
  WorkflowEngineProvider,
  WorkflowCatalogWidget,
  TaskInboxWidget,
  LiveSimulatorWidget,
  ExecutionSummaryCard,
} from 'parcepatacore-workflow-engine-react';

export function WorkflowWorkspace() {
  return (
    <WorkflowEngineProvider
      baseUrl="http://localhost:8001/api/v1"
      tenantId="bank-a-uuid"
      theme="light"
    >
      <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: '20px' }}>
        {/* 1. Workflow Pipelines Catalogue */}
        <WorkflowCatalogWidget
          onSelectWorkflow={(wf) => console.log('Selected workflow:', wf.workflow_code)}
          onLaunchWorkflow={(wf) => console.log('Launch requested:', wf.id)}
        />

        {/* 2. Maker-Checker Operational Triage Queue */}
        <TaskInboxWidget
          onClaimTask={(task) => console.log('Task claimed:', task.task_id)}
          onReviewTask={(task) => console.log('Review task:', task.task_id)}
        />
      </div>

      {/* 3. Interactive State Machine Simulator */}
      <div style={{ marginTop: '20px' }}>
        <LiveSimulatorWidget
          initialWorkflow="Retail KYC Pipeline"
          onExecutionComplete={(result) => console.log('Simulation finished:', result)}
        />
      </div>
    </WorkflowEngineProvider>
  );
}

3. Standalone Programmatic Client (Node.js / Non-React)

You can also use the strongly-typed workflowApi directly in backend services, automation scripts, or non-React applications:

import { configureWorkflowApi, workflowApi } from 'parcepatacore-workflow-engine-react';

// Configure endpoint & tenant boundaries
configureWorkflowApi('http://localhost:8001/api/v1', 'bank-a-uuid');

// 1. List active workflows
const { items: workflows } = await workflowApi.listWorkflows({ category: 'INDIVIDUAL_KYC' });
console.log('Workflows:', workflows.map(w => w.name));

// 2. Trigger an execution instance
const execution = await workflowApi.startExecution({
  workflow_code: 'WF-IND-01',
  entity_id: 'CUST-88192',
  entity_name: 'Alexander Petrov',
  priority: 'HIGH',
});
console.log('Execution started:', execution.execution_id);

// 3. Maker-Checker task triage
const { items: pendingTasks } = await workflowApi.listTasks({ role: 'ANALYST_MAKER' });
if (pendingTasks.length > 0) {
  // Claim task
  await workflowApi.claimTask(pendingTasks[0].id, 'Analyst Sarah');

  // Submit Maker decision
  await workflowApi.completeTask(pendingTasks[0].id, {
    decision: 'APPROVED',
    notes: 'Identity confirmed against OFAC SDN and credit bureau checks.',
    actor: 'Analyst Sarah',
  });
}

4. Custom React Hooks

The SDK provides reactive hooks for declarative state management:

useWorkflows(options)

Queries the workflow catalog with search, category filtering, and auto-fetch:

import { useWorkflows } from 'parcepatacore-workflow-engine-react';

function PipelineList() {
  const { workflows, loading, error, refetch } = useWorkflows({ category: 'CORPORATE_KYB' });

  if (loading) return <div>Loading...</div>;
  return (
    <ul>
      {workflows.map(w => (
        <li key={w.id}>{w.name} ({w.sla_hours}h SLA)</li>
      ))}
    </ul>
  );
}

useTaskInbox(options)

Reactive hook for managing Maker-Checker triage queues with optimistic updates:

import { useTaskInbox } from 'parcepatacore-workflow-engine-react';

function TriageInbox() {
  const { tasks, loading, claimTask, completeTask } = useTaskInbox({ role: 'SUPERVISOR_CHECKER' });

  return (
    <div>
      {tasks.map(t => (
        <div key={t.id}>
          <span>{t.entity_name} - {t.task_name}</span>
          <button onClick={() => claimTask(t.id, 'Supervisor John')}>Claim</button>
          <button onClick={() => completeTask(t.id, { decision: 'APPROVED' })}>Approve</button>
        </div>
      ))}
    </div>
  );
}

useWorkflowExecution(executionId, pollIntervalMs)

Tracks an active workflow execution and automatically polls status until complete:

import { useWorkflowExecution } from 'parcepatacore-workflow-engine-react';

function ExecutionTracker({ executionId }: { executionId: string }) {
  const { execution, loading, terminateExecution } = useWorkflowExecution(executionId, 3000);

  return (
    <div>
      <h3>Status: {execution?.status}</h3>
      <p>Current Stage: {execution?.current_stage_name}</p>
      <button onClick={() => terminateExecution('Manual override')}>Terminate</button>
    </div>
  );
}

5. Exported UI Components

Small Atoms

| Component | Props | Description | |---|---|---| | <WorkflowStatusChip /> | isActive: boolean, version?: number, size?: 'sm' \| 'md' | Displays pipeline active state and version tag. | | <ExecutionStatusBadge /> | status: string, size?: 'sm' \| 'md' | Color-coded status badge (RUNNING, WAITING_CHECKER, COMPLETED, ESCALATED, FAILED). | | <SLAPriorityPill /> | priority: string, size?: 'sm' \| 'md' | Priority indicator pill (CRITICAL, HIGH, MEDIUM, LOW). | | <TaskRoleBadge /> | role: string, size?: 'sm' \| 'md' | Role badge for Maker-Checker gates (ANALYST_MAKER, SUPERVISOR_CHECKER, COMPLIANCE_OFFICER). | | <SLAPolicyRow /> | policy: SLAPolicySummary, onToggle?: (p) => void | Compact SLA policy monitor with resolution time and enforcement toggle. |

Medium Widgets

| Component | Props | Description | |---|---|---| | <ExecutionSummaryCard /> | execution: ExecutionSummary, onInspect?: (e) => void | Structured card displaying execution stage progression and metadata. | | <TaskTriageCard /> | task: TaskSummary, onClaim?: (t) => void, onReview?: (t) => void | Operational task card with SLA countdown timer and action buttons. | | <PipelineStageFlowWidget /> | stages: WorkflowStage[], activeStageOrder?: number | Horizontal sequential step progression diagram showing current stage and statuses. | | <WorkflowTriggerCard /> | workflowCode?: string, defaultEntityName?: string, onSuccess?: (res) => void | Interactive form to launch a workflow execution directly from a host view. |

Large / Workspaces

| Component | Props | Description | |---|---|---| | <WorkflowCatalogWidget /> | onSelectWorkflow?: (w) => void, onLaunchWorkflow?: (w) => void, height?: string | Complete searchable, categorizable pipelines catalog with quick launch triggers. | | <TaskInboxWidget /> | onClaimTask?: (t) => void, onReviewTask?: (t) => void, height?: string | Dual-control Four-Eyes maker-checker queue with live role filter tabs and claiming. | | <LiveSimulatorWidget /> | initialWorkflow?: string, customSteps?: SimulationStep[], onExecutionComplete?: (r) => void | Interactive state machine simulator with real-time event bus terminal logs. |

6. Architecture & Folder Structure

workflow-sdk/
├── package.json                   # NPM package definition with dual ESM/CJS exports
├── tsconfig.json                  # Strict TypeScript configuration
├── vite.config.ts                 # Vite Library Mode build configuration
├── README.md                      # Complete developer guide and API documentation
└── src/
    ├── types/
    │   └── index.ts               # Domain interfaces, payloads, and DTO contracts
    ├── services/
    │   └── apiClient.ts           # Scoped Axios client factory and standalone workflowApi
    ├── hooks/
    │   ├── index.ts               # Hooks barrel export
    │   ├── useWorkflows.ts        # Reactive workflows query hook
    │   ├── useTaskInbox.ts        # Reactive maker-checker triage queue hook
    │   ├── useWorkflowExecution.ts# Reactive execution status tracker hook
    │   └── useWorkflowSimulator.ts# Step-by-step state machine runner hook
    ├── components/
    │   ├── WorkflowEngineProvider.tsx # Global SDK context provider
    │   ├── WorkflowStatusChip.tsx     # Small atom chip
    │   ├── ExecutionStatusBadge.tsx   # Small atom badge
    │   ├── SLAPriorityPill.tsx        # Small atom pill
    │   ├── TaskRoleBadge.tsx          # Small atom badge
    │   ├── SLAPolicyRow.tsx           # SLA monitor row
    │   ├── ExecutionSummaryCard.tsx   # Medium summary card
    │   ├── TaskTriageCard.tsx         # Medium triage card
    │   ├── PipelineStageFlowWidget.tsx# Medium flow progression visualizer
    │   ├── WorkflowTriggerCard.tsx    # Medium execution launch card
    │   ├── WorkflowCatalogWidget.tsx  # Large workspace catalogue
    │   ├── TaskInboxWidget.tsx        # Large workspace triage queue
    │   └── LiveSimulatorWidget.tsx    # Large workspace execution simulator
    └── index.ts                   # Root barrel export

License

Proprietary — PerceptaCore / Athena KYC Compliance Platform.