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

> Explore Archify's structural arrays for lifecycle diagrams: lanes states transitions and cards. Understand the complete schema reference for diagram geometry flow and interactions.

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

---

**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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json) (lines 262-265) and referencing the generic cards definition in [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/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:

```json
{
  "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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json) and referencing [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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).