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

> Learn to create workflow diagrams with Archify. This guide shows developers how to generate HTML diagrams from JSON specifications, validating and producing self-contained output.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-08-29

---

**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`](https://github.com/tt-a1i/archify/blob/main/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.

```json
{
  "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`.

```json
{
  "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.

```json
{
  "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`

```json
{
  "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:

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

```

If you omit [`output.html`](https://github.com/tt-a1i/archify/blob/main/output.html), the renderer falls back to the `meta.output` field or defaults to [`workflow.html`](https://github.com/tt-a1i/archify/blob/main/workflow.html).

### Programmatic Rendering

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

```js
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:

```bash
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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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.