How to Use the Workflow Diagram Type in Archify: Complete Guide with JSON Schema and CLI Examples

Archify's workflow diagram type lets you model technical processes—AI agent tool-calls, CI/CD pipelines, runbooks, or policy-driven approval chains—by authoring a JSON file validated against archify/schemas/workflow.schema.json and compiled into a standalone HTML artifact.

The workflow renderer in tt-a1i/archify transforms declarative JSON into production-ready SVG diagrams with swim-lanes, phases, and semantic validation. This guide covers the core concepts, CLI commands, and best practices for using the workflow diagram type effectively.

Core Architecture of Workflow Diagrams

A workflow diagram in Archify consists of seven core building blocks defined in your JSON intermediate representation (IR):

Concept	Purpose	Key Property
diagram_type	Activates the workflow renderer	Must be "workflow"
lanes	Horizontal swim-lanes for ownership boundaries	id, label
phases	Vertical bands grouping logical stages	fromCol, toCol
groups	Containers for parallel or exception paths	lane assignment
nodes	Individual steps with semantic typing	lane, col, type
edges	Directed connections with routing control	variant, route, fromSide/toSide
mainPath	Happy-path validation list	Ordered node IDs

The renderer enforces left-to-right flow validation: every edge in mainPath must exist and progress from lower to higher column indices.

JSON Schema Contract

All workflow files must validate against archify/schemas/workflow.schema.json. The schema defines strict types for layout computation and semantic checking.

Required Top-Level Fields

{
  "schema_version": 2,
  "diagram_type": "workflow",
  "meta": {
    "title": "Your Diagram Title",
    "quality_profile": "standard"
  },
  "lanes": [...],
  "nodes": [...],
  "edges": [...],
  "mainPath": [...]
}

Optional enhancements include phases for visual grouping, groups for nested containers, cards for sidebar annotations, and semanticChecks for domain-level constraints like allowedRoots or required edges.

Rendering Pipeline: 3 Steps

Step 1: Author the JSON IR

Start from the built-in example at archify/examples/agent-tool-call.workflow.json. Define your structure using logical columns (col) rather than raw coordinates—the compiler translates these into pixel positions.

Step 2: Run the Renderer

node archify/renderers/workflow/render-workflow.mjs input.workflow.json output.html

• Omit output.html to use meta.output or default to workflow.html in the current directory
• The script automatically validates against the schema before layout computation
• Output is a self-contained HTML file with embedded SVG, theme toggle, and export menu

Step 3: Validate the Artifact

node archify/scripts/check-render-output.mjs output.html

This checker catches:

• Non-finite coordinate values
• Diagonal arrows (should be orthogonal)
• Legend collisions

Minimal Workflow Example: CI Pipeline

{
  "schema_version": 2,
  "diagram_type": "workflow",
  "meta": {
    "title": "Simple CI Pipeline",
    "quality_profile": "standard"
  },
  "lanes": [
    { "id": "src", "label": "Source" },
    { "id": "build", "label": "Build" },
    { "id": "deploy", "label": "Deploy" }
  ],
  "phases": [
    { "id": "fetch", "label": "Fetch", "fromCol": 0, "toCol": 1 },
    { "id": "run", "label": "Run", "fromCol": 2, "toCol": 3 }
  ],
  "nodes": [
    { "id": "checkout", "lane": "src", "col": 0, "type": "frontend", "label": "Checkout" },
    { "id": "compile",  "lane": "build", "col": 2, "type": "backend", "label": "Compile" },
    { "id": "publish",  "lane": "deploy", "col": 4, "type": "cloud", "label": "Publish" }
  ],
  "edges": [
    { "id": "e1", "from": "checkout", "to": "compile", "variant": "default" },
    { "id": "e2", "from": "compile", "to": "publish", "variant": "default" }
  ],
  "mainPath": ["checkout", "compile", "publish"]
}

Render with:

