Archify Workflow Diagram Schema: JSON Structure and Reference Guide

Archify workflow diagrams are defined as typed JSON objects using schema version 2 (with backward compatibility for version 1), composed of top-level properties for metadata, swim-lanes, phases, nodes, edges, and optional legend cards that drive the visual rendering engine.

The tt-a1i/archify repository uses a declarative JSON schema to transform workflow definitions into interactive HTML diagrams. Understanding the schema details for workflow diagrams in Archify enables developers to programmatically generate architectural visualizations that include swim-lanes, routing hints, and semantic node types.

Core Schema Structure

Every Archify workflow document must be a valid JSON object containing two mandatory fields that identify the schema version and diagram category.

• schema_version: An integer specifying the schema revision. The current implementation supports version 2 as the default, while maintaining backward compatibility with version 1.
• diagram_type: A string enum that must be exactly "workflow" to trigger the workflow rendering pipeline.

According to the source code in docs/gallery/sources/agent-tool-call.workflow.json, these fields precede all layout definitions and determine how the validator parses subsequent properties.

Top-Level Properties Explained

The workflow schema organizes visual and semantic data into distinct arrays and objects. Each property serves a specific function in the rendering pipeline.

Lanes and Phases

Lanes define horizontal swim-lanes that group nodes vertically. Each lane object requires an id (unique identifier) and label (display text), with an optional variant property (e.g., "exception") to apply styling modifiers.

Phases create logical column groups that define horizontal flow progression. They require id, label, fromCol, and toCol integers that map to column indices. Phases may carry variants such as "emphasis" or "dashed" to influence edge routing styles.

Groups and Main Paths

Groups are named edge-routing constraints that enforce visual styles across specific column and lane ranges. A group specifies lane, fromCol, toCol, and a variant (e.g., "security") to highlight policy boundaries.

mainPath is an ordered array of node IDs representing the primary "happy path" flow. The renderer uses this list to highlight critical connections while dimming auxiliary branches.

Nodes Array

The nodes array contains individual diagram elements positioned at the intersection of lanes and columns. Each node object supports these fields:

• id: Unique string identifier referenced by edges and mainPath.
• lane: Must match an existing lane id.
• col: Integer index for horizontal positioning.
• type: Semantic enum including frontend, backend, security, messagebus, cloud, database, and external.
• label / sublabel: Display text strings.
• Optional: tag, width, variant.

As implemented in docs/gallery/sources/release-delivery.workflow.json, node types drive iconography and color coding in the final HTML output.

Edges Array

Edges are directed connections between nodes with rich semantic and routing capabilities:

• from / to: Required node ID references.
• id: Optional stable identifier for animation targeting.
• label: Optional UI text displayed along the connection.
• variant: Visual style enum ("emphasis", "security", "dashed").
• role: Semantic classification ("error", "return", "branch").
• Routing hints: route, fromSide, toSide, labelSegment.

Cards Array

Optional cards provide legend documentation alongside the diagram. Each card contains a dot color specifier, a title, and an items array of descriptive strings explaining architectural constraints or contracts.

Metadata and Rendering Configuration

The meta object contains global rendering hints consumed by the Archify CLI and web renderer. These sub-fields control animation, quality profiles, and output destinations.

• title: Human-readable diagram title for browser tabs and headers.
• animation: Set to "trace" to enable progressive edge drawing animations.
• visual_preset: Style theme such as "signal-flow".
• quality_profile: Validation strictness ("showcase" represents high-fidelity output).
• output: Repository-relative path where the rendered HTML artifact is written (e.g., "examples/output.html").

Viewport Configurations

The views array inside meta defines named viewport configurations for interactive exploration. Each view object includes:

• id: Machine identifier for URL fragments or UI selectors.
• label: Human-friendly name shown in dropdown menus.
• focus: Array of node IDs to emphasize; unlisted nodes are dimmed.
• note: Short description explaining the view’s purpose.

When a user selects a specific view in the rendered HTML, Archify highlights only the nodes in the focus list, as demonstrated in the test fixtures at archify/test/fixtures/v1-workflow-explicit-coordinates.workflow.json.

Example: Complete Workflow JSON

The following minimal example illustrates schema version 2 with lanes, phases, nodes, edges, and metadata:

