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

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 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 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 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:

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

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

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