Workflow Visualizer SDK

Production-ready, embeddable React SDK for visualizing and controlling workflow executions. Designed for non-technical end users to monitor AI-driven pipelines and automated workflows.

Features

• ✅ Next.js App Router Compatible - Works seamlessly with Next.js 14+ App Router
• ✅ TypeScript First - Fully typed API with comprehensive type definitions
• ✅ Timeline Visualization - Clear, vertical step-by-step progress display
• ✅ Interactive Controls - Pause, resume, and re-run workflows
• ✅ Editable Fields - In-place editing of workflow parameters
• ✅ Expandable Steps - View detailed input/output for each step
• ✅ Theming Support - Customize colors to match your brand
• ✅ No Backend Dependencies - Frontend-only, callback-driven architecture

Installation

npm install @automove/workflow-visualizer

Quick Start

"use client";

import { WorkflowVisualizer } from "@automove/workflow-visualizer";
import type { WorkflowRun } from "@automove/workflow-visualizer";

export default function WorkflowPage() {
  const workflowData: WorkflowRun = {
    id: "wf-001",
    status: "running",
    currentStepId: "step-2",
    steps: [
      {
        id: "step-1",
        name: "Data Collection",
        status: "completed",
        input: { source: "api" },
        output: { records: 1500 },
        startedAt: "2026-01-20T10:00:00Z",
        finishedAt: "2026-01-20T10:02:30Z",
      },
      {
        id: "step-2",
        name: "AI Processing",
        status: "running",
        input: { model: "gpt-4" },
        editableFields: ["model"],
        startedAt: "2026-01-20T10:02:35Z",
      },
    ],
  };

  return (
    <WorkflowVisualizer
      workflowRun={workflowData}
      onPause={(runId) => console.log("Pause:", runId)}
      onResume={(runId) => console.log("Resume:", runId)}
      onRerunFrom={(stepId) => console.log("Rerun from:", stepId)}
      onFieldEdit={(stepId, field, value) => 
        console.log("Edit:", { stepId, field, value })
      }
    />
  );
}

Data Model

WorkflowRun

interface WorkflowRun {
  id: string;
  status: "pending" | "running" | "paused" | "completed" | "failed";
  currentStepId: string;
  steps: WorkflowStep[];
}

WorkflowStep

interface WorkflowStep {
  id: string;
  name: string;
  status: "pending" | "running" | "paused" | "completed" | "failed";
  input?: Record<string, any>;
  output?: Record<string, any>;
  editableFields?: string[];  // Fields that users can edit
  startedAt?: string;  // ISO 8601 timestamp
  finishedAt?: string;  // ISO 8601 timestamp
}

Props

WorkflowVisualizerProps

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | workflowRun | WorkflowRun | Yes | - | The workflow data to visualize | | onPause | (runId: string) => void | No | - | Called when user clicks pause | | onResume | (runId: string) => void | No | - | Called when user clicks resume | | onRerunFrom | (stepId: string) => void | No | - | Called when user wants to restart from a step | | onFieldEdit | (stepId, field, value) => void | No | - | Called when user edits a field | | className | string | No | "" | Additional CSS classes | | theme | ThemeOptions | No | - | Custom color theme | | showControls | boolean | No | true | Show pause/resume controls |

ThemeOptions

interface ThemeOptions {
  primaryColor?: string;    // Default: #3b82f6
  successColor?: string;    // Default: #10b981
  errorColor?: string;      // Default: #ef4444
  warningColor?: string;    // Default: #f59e0b
  neutralColor?: string;    // Default: #6b7280
}

Styling

The SDK includes default styles. Import the CSS in your app:

import "@automove/workflow-visualizer/dist/index.css";

For custom styling, you can:

1. Use the className prop to add custom classes
2. Use CSS variables to override theme colors
3. Override specific classes using CSS specificity

CSS Custom Properties

:root {
  --wf-primary: #3b82f6;
  --wf-success: #10b981;
  --wf-error: #ef4444;
  --wf-warning: #f59e0b;
  --wf-neutral: #6b7280;
}

Integration Pattern

This SDK is designed to work with your existing backend:

"use client";

import { useState, useEffect } from "react";
import { WorkflowVisualizer } from "@automove/workflow-visualizer";

export default function YourWorkflowPage() {
  const [workflow, setWorkflow] = useState(null);

  useEffect(() => {
    // Fetch workflow data from your API
    fetch("/api/workflows/123")
      .then(res => res.json())
      .then(setWorkflow);
  }, []);

  const handlePause = async (runId) => {
    await fetch(`/api/workflows/${runId}/pause`, { method: "POST" });
    // Refresh workflow state
  };

  if (!workflow) return <div>Loading...</div>;

  return (
    <WorkflowVisualizer
      workflowRun={workflow}
      onPause={handlePause}
      // ... other handlers
    />
  );
}

Advanced Usage

Real-time Updates

Use polling or WebSockets to update the workflow state:

useEffect(() => {
  const interval = setInterval(async () => {
    const updated = await fetch(`/api/workflows/${id}`).then(r => r.json());
    setWorkflow(updated);
  }, 2000);

  return () => clearInterval(interval);
}, [id]);

Custom Theming

<WorkflowVisualizer
  workflowRun={data}
  theme={{
    primaryColor: "#8b5cf6",
    successColor: "#22c55e",
    errorColor: "#dc2626",
  }}
/>

Browser Support

• Chrome/Edge 90+
• Firefox 88+
• Safari 14+

License

MIT

Support

For issues or questions, please open an issue on GitHub.