How to Create Workflow Diagrams Using Archify: A Complete Developer's Guide

Archify renders production-ready workflow diagrams from declarative JSON specifications, validating them against a strict schema and generating self-contained HTML output without external dependencies.

The tt-a1i/archify repository provides a schema-driven toolkit for creating architectural diagrams programmatically. By defining workflows as structured JSON files, you can version-control your system architecture, automate diagram generation in CI/CD pipelines, and ensure consistent visual standards across your documentation.

Core Architecture Components

Archify's workflow generation pipeline consists of three specialized components that work together to transform JSON specifications into polished SVG diagrams.

The JSON Schema Validator

Every workflow diagram begins with a JSON file that must conform to the workflow schema located at archify/schemas/workflow.schema.json. The schema enforces required top-level fields including schema_version, diagram_type, meta, lanes, nodes, and edges. It also validates optional sections such as phases for high-level story beats, groups for parallel work isolation, mainPath for happy-path validation, and cards for embedded legends.

The Workflow Renderer

The workflow renderer (archify/renderers/workflow/render-workflow.mjs) consumes validated JSON and produces a complete HTML page using Archify's standard template. This module bundles its own validator, eliminating external dependencies. The renderer applies automatic layout algorithms, assigns visual styles based on node types, and calculates orthogonal edge routing.

The Artifact Checker

After rendering, the optional artifact checker (archify/scripts/check-render-output.mjs) scans generated HTML for SVG anomalies. It detects non-finite values, overly short arrows, and crossing issues to enforce quality standards before the diagram reaches production.

Building Your First Workflow Diagram

Creating a workflow diagram follows a declarative approach where you define structure, components, and connections in JSON format.

Define the JSON Structure

Start with a JSON file containing the mandatory fields. The schema_version must be set to 1, and diagram_type must specify "workflow". The meta object requires at least a title property and optionally output to specify the default HTML filename.

{
  "schema_version": 1,
  "diagram_type": "workflow",
  "meta": { "title": "API Request Flow", "output": "api-flow.html" },
  "lanes": [],
  "nodes": [],
  "edges": []
}

Configure Lanes and Phases

Lanes define ownership or runtime boundaries in your architecture. Each lane requires an id and label. You can optionally add phases to create vertical columns representing high-level story beats like Intake, Plan, and Execute.

{
  "lanes": [
    { "id": "client", "label": "Client Application" },
    { "id": "gateway", "label": "API Gateway" },
    { "id": "service", "label": "Backend Service" }
  ],
  "phases": [
    { "id": "auth", "label": "Authentication" },
    { "id": "process", "label": "Processing" }
  ]
}

Add Nodes with Types and Labels

Nodes represent architectural components within lanes. Each node requires id, lane, col (column index), type, and label fields. The type property maps to component kinds including frontend, backend, security, messagebus, database, cloud, and external.

Optional fields customize appearance: sublabel adds descriptive text below the main label, tag overlays a small badge, brand applies vendor-specific styling, and width/height override default dimensions.

{
  "nodes": [
    { 
      "id": "mobile", 
      "lane": "client", 
      "col": 0, 
      "type": "external", 
      "label": "Mobile App",
      "tag": "iOS/Android"
    },
    { 
      "id": "auth-service", 
      "lane": "gateway", 
      "col": 1, 
      "type": "security", 
      "label": "OAuth Handler" 
    }
  ]
}

Connect Nodes with Edges

Edges define relationships between nodes using from and to properties that reference node IDs. Customize connections using:

• variant: default, emphasis, security, or dashed
• role: main, branch, async, return, or error
• Routing options: drop, outside-right, return-left, bottom-channel, or up-channel

{
  "edges": [
    { 
      "id": "login", 
      "from": "mobile", 
      "to": "auth-service", 
      "variant": "security",
      "role": "main",
      "route": "drop"
    }
  ]
}

Embed Cards and Legends

