workflow-graph

A GitHub Actions-style workflow DAG visualizer and job execution engine, built with Rust + WebAssembly.

Render interactive workflow graphs in the browser with pixel-perfect GitHub Octicon icons, drag-and-drop nodes, pan & zoom, path highlighting, and real-time job status updates. Execute workflows via a pluggable queue system with external workers.

Features

Visualization (WASM)

• GitHub-accurate DAG rendering — Octicon SVG icons via Canvas Path2D
• Interactive nodes — drag to reposition, click to select, shift+click for multi-select
• Pan & zoom — mouse wheel zoom (0.25x–4x), click+drag empty space to pan
• Touch support — full touch interaction: drag, pan, tap on mobile devices
• Path highlighting — hover a node to highlight its full upstream/downstream path in blue
• Animated status icons — spinning ring for running jobs, live elapsed timer
• Theming — light, dark, and high-contrast presets; fully customizable colors, fonts, and dimensions
• Layout direction — left-to-right (default) or top-to-bottom
• Minimap — optional overview overlay for large graphs
• Node CRUD API — add, remove, update nodes and edges at runtime with automatic re-layout
• Port system — typed input/output ports on nodes (Blender-style); edges connect port-to-port with type-checking
• Port rendering — colored port dots on node edges with labels; configurable colors per port type
• Port connections — drag from output port to input port to create edges; onConnect callback
• Drag & drop — native HTML5 drop zone on canvas; onDrop callback with graph-space coordinates
• Custom node rendering — callback to draw custom node content
• Edge click & styles — clickable edges with per-edge color, width, and dash patterns
• Node & edge metadata — arbitrary key-value metadata on nodes and edges for custom renderers
• i18n — configurable status labels and duration formats for any language
• Accessibility — ARIA live region for status announcements, keyboard navigation, high-contrast theme
• Auto-resize — ResizeObserver adapts canvas to container size changes
• HiDPI — adapts to devicePixelRatio changes (multi-monitor)

Job Execution (Server + Workers)

• Pluggable queue — trait-based: in-memory (dev), Postgres/pg-boss, Redis
• DAG scheduler — event-driven cascade: downstream jobs auto-start when deps succeed
• External workers — poll for jobs via HTTP, execute shell commands, stream logs
• Atomic job claiming — lease-based with TTL, prevents double-claiming
• Heartbeats — workers send periodic heartbeats; expired leases trigger re-queue
• Retry policy — configurable per-job retries with Fixed or Exponential backoff
• Cancellation — cancel workflows/jobs; workers detect and abort gracefully
• Graceful shutdown — workers handle SIGTERM/SIGINT, finish current job before exit
• Worker labels — jobs require labels, workers register capabilities
• Log streaming — workers push log chunks, server stores and serves them
• Artifact outputs — jobs publish key-value outputs, downstream jobs read them

Library Design

• 6 crates — shared types, queue engine, WASM frontend, worker SDK, reference server, standalone scheduler
• 3 npm packages — @auser/workflow-graph-web, @auser/workflow-graph-react, @auser/workflow-graph-client
• Trait-based backends — JobQueue, ArtifactStore, LogSink, WorkerRegistry
• YAML/JSON workflows — GitHub Actions-inspired definition format
• Embeddable — use create_router() to embed the API in your own Axum server
• Edge-deployable — API server is stateless; run scheduler separately or in-process
• 51 tests — unit, integration, performance, layout, and YAML parsing

Architecture

                     All-in-one (dev)          Split (edge/prod)
                     ────────────────          ─────────────────
┌──────────┐  poll   ┌──────────────┐         ┌───────────┐  ┌───────────┐
│  Worker   │◄──────►│   Server     │         │ API Server│  │ Scheduler │
│  (SDK)    │  HTTP  │ API+Scheduler│         │ (stateless│  │ (separate │
└──────────┘        └──────┬───────┘         │  process) │  │  process) │
                           │                  └─────┬─────┘  └─────┬─────┘
                      ┌────┴────┐                   │              │
                      │JobQueue │◄──────────────────┴──────────────┘
                      │LogSink  │
                      │Artifacts│
                      └─────────┘

Documentation

Full documentation is available at auser.github.io/workflow-graph.

NPM Packages

npm install @auser/workflow-graph-web      # WASM + Canvas renderer
npm install @auser/workflow-graph-react    # React component
npm install @auser/workflow-graph-client   # REST API client

TypeScript / Vanilla JS

import { WorkflowGraph, darkTheme, setWasmUrl } from '@auser/workflow-graph-web';

// Serve the .wasm file from public/ and set the URL
setWasmUrl('/workflow_graph_web_bg.wasm');

const graph = new WorkflowGraph(document.getElementById('container')!, {
  onNodeClick: (jobId) => console.log('clicked', jobId),
  onEdgeClick: (from, to) => console.log('edge', from, to),
  theme: darkTheme,
  autoResize: true,
});
await graph.setWorkflow(workflowData);

// Update statuses (preserves positions, zoom, selection)
await graph.updateStatus(newWorkflowData);

// Runtime theme switching
await graph.setTheme({ minimap: true, direction: 'TopToBottom' });

// Node CRUD — add, remove, update nodes and edges at runtime
await graph.addNode({
  id: 'new-job', name: 'New Job', status: 'queued',
  command: 'echo hello', depends_on: ['build'],
  metadata: { icon: 'rocket' },
});
await graph.addEdge('build', 'new-job', { label: 'on success' });
await graph.updateNode('new-job', { status: 'running' });
const nodes = await graph.getNodes();
const edges = await graph.getEdges();
await graph.removeEdge('build', 'new-job');
await graph.removeNode('new-job');