{
  "schema_version": 2,
  "diagram_type": "workflow",
  "meta": {
    "title": "Simple Greeting Workflow",
    "animation": "trace",
    "visual_preset": "signal-flow",
    "quality_profile": "showcase",
    "views": [
      {
        "id": "default",
        "label": "Full Flow",
        "focus": ["request", "reply"],
        "note": "Shows the end-to-end greeting."
      }
    ],
    "output": "examples/simple-greeting.html"
  },
  "lanes": [
    { "id": "ui", "label": "User Interface" },
    { "id": "bot", "label": "Bot Runtime" }
  ],
  "phases": [
    { "id": "receive", "label": "Receive", "fromCol": 0, "toCol": 1 },
    { "id": "respond", "label": "Respond", "fromCol": 2, "toCol": 3 }
  ],
  "mainPath": ["request", "reply"],
  "nodes": [
    { "id": "request", "lane": "ui", "col": 0, "type": "external", "label": "User", "sublabel": "asks hello" },
    { "id": "reply", "lane": "ui", "col": 3, "type": "backend", "label": "Bot Reply", "sublabel": "says hi" }
  ],
  "edges": [
    { "from": "request", "to": "reply", "variant": "emphasis", "role": "return" }
  ],
  "cards": [
    {
      "dot": "emerald",
      "title": "Simple Flow",
      "items": ["One request → one reply", "No branching"]
    }
  ]
}

Programmatic Generation

You can construct workflow objects dynamically using Node.js and Archify’s rendering API. This approach is useful for generating diagrams from CI/CD pipelines or database schemas:

import { writeFileSync } from "fs";
import { renderWorkflow } from "archify";

const workflow = {
  schema_version: 2,
  diagram_type: "workflow",
  meta: {
    title: "Dynamic Data Ingestion",
    animation: "trace",
    visual_preset: "signal-flow",
    quality_profile": "showcase",
    views: [{ id: "default", "label": "Full", "focus": [], "note": "All nodes visible" }],
    output: "examples/dynamic-ingest.html"
  },
  lanes: [
    { id: "source", "label": "Source Systems" },
    { id: "ingest", "label": "Ingestion Service" },
    { id: "store", "label": "Data Lake" }
  ],
  phases: [
    { id: "collect", "label": "Collect", "fromCol": 0, "toCol": 1 },
    { id": "persist", "label": "Persist", "fromCol": 2, "toCol": 3 }
  ],
  mainPath: ["api", "collector", "loader"],
  nodes: [
    { id: "api", "lane": "source", "col": 0, "type": "frontend", "label": "API", "sublabel": "pull events" },
    { id: "collector", "lane": "ingest", "col": 1, "type": "backend", "label": "Collector", "sublabel": "batch fetch" },
    { id: "loader", "lane": "store", "col": 3, "type": "cloud", "label": "Loader", "sublabel": "write S3" }
  ],
  edges": [
    { "from": "api", "to": "collector", "variant": "emphasis" },
    { "from": "collector", "to": "loader", "variant": "emphasis" }
  ],
  cards: [{ "dot": "cyan", "title": "Ingestion Overview", "items": ["API → Collector → Loader"] }]
};

renderWorkflow(workflow).then(html => {
  writeFileSync("examples/dynamic-ingest.html", html);
});

The renderWorkflow function accepts a schema-valid object and returns a Promise resolving to the complete HTML string, which can be persisted to disk or served directly.

Summary

• Archify workflow diagrams use schema version 2 JSON objects with diagram_type set to "workflow".
• Top-level properties include meta, lanes, phases, groups, mainPath, nodes, edges, and optional cards for legends.
• Nodes support semantic types (frontend, backend, security, etc.) and are positioned via lane and col coordinates.
• Edges carry routing hints (fromSide, toSide), visual variants (emphasis, security), and semantic roles (error, return).
• The meta.views array enables interactive exploration by focusing on specific node subsets.
• Source examples are available in docs/gallery/sources/agent-tool-call.workflow.json and docs/gallery/sources/release-delivery.workflow.json.

Frequently Asked Questions

What is the current schema version for Archify workflow diagrams?

The current schema version is 2, as specified by the schema_version integer field. Version 1 remains supported for backward compatibility, but new implementations should target version 2 to access the full feature set including advanced routing hints and view configurations.

How do I define swim-lanes in an Archify workflow?

Define swim-lanes using the lanes array, where each object requires a unique id and a human-readable label. Nodes reference these lanes via their own lane property to establish vertical grouping. Optional variant strings (such as "exception") can be applied to lanes to trigger specialized styling in the rendered output.

What node types are supported in Archify workflow diagrams?

The schema supports seven semantic node types exposed through the type field: frontend, backend, security, messagebus, cloud, database, and external. These types determine the iconography and color palette applied by the renderer, as seen in the canonical examples at docs/gallery/sources/agent-tool-call.workflow.json.

How do I programmatically render a workflow diagram in Archify?

Import the renderWorkflow function from the archify package, pass a schema-valid JSON object, and handle the returned Promise to obtain the HTML string. Write this string to a file path specified in meta.output or serve it directly via a web server. This method allows dynamic generation of architectural diagrams from code or configuration files.

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