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

> Master Archify's workflow diagram type to model technical processes. Learn to author JSON files validated against the schema and compile them into HTML artifacts with CLI examples.

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

---

**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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) and compiled into a standalone HTML artifact.**

The workflow renderer in [`tt-a1i/archify`](https://github.com/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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json). The schema defines strict types for layout computation and semantic checking.

### Required Top-Level Fields

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

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

```

- Omit [`output.html`](https://github.com/tt-a1i/archify/blob/main/output.html) to use `meta.output` or default to [`workflow.html`](https://github.com/tt-a1i/archify/blob/main/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

```bash
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

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

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

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

```bash
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

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

```

See [`archify/renderers/workflow/README.md`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) | JSON Schema validation contract |
| `archify/renderers/workflow/render-workflow.mjs` | Main compilation entry point |
| [`archify/renderers/workflow/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/renderers/workflow/README.md) | Renderer-specific documentation |
| [`archify/examples/agent-tool-call.workflow.json`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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.