# Layout Contract for Archify v2 Workflows: JSON Schema and Rendering Pipeline

> Understand the Archify v2 workflows layout contract. This strict JSON schema ensures deterministic SVG and HTML diagram rendering with semantic elements and visual properties.

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

---

**The layout contract for Archify v2 workflows is a strict JSON schema requiring `schema_version: 2` that defines semantic elements (lanes, nodes, edges) and visual layout properties, validated against [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) to guarantee deterministic SVG and HTML diagram rendering.**

The `tt-a1i/archify` repository implements a versioned **layout compiler** that transforms structured workflow definitions into visual artifacts. This contract establishes the binding specification between the semantic model—what the workflow represents—and the rendering engine in `archify/renderers/workflow/render-workflow.mjs`, ensuring reproducible output across CLI versions when processed by `archify/bin/archify.mjs`.

## Schema Version and Root Requirements

The layout contract is strictly versioned. According to [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) lines 17–20, the root object must declare `"schema_version": 2` as an integer to opt into the v2 readable layout compiler. Lines 22–24 mandate `"diagram_type": "workflow"`, which signals the renderer to process the definition as a workflow diagram rather than other supported diagram types.

The `meta` object (lines 25–65) holds optional UI-related settings including `title`, `quality_profile`, and `visual_preset`. The **visual_preset** accepts values such as `classic`, `signal-flow`, `blueprint`, or `editorial`, selecting predefined visual styles without altering the semantic structure.

## Semantic Layout Elements

### Lanes and Phases

**Lanes** are ordered containers that group nodes into horizontal tracks. As defined in lines 6–30 of the schema, each lane requires an `id` and `label`, with an optional `variant` property for styling variations. The renderer maps each lane to a distinct vertical track in the final diagram.

**Phases** (lines 33–71) create horizontal bands within a lane that constrain node placement using `fromCol` and `toCol` properties. These limit which columns (0–5) nodes may occupy, creating logical stages across the workflow timeline.

### Groups and Cards

**Groups** (lines 73–115) provide rectangular visual containers that span a single lane and a specific column range (`fromCol` to `toCol`). These render as shaded backgrounds behind nodes to indicate logical clusters, though they do not participate in layout calculations or node positioning.

**Cards** (lines 197–199) reference the generic cards definition from the common schema. These elements provide overlay annotations that appear above the diagram canvas without affecting the core layout geometry or node spacing.

## Node Positioning and Sizing

Nodes are defined in [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) lines 55–101. Each node must specify:

- `id`: Unique identifier referenced by edges and the main path
- `lane`: ID of the containing lane
- `col`: Integer column index (constrained to 0–5) determining horizontal placement
- `type`: Semantic classification (e.g., `request`, `approval`, `task`)
- `label`: Display text rendered inside the node shape

Layout-specific optional fields include `width`, `height`, and `yOffset`. The layout compiler uses these values to compute exact positioning, spacing, and vertical alignment offsets within the assigned lane.

The `mainPath` property (lines 17–22) accepts an ordered array of node IDs that define the primary **critical path**. The renderer highlights this sequence with distinct styling to emphasize the core workflow flow through the diagram.

## Edge Routing and Connection Logic

Edges connect nodes and carry extensive routing instructions defined in lines 110–170. The layout compiler processes these properties to generate SVG path data:

- `role`: Classification such as `main`, `branch`, or `async` affecting visual weight and color
- `fromSide` / `toSide`: Attachment points (`left`, `right`, `top`, `bottom`) on the source and target nodes
- `route`: Routing algorithm selection including `auto`, `straight`, `drop`, `outside-right`, or `bottom-channel`
- `via`: Array of explicit intermediate `[x, y]` coordinate points for custom path routing
- `bias` and `width`: Fine-tuning parameters for curve tension and stroke weight
- `labelAt`, `labelDx`, `labelDy`: Optional label positioning relative to the path geometry

## Rendering Pipeline Implementation

When a workflow JSON is processed by the CLI at `archify/bin/archify.mjs`, the layout compiler validates the document against the schema and then produces an artifact where:

- Lanes render as distinct horizontal tracks with calculated spacing
- Phases constrain node positions within specified column ranges
- Groups draw shaded rectangular backgrounds spanning their defined regions
- The **mainPath** receives highlight styling distinct from standard nodes
- Edges route according to `route` type and `via` hints, respecting `fromSide` and `toSide` constraints
- Node dimensions (`width`, `height`) determine collision boxes and spacing margins

