Structural Arrays for Lifecycle Diagrams in Archify: The Complete Schema Reference

Archify defines lifecycle diagrams using three mandatory JSON arrays—lanes, states, and transitions—plus an optional cards array, all validated against the lifecycle schema to control diagram geometry, flow, and interactive elements.

The tt-a1i/archify repository renders interactive lifecycle diagrams through a strict schema-driven architecture. To author valid diagrams, you must understand the specific structural arrays declared in archify/schemas/lifecycle.schema.json that govern how the render-lifecycle.mjs engine parses and visualizes diagram data.

The Core Structural Arrays

Archify lifecycle diagrams require four distinct array structures within the JSON payload. Three are mandatory for geometric layout, while the fourth enables supplemental UI components.

The lanes Array

The lanes array defines horizontal tracks that group related states, such as "User" or "System" swimlanes. According to the schema in archify/schemas/lifecycle.schema.json (lines 94-111), each lane object must contain:

• id: A unique string identifier referenced by states
• label: The display name rendered on the diagram

Lanes provide the vertical scaffolding that organizes states into logical partitions across the horizontal axis.

The states Array

The states array contains individual nodes positioned at specific lane and column intersections. Defined in archify/schemas/lifecycle.schema.json (lines 115-167), each state requires:

• id: Unique identifier string
• type: Enum value determining visual styling (e.g., start, active, waiting, success)
• label: Display text for the node
• lane: Reference to a lane id for vertical positioning
• col: Integer index for horizontal placement

Optional geometry fields include width, height, and yOffset for fine-tuned positioning within the lane.

The transitions Array

The transitions array defines directed edges connecting states. As specified in archify/schemas/lifecycle.schema.json (lines 182-260), each transition requires:

• from: Source state id
• to: Target state id

Optional routing controls include label, variant, and routing hints such as route (e.g., "auto"), fromSide, toSide, and via for custom path geometry.

The Optional cards Array

The cards array attaches supplemental UI panels to the diagram, such as detailed notes or contextual tooltips. Defined in archify/schemas/lifecycle.schema.json (lines 262-265) and referencing the generic cards definition in common.schema.json, this array enables rich contextual data without affecting core diagram geometry.

Rendering Implementation

The archify/renderers/lifecycle/render-lifecycle.mjs module processes these arrays sequentially. It first calculates lane geometries from the lanes array, positions nodes according to states coordinates, then draws SVG paths based on transitions routing hints. When present, the renderer injects cards as HTML overlays alongside the SVG canvas.

Practical JSON Example

The following minimal payload demonstrates the three required structural arrays in a valid lifecycle configuration. This example can be passed directly to render-lifecycle.mjs or validated against the schema:

{
  "schema_version": 1,
  "diagram_type": "lifecycle",
  "meta": { "title": "Sample Lifecycle" },
  "lanes": [
    { "id": "user", "label": "User" },
    { "id": "system", "label": "System" }
  ],
  "states": [
    { "id": "s0", "type": "start",   "label": "Queued",          "lane": "user",   "col": 0 },
    { "id": "s1", "type": "active",  "label": "Planning",        "lane": "system", "col": 1 },
    { "id": "s2", "type": "waiting", "label": "Approval",        "lane": "system", "col": 2 },
    { "id": "s3", "type": "success", "label": "Completed",       "lane": "system", "col": 3 }
  ],
  "transitions": [
    { "from": "s0", "to": "s1", "route": "auto" },
    { "from": "s1", "to": "s2", "route": "auto" },
    { "from": "s2", "to": "s3", "route": "auto" }
  ]
}

For a comprehensive implementation including the cards array, reference the fixture file at archify/test/fixtures/v1-baseline/agent-run.lifecycle.json.

Summary

• Three mandatory arrays: lanes define horizontal tracks, states position typed nodes on those tracks, and transitions draw directed edges between states.
• Schema location: All structural arrays are formally defined in archify/schemas/lifecycle.schema.json with specific line ranges for each component.
• Optional enrichment: The cards array adds UI panels without affecting core diagram geometry.
• Rendering entry point: The render-lifecycle.mjs module interprets these arrays to generate the final SVG/HTML output.

Frequently Asked Questions

What are the required fields for a state in Archify lifecycle diagrams?

Each state must include id, type, label, lane, and col fields. The type field accepts enum values like start, active, waiting, or success that determine the node's visual styling, while lane must reference a valid lane id defined in the same document.

How does Archify handle routing between states?

Archify supports both automatic and manual routing through the transitions array. Set route: "auto" for algorithmic path calculation, or specify fromSide, toSide, and via coordinates to force specific connection geometries between state nodes.

Can I include metadata panels alongside lifecycle diagrams?

Yes. The optional cards array, defined in archify/schemas/lifecycle.schema.json and referencing common.schema.json, allows you to attach supplemental UI panels containing detailed notes, tooltips, or contextual data that render alongside the main diagram canvas.

Where is the lifecycle schema formally defined?

The canonical schema resides in archify/schemas/lifecycle.schema.json within the tt-a1i/archify repository. This file specifies the exact structure for lanes (lines 94-111), states (lines 115-167), transitions (lines 182-260), and the optional cards array (lines 262-265).

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