@imola-solutions/workflow-builder

Visual workflow builder + runner extracted from BOPC-ITMP. React Flow graph viewer, e-signature dialogs, document attachment picker, per-record workflow panels — all driven by a createWorkflowService({ apiClient, currentUser }) factory that consumers supply with their own persistence.

Install

npm install @imola-solutions/workflow-builder @imola-solutions/ui

Peer deps (already in most React + MUI stacks):

• react >=18, react-dom >=18
• @mui/material >=5, @emotion/react >=11, @emotion/styled >=11
• @xyflow/react >=12, @dagrejs/dagre >=3
• @phosphor-icons/react >=2, dayjs >=1

Minimal usage

import { createWorkflowService, RecordWorkflowPanel } from "@imola-solutions/workflow-builder";
import { createClient } from "@supabase/supabase-js";

const supabase = createClient(URL, ANON_KEY);
const service = createWorkflowService({
  apiClient: supabase,
  currentUser: { id: "…uuid…", name: "Ada" },
});

export function LicensePage({ licenseId, role }) {
  return (
    <RecordWorkflowPanel
      service={service}
      recordType="license_application"
      recordId={licenseId}
      role={role}
      canStart={role === "reviewer"}
    />
  );
}

Read-only graph view

import { WorkflowGraphViewer } from "@imola-solutions/workflow-builder";

<WorkflowGraphViewer
  title="Application progress"
  steps={["Intake", "Review", "Decision"]}
  currentIndex={1}
/>

Compliance & audit

createWorkflowService accepts an onAudit callback. Every mutation and AI call emits a structured event:

const service = createWorkflowService({
  apiClient,
  currentUser,
  onAudit: (event) => {
    // event: { action, actorId, targetType?, targetId?, timestamp, metadata?, success }
    // actions: workflow.start | workflow.advance | workflow.sign
    //   | workflow.attach-document | workflow.evidence-log
    //   | ai.suggest-next-step | ai.explain-step | ai.generate-from-description
    auditLogger.record({ ...event, product: "bopc", surface: "workflow-builder" });
  },
});

Audit callback errors are caught so a logger outage never breaks workflow flow.

AI extensions

const service = createWorkflowService({
  apiClient,
  currentUser,
  aiExtensions: {
    suggestNextStep: async (context) => llm.suggest({ context }),
    explainStep: async (step, context) => llm.explain({ step, context }),
    generateFromDescription: async (desc) => llm.buildGraph(desc),
  },
});

// Feature-detect:
if (service.hasAi.suggestNextStep) {
  const s = await service.suggestNextStep({ instanceId });
}

Unconfigured AI methods throw a helpful error (fail loud, not silent).

Exports

• createWorkflowService — factory returning { fetchDefinitions, fetchInstances, startWorkflow, advanceStep, logEvidence, signStep, attachDocuments, hasAi, ... }
• WorkflowGraphViewer — read-only React Flow graph with current-step highlight
• WorkflowMessagesCard — secure-messages sidecar for a workflow instance
• BoundWorkflowsList — table of instances bound to a record
• RecordWorkflowPanel — "Workflows" panel with Start button + list
• StartWorkflowDialog — shared picker; works on a single record or a multi-selection
• FileWorkflowDocumentsDialog — file collected artifacts at completion
• ESignatureSignDialog — apply an e-signature to an approval step
• ESignatureEvidenceDialog — read-only signing certificate + tamper hashes