The test suite in `archify/test/workflow-compiler.test.mjs` verifies this behavior, ensuring that edge routing and lane handling conform to the contract across supported `visual_preset` configurations.

## Complete Workflow Example

The following JSON demonstrates a valid v2 workflow adhering to the layout contract with lanes, phases, groups, and routed edges:

```json
{
  "schema_version": 2,
  "diagram_type": "workflow",
  "meta": {
    "title": "Sample Approval Flow",
    "visual_preset": "signal-flow",
    "quality_profile": "standard"
  },
  "lanes": [
    { "id": "lane-req", "label": "Request" },
    { "id": "lane-act", "label": "Action" }
  ],
  "phases": [
    { "id": "phase-1", "label": "Start", "fromCol": 0, "toCol": 2 },
    { "id": "phase-2", "label": "Decision", "fromCol": 2, "toCol": 4 }
  ],
  "groups": [
    { "id": "group-review", "label": "Review", "lane": "lane-act", "fromCol": 2, "toCol": 4 }
  ],
  "mainPath": ["node-req", "node-approve", "node-complete"],
  "nodes": [
    { "id": "node-req", "lane": "lane-req", "col": 1, "type": "request", "label": "User Request" },
    { "id": "node-approve", "lane": "lane-act", "col": 3, "type": "approval", "label": "Manager Approval" },
    { "id": "node-complete", "lane": "lane-act", "col": 4, "type": "task", "label": "Complete" }
  ],
  "edges": [
    {
      "from": "node-req",
      "to": "node-approve",
      "role": "main",
      "fromSide": "right",
      "toSide": "left",
      "route": "auto"
    },
    {
      "from": "node-approve",
      "to": "node-complete",
      "role": "main",
      "fromSide": "right",
      "toSide": "left",
      "route": "straight"
    }
  ]
}

```

### CLI Validation and Rendering

Execute the following commands to validate the contract and generate output:

```bash

# Validate schema compliance and layout contract

node archify/bin/archify.mjs validate workflow sample.json --layout-json

# Render to HTML with computed layout

node archify/bin/archify.mjs render workflow sample.json > demo.html

```

The generated [`demo.html`](https://github.com/tt-a1i/archify/blob/main/demo.html) displays the lanes as horizontal tracks, highlights the mainPath, renders the "Review" group as a shaded rectangle, and routes edges according to the specified side preferences and route types.

## Summary

- The **layout contract for Archify v2 workflows** requires `"schema_version": 2` and `"diagram_type": "workflow"` as defined in [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) lines 17–24.
- **Lanes** organize nodes into horizontal tracks, while **phases** constrain placement to specific column ranges (0–5) and **groups** provide visual background containers.
- **Nodes** must declare their lane, column position, and type, with optional explicit dimensions (`width`, `height`, `yOffset`) used for spacing calculations.
- **Edges** define routing through `route` algorithms, `fromSide`/`toSide` attachments, and optional `via` coordinate arrays, processed by the layout compiler in `archify/renderers/workflow/render-workflow.mjs`.
- The **mainPath** property identifies critical workflow sequences for visual highlighting.

## Frequently Asked Questions

### What happens if schema_version is not set to 2?

The Archify CLI will reject the file or process it under legacy v1 rules. According to [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) lines 17–20, the integer value `2` is mandatory to activate the v2 layout compiler and its deterministic rendering pipeline.

### Can nodes exist outside the column 0–5 range?

No. The layout contract defined in [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) lines 55–101 constrains the `col` property to integers between 0 and 5 inclusive. This limitation ensures consistent horizontal spacing across all supported `visual_preset` styles.

### How does the layout compiler resolve edge routing conflicts?

The compiler in `archify/renderers/workflow/render-workflow.mjs` resolves conflicts using edge contract properties: `bias` adjusts curve tension, `route` selects strategies like `outside-right` or `bottom-channel`, and `via` arrays override automatic routing with explicit coordinates. The test suite in `archify/test/workflow-compiler.test.mjs` verifies these collision resolution behaviors.

### Where can I find real-world examples of v2 workflows?

The repository includes [`examples/agent-tool-call.workflow.json`](https://github.com/tt-a1i/archify/blob/main/examples/agent-tool-call.workflow.json), which demonstrates production usage of the layout contract with complex lane assignments, phase constraints, and mainPath highlighting. This file serves as the canonical reference for schema compliance and visual output expectations.