Add explanatory cards to embed legends or contextual notes directly in the diagram. Cards support dot color specifications, title text, and items arrays for bullet points. The legend automatically derives entries from nodes[].type, though you can override this via meta.legend.entries.

Rendering and Validation Commands

Archify supports both CLI and programmatic rendering workflows.

CLI Rendering

Execute the renderer via Node.js, providing the input JSON path and optional output HTML filename:

node archify/renderers/workflow/render-workflow.mjs path/to/your.workflow.json output.html

If you omit output.html, the renderer falls back to the meta.output field or defaults to workflow.html.

Programmatic Rendering

Import the renderer module directly for integration into Node.js applications:

const { renderWorkflow } = require('../archify/renderers/workflow/render-workflow.mjs');
const fs = require('fs');

const spec = JSON.parse(fs.readFileSync('workflow.json', 'utf8'));
renderWorkflow(spec, { output: 'diagram.html' })
  .then(() => console.log('Rendered successfully'))
  .catch(err => console.error('Render error:', err));

Post-Render Validation

Run the artifact checker to detect SVG geometry issues and enforce quality standards:

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

This tool validates against quality profiles (standard vs. showcase), where showcase mode rejects short route segments and improper edge crossings.

Advanced Design Patterns

Sophisticated workflows leverage Archify's layout primitives for complex architectural visualization.

Using Groups and Exception Lanes

Groups isolate parallel or branching work within individual lanes, creating visual boundaries around related nodes. Exception lanes (marked with variant: "exception") visually separate retry logic, denial paths, and failure handling from main flow lines.

MainPath Validation

The optional mainPath array validates that your happy path proceeds left-to-right logically. Archify verifies that each consecutive node in this array possesses a corresponding edge connecting them, ensuring diagram completeness.

Edge Routing Strategies

For complex orthogonal routing, combine route presets with via coordinates and bias adjustments. The routing engine prefers presets before calculating custom paths, ensuring consistent spacing and avoiding node overlap.

Summary

• Archify validates all workflow definitions against archify/schemas/workflow.schema.json before rendering, ensuring structural integrity.
• The renderer at archify/renderers/workflow/render-workflow.mjs converts JSON specifications into standalone HTML files with embedded SVG diagrams.
• Nodes support seven core types (frontend, backend, security, messagebus, database, cloud, external) with optional tagging and dimensional overrides.
• Edges offer granular control through variants, roles, and routing presets including drop, outside-right, and return-left.
• The artifact checker archify/scripts/check-render-output.mjs enforces quality profiles and detects visual anomalies like crossing edges or non-finite coordinates.
• Reference implementations in archify/examples/agent-tool-call.workflow.json demonstrate production-ready patterns for lanes, phases, groups, and mainPath validation.

Frequently Asked Questions

What fields are required in an Archify workflow JSON file?

Every workflow JSON must include schema_version (set to 1), diagram_type (set to "workflow"), meta (containing at least a title), lanes (array of lane definitions), nodes (array of component definitions), and edges (array of connection definitions). The schema at archify/schemas/workflow.schema.json strictly enforces these requirements.

How do I render a workflow diagram from the command line?

Execute node archify/renderers/workflow/render-workflow.mjs followed by your input JSON path and desired output HTML filename. For example: node archify/renderers/workflow/render-workflow.mjs workflow.json diagram.html. If you omit the output filename, the renderer uses the meta.output field or defaults to workflow.html.

What edge routing options are available in Archify?

Archify supports five routing presets: drop (vertical descent), outside-right (exit right of source), return-left (loop back left), bottom-channel (low horizontal path), and up-channel (high horizontal path). You can also specify raw via points for custom orthogonal routing, with bias values to adjust path preferences.

How can I validate my workflow diagram for visual quality issues?

Run the artifact checker using node archify/scripts/check-render-output.mjs output.html. This tool scans the generated SVG for non-finite coordinate values, arrows shorter than layout tolerances, and improper edge crossings. Enable showcase quality profile for stricter validation that rejects short segments and crossing violations.

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