# How to Create Workflow Diagrams with Lanes and Branches Using Archify

> Learn to create workflow diagrams with lanes and branches in Archify. This guide shows how to use its JSON representation and CLI to generate clear, multi-actor process diagrams.

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

---

**Archify renders multi-actor processes as horizontal lanes with split-arrow branches for alternative paths, using a typed JSON intermediate representation and CLI commands to generate, validate, and deliver diagrams.**

The `tt-a1i/archify` repository provides a specialized **Workflow** view designed to model complex sequences like CI/CD pipelines and approval processes. When you create workflow diagrams with lanes and branches using Archify, the tool generates a deterministic visual layout that keeps the happy path clear while exposing exceptional flows through dedicated JSON syntax.

## Core Concepts: Lanes vs. Branches

Archify's workflow visualization relies on two structural elements to organize complexity.

**Lanes** represent horizontal tracks assigned to top-level participants such as *Browser*, *API*, or *Database*. Each actor defined in your JSON receives its own lane, ensuring the main sequence remains visually distinct. According to the schema defined in [`archify/schemas/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md), you assign lanes using the `lane` property on node objects.

**Branches** represent alternative or exceptional flows that split from the primary path. When you add a `branch` array to a step, Archify draws split arrows from the parent step to each target node, automatically aligning alternative lanes. This is ideal for modeling cache misses, fallbacks, or error states without cluttering the main diagram flow.

## Step-by-Step: Creating Workflow Diagrams with Lanes and Branches

The CLI entry point at `archify/bin/archify.mjs` provides a four-stage pipeline for building workflow diagrams.

### 1. Generate the Workflow IR

Start by creating a typed JSON **workflow IR** (`*.workflow.json`). You can generate this automatically using natural language or write it manually.

```bash
node archify/bin/archify.mjs guide "Show CI/CD checks, approval, deploy, and rollback" --json > my-pipeline.workflow.json

```

This intermediate representation lists all participants and the order of actions, establishing the foundation for your lane and branch structure.

### 2. Validate Against the Schema

Run the built-in validators to ensure your IR matches the required schema and layout rules.

```bash
node archify/bin/archify.mjs validate workflow my-pipeline.workflow.json --quality showcase --json

```

The validation catches missing lane IDs, ambiguous branches, or unsupported visual presets before rendering occurs.

### 3. Preview Locally

Iterate rapidly using the live preview command, which watches the JSON file and updates only after validation passes.

```bash
node archify/bin/archify.mjs preview workflow my-pipeline.workflow.json /tmp/pipeline.html --quality showcase

```

The viewer draws a lane for each actor and renders directed edges for each step, displaying branches as split arrows with automatic lane alignment.

### 4. Deliver the Final Artifact

Generate the deterministic HTML (and optional PNG/SVG) for sharing or embedding.

```bash
node archify/bin/archify.mjs deliver workflow my-pipeline.workflow.json /tmp/pipeline.html --quality showcase --open --json

```

The final artifact contains the complete lane arrangement, branch labels, and optional motion tracing if requested via the `trace` parameter.

## Workflow JSON Structure for Lanes and Branches

The [`archify/examples/agent-tool-call.workflow.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/agent-tool-call.workflow.json) file demonstrates the required JSON shape. Below is a minimal example showing lane assignment and branching logic:

```json
{
  "meta": {
    "type": "workflow",
    "visual_preset": "signal-flow"
  },
  "nodes": [
    { "id": "browser",   "label": "Browser",   "kind": "actor", "lane": "A" },
    { "id": "webapp",    "label": "Web App",   "kind": "service","lane": "B" },
    { "id": "api",       "label": "API",       "kind": "service","lane": "C" },
    { "id": "cache",     "label": "Redis Cache","kind":"datastore","lane":"D" },
    { "id": "db",        "label": "PostgreSQL","kind":"datastore","lane":"E" }
  ],
  "steps": [
    { "id": "s1", "source": "browser", "target": "webapp", "label": "GET /login" },
    { "id": "s2", "source": "webapp",  "target": "api",    "label": "POST /auth" },
    {
      "id": "s3",
      "source": "api",
      "target": "cache",
      "label": "Read session",
      "branch": [
        { "target": "db", "label": "cache-miss → DB fallback" }
      ]
    },
    { "id": "s4", "source": "cache", "target": "webapp", "label": "Session found" }
  ]
}

```

In this structure:

- The `lane` property places each node on its own horizontal track.
- The `branch` array under step `s3` creates a split arrow leading to the *DB* lane when the cache is missed.
- The `meta.visual_preset` field controls the overall look; `signal-flow` is the default for workflow diagrams and emphasizes lane clarity.

## Key Source Files

Understanding these files helps you customize and debug your workflow diagrams:

- **[`README_EN.md`](https://github.com/tt-a1i/archify/blob/main/README_EN.md)** — Overview of Archify's five diagram types, including the "Workflow keeps the happy path clear across lanes" design philosophy.
- **`archify/bin/archify.mjs`** — The CLI entry point powering the `guide`, `validate`, `preview`, and `deliver` commands.
- **[`archify/examples/agent-tool-call.workflow.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/agent-tool-call.workflow.json)** — A real-world workflow example demonstrating complex lane arrangements and branching logic.
- **[`archify/schemas/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md)** — Formal schema reference defining the workflow JSON shape, including lane and branch field specifications.
- **[`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md)** — Complete contract for the Archify skill, covering validation rules, delivery options, and visual preset configurations.

## Summary

- **Archify** provides a dedicated Workflow view for modeling multi-actor processes with clear visual separation.
- **Lanes** assign horizontal tracks to participants using the `lane` property in node definitions.
- **Branches** create alternative flows using the `branch` array within step objects, rendered as split arrows.
- The CLI pipeline (`guide` → `validate` → `preview` → `deliver`) ensures your `*.workflow.json` files are valid before rendering.
- The `signal-flow` visual preset optimizes layout for lane-based diagrams with complex branching.

## Frequently Asked Questions

### What is the difference between lanes and branches in Archify?

**Lanes** are horizontal tracks that organize steps by participant (e.g., Browser, API, Database), keeping the diagram's vertical flow uncluttered. **Branches** are forked paths within a step that model alternative outcomes like errors or cache misses, displayed as split arrows crossing between lanes.

### How do I assign a step to a specific lane?

Assign the `lane` property to node definitions in your JSON file, not to steps directly. Each step references source and target node IDs, and Archify positions the step visually based on the lane assigned to its target node. For example, `"lane": "C"` places a node in the third horizontal track.

### Can I use Archify workflows for CI/CD pipeline documentation?

Yes. The Workflow view is specifically designed for sequences like CI/CD pipelines, approval processes, and runbooks. The lane structure naturally separates tools (GitHub Actions, Docker, Kubernetes) while branches handle conditional logic such as test failures or rollback scenarios.

### Where can I find the JSON schema for workflow validation?

The formal schema reference is located in [`archify/schemas/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md). This document defines all required fields for the workflow IR, including lane identifiers, branch array structures, and valid values for the `meta.visual_preset` field.