React

import { setWasmUrl } from '@auser/workflow-graph-web';
import { WorkflowGraphComponent, darkTheme } from '@auser/workflow-graph-react';
import type { WorkflowGraphHandle } from '@auser/workflow-graph-react';

setWasmUrl('/workflow_graph_web_bg.wasm');

const ref = useRef<WorkflowGraphHandle>(null);

<WorkflowGraphComponent
  ref={ref}
  workflow={workflowData}
  theme={darkTheme}
  autoResize
  onNodeClick={(id) => console.log(id)}
  onError={(err) => console.error(err)}
/>

// Imperative control via ref
ref.current?.zoomToFit();
ref.current?.setTheme({ minimap: true });

// Node CRUD via ref
await ref.current?.addNode({ id: 'deploy', name: 'Deploy', status: 'queued', command: './deploy.sh', depends_on: ['build'] });
await ref.current?.addEdge('build', 'deploy');
await ref.current?.updateNode('deploy', { status: 'running' });
const nodes = await ref.current?.getNodes();
const edges = await ref.current?.getEdges();
await ref.current?.removeNode('deploy');

REST API Client

import { WorkflowClient } from '@auser/workflow-graph-client';

const client = new WorkflowClient('http://localhost:3000');
const workflows = await client.listWorkflows();
await client.runWorkflow(workflows[0].id);

// Stream logs
for await (const chunk of client.streamLogs(wfId, jobId)) {
  console.log(chunk.data);
}

Examples

Working examples for each package are in the examples/ directory:

Theming

Three built-in presets:

import { darkTheme, lightTheme, highContrastTheme } from '@auser/workflow-graph-web';

Full customization via ThemeConfig:

const theme: ThemeConfig = {
  colors: { bg: '#1a1a2e', node_bg: '#16213e', text: '#e0e0e0' },
  fonts: { family: 'JetBrains Mono, monospace', size_name: 12 },
  layout: { node_width: 220, node_height: 48, h_gap: 80 },
  direction: 'TopToBottom',
  labels: { running: 'En curso', success: 'Listo' },  // i18n
  edge_styles: { 'build->deploy': { color: '#ff0', dash: [5, 3] } },
  minimap: true,
};

Crate Structure

Quick Start

Prerequisites

# Rust toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup target add wasm32-unknown-unknown
cargo install wasm-pack just

Build & Run

# Build WASM frontend + start server
just dev

# Or separately:
just build-wasm      # Build WASM (release, optimized)
just serve           # Start server (auto-finds port if 3000 is taken)
just build-packages  # Build all TypeScript packages

# Development with auto-reload:
just watch            # cargo-watch restarts server on changes

Open http://localhost:3000/index.html and click Run workflow.

Run a Worker (separate terminal)

cargo run -p workflow-graph-worker-sdk
# Or with custom server URL and labels:
SERVER_URL=http://localhost:3000 WORKER_LABELS=docker,linux cargo run -p workflow-graph-worker-sdk

Workflow Definition (YAML)

name: CI Pipeline
on: push

jobs:
  test:
    name: Unit Tests
    run: cargo test
    retries: 2

  lint:
    name: Lint
    run: cargo clippy

  build:
    name: Build
    needs: [test, lint]
    run: cargo build --release
    labels: [linux]

  deploy:
    name: Deploy
    needs: [build]
    labels: [linux, aws]
    steps:
      - name: Migrate DB
        run: ./scripts/migrate.sh
      - name: Deploy App
        run: ./scripts/deploy.sh

Place workflow files in workflows/ directory (.yml, .yaml, or .json).

REST API

Workflow Management

Worker Protocol

Environment Variables

Deployment Modes

All-in-one (default)

Runs the API server, DAG scheduler, and lease reaper in a single process. Best for development and simple deployments.

cargo run -p workflow-graph-server

Split (edge/serverless)

Runs the API server without the scheduler — suitable for edge platforms where functions are request-scoped.

# Terminal 1: API server (stateless, edge-deployable)
API_ONLY=1 cargo run -p workflow-graph-server

# Terminal 2: Standalone scheduler (long-running)
cargo run -p workflow-graph-scheduler

Embedding in Your Server

use std::sync::Arc;
use tokio::sync::RwLock;
use workflow_graph_queue::memory::*;
use workflow_graph_queue::{DagScheduler, WorkflowState};
use workflow_graph_server::state::AppState;

#[tokio::main]
async fn main() {
    let state = Arc::new(RwLock::new(WorkflowState::new()));
    let queue = Arc::new(InMemoryJobQueue::new());
    let artifacts = Arc::new(InMemoryArtifactStore::new());
    let logs = Arc::new(InMemoryLogSink::new());
    let workers = Arc::new(InMemoryWorkerRegistry::new());

    // Spawn scheduler (optional — omit for API-only / edge mode)
    let scheduler = Arc::new(DagScheduler::new(queue.clone(), artifacts.clone(), state.clone()));
    tokio::spawn(scheduler.clone().run());

    // Build your router with the stateless API
    let app = workflow_graph_server::create_router(AppState {
        workflow_state: state,
        queue, artifacts, logs, workers,
    });

    axum::serve(listener, app).await.unwrap();
}

Performance

See PERFORMANCE.md for benchmarks and optimization tips.

Testing

just test              # Run all tests (51 tests)
just check             # Type-check workspace
cargo test -p workflow-graph-queue                    # Queue + scheduler unit tests
cargo test --test integration -p workflow-graph-queue # Integration tests
cargo test --test performance -p workflow-graph-queue -- --nocapture # Benchmarks

License

MIT