# Archify Workflow Diagram Schema: JSON Structure and Reference Guide

> Explore the Archify workflow diagram schema version 2. Understand its JSON structure including metadata, swim-lanes, phases, nodes, edges, and legend cards for visual rendering.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: api-reference
- Published: 2026-09-10

---

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

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

```javascript
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`](https://github.com/tt-a1i/archify/blob/main/docs/gallery/sources/agent-tool-call.workflow.json) and [`docs/gallery/sources/release-delivery.workflow.json`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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.