How to Create Workflow Diagrams with Lanes and Branches Using Archify

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, 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.

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.

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.

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.

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 file demonstrates the required JSON shape. Below is a minimal example showing lane assignment and branching logic:

{
  "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 — 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 — A real-world workflow example demonstrating complex lane arrangements and branching logic.
• archify/schemas/README.md — Formal schema reference defining the workflow JSON shape, including lane and branch field specifications.
• 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. 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.

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