node archify/renderers/workflow/render-workflow.mjs simple-ci.workflow.json

Full-Featured Example: AI Agent Tool-Call Workflow

The repository includes a production-ready example demonstrating advanced features:

node archify/renderers/workflow/render-workflow.mjs \
  archify/examples/agent-tool-call.workflow.json \
  workflow-agent-tool-call-rendered.html

This example showcases:

• Multiple lanes: ui, agent, policy, tool, external
• Phases: intake, plan, execute
• Groups: Parallel paths and exception handling
• Cards: Sidebar summary boxes with dot color indicators
• Semantic checks: allowedRoots and required edge validation

The generated HTML includes accessibility metadata: <desc id="archify-diagram-description">A workflow diagram generated by Archify.</desc> as seen in archify/examples/workflow-agent-tool-call-rendered.html.

Advanced Routing and Styling

Edge Routing Presets

Prefer these route values over manual via arrays:

• drop — vertical down-then-right
• outside-right — exit right side, re-enter from left
• bottom-channel — shared gutter below lanes

Variant-Driven Legend

The variant field on nodes and edges drives automatic legend generation:

Variant	Typical Use
frontend	User interface components
backend	Application logic
security	Authentication, approval gates
cloud	External services, infrastructure

CLI Utilities for Workflow Management

Validate with Layout Receipt

node archify/bin/archify.mjs validate workflow \
  archify/examples/agent-tool-call.workflow.json --layout-json

Outputs computed positions for debugging or migration tooling.

Migrate Legacy Versions

node archify/bin/archify.mjs migrate workflow old.json new.json \
  --to-schema 2 --json

See archify/renderers/workflow/README.md for detailed migration notes.

Best Practices for Production Diagrams

• Use meta.quality_profile: "showcase" for final outputs—this enables stricter crossing minimization
• Keep mainPath synchronized with visual flow to leverage automatic happy-path linting
• Set explicit fromSide/toSide only when route presets fail; defaults produce cleaner orthogonality
• Group exception paths with groups rather than scattering nodes across lanes
• Run check-render-output.mjs in CI pipelines to catch SVG regressions

Key Source Files

Path	Purpose
archify/schemas/workflow.schema.json	JSON Schema validation contract
archify/renderers/workflow/render-workflow.mjs	Main compilation entry point
archify/renderers/workflow/README.md	Renderer-specific documentation
archify/examples/agent-tool-call.workflow.json	Reference implementation
archify/bin/archify.mjs	Unified CLI (validate, migrate, render)
scripts/check-render-output.mjs	Post-render quality assurance

Summary

• Archify workflow diagrams are authored as JSON IR files with diagram_type: "workflow"
• The rendering pipeline validates against archify/schemas/workflow.schema.json, computes layouts, and emits standalone HTML
• Core concepts include lanes (horizontal ownership), phases (vertical grouping), nodes (typed steps), and edges (routed connections)
• Quality assurance combines quality_profile settings with the check-render-output.mjs script
• Migration and validation are handled through archify/bin/archify.mjs

Frequently Asked Questions

What JSON schema version does Archify workflow use?

Archify workflow diagrams use schema_version 2 as defined in archify/schemas/workflow.schema.json. The CLI provides migration tools from v1 via archify/bin/archify.mjs migrate workflow.

How do I control edge routing without manual coordinates?

Use the route preset field on edges with values like drop, outside-right, or bottom-channel. These presets compute clean orthogonal paths automatically. Manual via arrays are supported but discouraged for maintainability.

Can I validate a workflow file without rendering it?

Yes. Run node archify/bin/archify.mjs validate workflow <file.json> for schema validation only, or add --layout-json to output computed positions without generating HTML.

What does the artifact checker detect?

scripts/check-render-output.mjs catches non-finite SVG coordinates, diagonal arrows (which should be orthogonal), and legend collisions that could obscure diagram elements.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}