flowjob

flowjob turns flow JSON into a single interactive HTML flow. The output embeds its data, CSS, JavaScript, and line renderer, opens directly through file://, and makes no automatic network requests.

Flow data is immutable in the browser. Users and agents explore it by revealing branches and arranging the diagram, then save that presentation as a display. Displays can be stored locally, exchanged as JSON, or pre-baked into another flow.

Requirements

• Node.js 20 or newer
• A modern browser for generated flows

Install

npm install @p10i/flowjob

CLI

flowjob validate architecture.json
flowjob validate architecture.json --json
flowjob build architecture.json --output architecture.html
flowjob build architecture.json --output architecture.html --force

Pre-bake one or more display files:

flowjob build architecture.json \
  --display checkout.json \
  --display refund.json \
  --initial-display "Checkout" \
  --output architecture.html

The repository includes a complete example:

flowjob build examples/order-processing.flow.json \
  --display examples/order-processing.display.json \
  --initial-display "Place order" \
  --output order-processing.html

--display accepts a display envelope or a display bundle and may be repeated. Existing output is not overwritten unless --force is present. Both commands support --json for machine-readable output.

Agent discovery

Agents can print the bundled schemas and a complete example without locating package files:

flowjob schema flow
flowjob schema display
flowjob example
flowjob skill

The schema and example commands write only formatted JSON to stdout. skill prints a standards-compliant Agent Skill containing the recommended workflow. A typical agent workflow is to inspect flowjob schema flow, generate an input document, and check it with flowjob validate input.json --json before building. The skill is exported as @p10i/flowjob/skills/flowjob/SKILL.md for agent tooling that installs skills from package resources.

Library

import {
    buildFlow,
    buildFlowFile,
    fingerprintFlow,
    validateDisplay,
    validateFlow,
} from "@p10i/flowjob";

const validation = validateFlow(flowData);
if (!validation.valid) {
    console.error(validation.errors);
}

const html = buildFlow(flowData, {
    displays: [checkoutDisplay],
    initialDisplay: checkoutDisplay,
});

The public ESM API exports:

• buildFlow(flowData, options)
• buildFlowFile(inputPath, outputPath, options)
• validateFlow(flowData)
• validateDisplay(display, flowData)
• fingerprintFlow(flowData)
• stableStringify(value)

Flow Data

Flow data describes modules, their submodules, and directed relationships. IDs may be strings or finite numbers and are canonicalized as strings by the viewer, so 1 and "1" cannot coexist as distinct IDs.

{
  "schemaVersion": 1,
  "title": "Order processing",
  "modules": [
    {
      "id": "orders",
      "name": "Orders",
      "submodules": [
        { "id": "submit", "name": "submitOrder()" }
      ]
    },
    {
      "id": "payments",
      "name": "Payments",
      "submodules": [
        { "id": "capture", "name": "capturePayment()" }
      ]
    }
  ],
  "flows": [
    {
      "id": "capture-call",
      "type": "capturePayment()",
      "relationType": "call",
      "from": { "module": "orders", "submodule": "submit" },
      "to": { "module": "payments", "submodule": "capture" }
    }
  ]
}

The published schema is available as @p10i/flowjob/schema/flow.schema.json. Optional moduleTypes, relationTypes, detailFilterOptions, styling fields, and metadata are passed to the viewer.

Displays

A display belongs to one exact flow fingerprint and contains presentation state without duplicating flow data:

{
  "schemaVersion": 1,
  "flowFingerprint": "sha256:...",
  "name": "Checkout",
  "state": {
    "targetModuleId": "orders",
    "branches": [],
    "nextBranchId": 1,
    "columnState": {},
    "messageSortKeys": {}
  }
}

The generated UI can save named displays in browser storage, import or export display JSON, and export the current display as a new standalone flow. Browser storage is namespaced by the source fingerprint.

Agents can use the generated browser API:

window.flowjob.listDisplays();
window.flowjob.getCurrentDisplay();
window.flowjob.applyDisplay(display);
window.flowjob.saveDisplay("Checkout");
window.flowjob.exportFlowHtml();

The display schema is available as @p10i/flowjob/schema/display.schema.json.

Development

npm run test:unit
npm run test:browser-unit
npm test
npm run test:all

All browser tests run against generated flows. Test setup creates a temporary standalone harness with demo data, fixtures, and the internal test API; production flows strip that instrumentation.