# How to Define States and Transitions in Archify Lifecycle Diagrams

> Learn how to define states and transitions in Archify lifecycle diagrams. Create a JSON file using the lifecycle schema to define typed states and directed transitions with unique IDs.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-07-15

---

**To define states and transitions in Archify lifecycle diagrams, create a JSON file that follows the [`lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/lifecycle.schema.json) specification, populating the top-level `states` array with typed node objects and the `transitions` array with directed edges that reference state IDs by their unique identifiers.**

Archify generates interactive lifecycle diagrams from strict JSON definitions validated against a formal schema. According to the `tt-a1i/archify` source code, the rendering engine expects a typed description containing three top-level arrays—`lanes`, `states`, and `transitions`—that together define the visual structure and logical flow of your state machine.

## Understanding the Core Schema Structure

Archify validates every lifecycle diagram against [`archify/schemas/lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json), which enforces strict typing and disallows additional properties to guarantee well-formed output. The schema requires three primary collections:

- **`lanes`** — Horizontal rails that group related states (e.g., main flow, waiting states, exceptions)
- **`states`** — Individual nodes representing each step in the state machine
- **`transitions`** — Directed edges that connect source states to target states

## Defining States with Required Properties

Each state object in the `states` array must include five required fields that determine its identity, visual type, and placement:

- **`id`** — A unique string identifier referenced by transitions
- **`type`** — The node category: `start`, `active`, `waiting`, `decision`, `success`, `failure`, `neutral`, or `external`
- **`label`** — The display text rendered inside the node
- **`lane`** — The identifier of the lane where the state appears
- **`col`** — Column index (0-4) controlling horizontal positioning within the lane

The `type` field controls the visual glyph: `start` renders as circles, `active` as rectangles, `waiting` as hourglasses, `decision` as diamonds, `success` as checkmarks, and `failure` as crosses.

Optional visual modifiers include `sublabel`, `tag`, `step`, `width`, `height`, and `yOffset` for fine-grained layout control.

## Configuring Transitions and Routing

Transitions define directed edges between states using the `transitions` array. Each transition requires two properties:

- **`from`** — The `id` of the source state
- **`to`** — The `id` of the target state

Beyond basic connectivity, Archify supports advanced routing controls in [`archify/schemas/lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json):

- **`route`** — Layout algorithm selection: `auto`, `straight`, `drop`, `bottom-channel`, `top-channel`, `right-channel`, or `left-channel`
- **`fromSide` / `toSide`** — Attachment points on the source and target nodes (`left`, `right`, `top`, `bottom`)
- **`via`** — Array of coordinate pairs `[[x, y], ...]` for custom polyline routing
- **`variant`** — Styling hint (e.g., `security`) that applies predefined visual treatments
- **`label`** — Text annotation rendered on the arrow
- **Fine-tuning** — `cornerRadius`, `width`, `labelAt`, `labelDx`, `labelDy`, and `labelSegment` for precise appearance control

## Complete Working Examples

### Minimal Lifecycle Definition

This example from the `tt-a1i/archify` repository demonstrates a basic three-state lifecycle with automatic routing:

```json
{
  "schema_version": 1,
  "diagram_type": "lifecycle",
  "meta": { "title": "Simple Lifecycle" },
  "lanes": [{ "id": "main", "label": "Main" }],
  "states": [
    { "id": "start", "type": "start",   "label": "Start",   "lane": "main", "col": 0 },
    { "id": "process","type": "active", "label": "Process", "lane": "main", "col": 1 },
    { "id": "end",   "type": "success", "label": "End",     "lane": "main", "col": 2 }
  ],
  "transitions": [
    { "from": "start",   "to": "process", "route": "auto" },
    { "from": "process", "to": "end",     "route": "auto" }
  ]
}

```

### Advanced Routing with Waiting States

The bundled [`archify/examples/agent-run.lifecycle.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/agent-run.lifecycle.json) illustrates complex routing between multiple lanes using explicit side attachments and custom paths:

```json
{
  "states": [
    { "id": "executing", "type": "active", "label": "Executing", "lane": "main", "col": 2, "step": "03" },
    { "id": "approval", "type": "waiting", "label": "Needs Approval", "lane": "waiting", "col": 0, "tag": "pause" },
    { "id": "blocked", "type": "failure", "label": "Blocked", "lane": "exceptions", "col": 0 }
  ],
  "transitions": [
    {
      "from": "executing",
      "to": "approval",
      "variant": "security",
      "fromSide": "bottom",
      "toSide": "top",
      "route": "straight"
    },
    {
      "from": "reviewing",
      "to": "blocked",
      "variant": "default",
      "route": "drop"
    },
    {
      "from": "executing",
      "to": "failed",
      "variant": "security",
      "fromSide": "left",
      "toSide": "top",
      "via": [[340, 342], [402, 342]]
    }
  ]
}

```

## Rendering Your Lifecycle Diagram

Once you have defined your states and transitions in a JSON file, generate the diagram using the Archify CLI:

```bash
archify.mjs render lifecycle definition.json output.html

```

The renderer processes your JSON through the validation schema and produces a self-contained HTML file at [`examples/lifecycle-agent-run.html`](https://github.com/tt-a1i/archify/blob/main/examples/lifecycle-agent-run.html) that embeds the SVG representation and interactive controls.

## Summary

- **Archify lifecycle diagrams** are defined via JSON following the strict [`lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/lifecycle.schema.json) specification located at [`archify/schemas/lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json)
- **States** require `id`, `type`, `label`, `lane`, and `col` properties, with types determining visual glyphs (circles, rectangles, diamonds, etc.)
- **Transitions** connect states using `from` and `to` ID references, supporting advanced routing via `route`, `fromSide`/`toSide`, and `via` coordinates
- **Validation** occurs against the schema before rendering, ensuring semantic correctness and visual consistency

## Frequently Asked Questions

### What JSON schema does Archify use to validate lifecycle diagrams?

Archify validates all lifecycle definitions against [`archify/schemas/lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json) in the `tt-a1i/archify` repository. This schema mandates strict typing for the `lanes`, `states`, and `transitions` arrays and disallows additional properties to prevent malformed diagrams.

### What are the required fields when defining a state in Archify?

Every state object must include five required fields: `id` (unique identifier), `type` (one of eight valid types including `start`, `active`, `waiting`, `decision`, `success`, `failure`, `neutral`, or `external`), `label` (display text), `lane` (grouping rail identifier), and `col` (column index 0-4). Missing any of these fields causes validation to fail.

### How do I customize the routing path of a transition between states?

Control transition routing using the `route` property (values: `auto`, `straight`, `drop`, `bottom-channel`, `top-channel`, `right-channel`, `left-channel`), specify attachment sides with `fromSide` and `toSide` (`left`, `right`, `top`, `bottom`), or define exact polyline coordinates using the `via` array containing `[x, y]` coordinate pairs as implemented in the schema at [`archify/schemas/lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json).

### Where can I find reference examples of Archify lifecycle definitions?

The `tt-a1i/archify` repository includes [`archify/examples/agent-run.lifecycle.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/agent-run.lifecycle.json), which demonstrates production-ready patterns including multi-lane layouts, diverse state types, and custom transition routing. The rendered output appears at [`examples/lifecycle-agent-run.html`](https://github.com/tt-a1i/archify/blob/main/examples/lifecycle-agent-run.html), showing how the JSON definitions translate to interactive SVG diagrams.