# How State Transitions Are Rendered in Archify Lifecycle Diagrams

> Discover how Archify renders state transitions in lifecycle diagrams using directed edges and `transitions` array. Learn to define `from`, `to`, and routing controls for exact visual layout.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: internals
- Published: 2026-07-13

---

**State transitions in Archify lifecycle diagrams are rendered as directed edges defined within the `transitions` array of a typed JSON description, requiring `from` and `to` state IDs and supporting optional routing controls like `route`, `fromSide`, `toSide`, and `via` points for precise visual layout.**

Archify renders **lifecycle diagrams** from a strictly typed JSON description defined in [`lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/lifecycle.schema.json). The schema mandates three top-level arrays—`lanes`, `states`, and `transitions`—where the `transitions` array specifically governs how state changes are visualized as directed edges between nodes.

## Understanding the Lifecycle Schema Structure

### The Three Core Arrays

According to [`archify/schemas/lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json), every lifecycle diagram must define three properties:

- **lanes**: Horizontal rails that group related states (e.g., main flow, waiting states, exceptions).
- **states**: Individual nodes containing `id`, `type`, `label`, `lane`, and `col` properties.
- **transitions**: Directed edges connecting states that control the visual flow between nodes.

The schema enforces strict typing and disallows additional properties, guaranteeing that every diagram is well-formed before rendering.

## Defining State Transitions in Archify

### Required Transition Properties

Every transition object must reference existing state IDs:

- **`from`**: The source state ID.
- **`to`**: The target state ID.

### Optional Routing and Styling Controls

The schema provides extensive optional fields for controlling visual appearance:

- **`route`**: Layout algorithm selection (`auto`, `straight`, `drop`, `bottom-channel`, `top-channel`, `right-channel`, `left-channel`).
- **`fromSide` / `toSide`**: Attachment points on nodes (`left`, `right`, `top`, `bottom`).
- **`via`**: Array of intermediate points for custom polylines (e.g., `[[340,342],[402,342]]`).
- **`variant`**: Styling hint for categories like `security`.
- **`label`**: Text displayed on the arrow.
- **Fine-grained controls**: `cornerRadius`, `width`, `labelAt`, `labelDx`, `labelDy`, `labelSegment`.

## Visual State Types and Their Connections

### State Types That Influence Diagrams

The `type` property in states affects how transition endpoints appear:

- **`start`**: Entry circles.
- **`active`**: Process rectangles.
- **`waiting`**: Hourglass shapes for paused states.
- **`decision`**: Diamond shapes for branching logic.
- **`success`** / **`failure`**: Terminal checkmarks or crosses.
- **`neutral`** / **`external`**: Alternative node styles for special cases.

### Rendering Implementation

The rendering logic in `archify/renderers/workflow/render-workflow.mjs` consumes the JSON intermediate representation to produce self-contained HTML/SVG output, applying the routing algorithms specified in each transition's `route` property.

## Practical Code Examples

### Basic Sequential Flow

This minimal example from [`archify/examples/agent-run.lifecycle.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/agent-run.lifecycle.json) demonstrates standard state progression:

```json
{
  "schema_version": 1,
  "diagram_type": "lifecycle",
  "meta": { "title": "Simple Lifecycle" },
  "lanes": [{ "id": "main", "label": "Main" }],
  "states": [
    { "id": "queued",   "type": "start",    "label": "Queued",   "lane": "main", "col": 0, "step": "01", "tag": "entry" },
    { "id": "planning", "type": "active",   "label": "Planning", "lane": "main", "col": 1, "step": "02", "tag": "model" },
    { "id": "executing","type": "active",   "label": "Executing","lane": "main", "col": 2, "step": "03", "tag": "work"  },
    { "id": "reviewing","type": "decision", "label": "Reviewing","lane": "main", "col": 3, "step": "04", "tag": "check" },
    { "id": "completed","type": "success",  "label": "Completed","lane": "main", "col": 4, "step": "05", "tag": "done"  }
  ],
  "transitions": [
    { "from": "queued",    "to": "planning", "route": "auto" },
    { "from": "planning",  "to": "executing","route": "auto" },
    { "from": "executing", "to": "reviewing","route": "auto" },
    { "from": "reviewing", "to": "completed","route": "auto" }
  ]
}

```

### Advanced Routing with Waiting States

This example illustrates complex routing between lanes using `fromSide`, `toSide`, and custom `via` points:

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

```

To render these definitions, use the Archify CLI:

```bash
archify.mjs render lifecycle <file>.json <output>.html

```

## Summary

- Archify lifecycle diagrams are defined in **JSON** following the strict [`lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/lifecycle.schema.json) specification.
- **Transitions** are directed edges stored in the `transitions` array, requiring `from` and `to` state IDs.
- **Routing options** include `auto`, `straight`, `drop`, and channel-based algorithms (`bottom-channel`, `top-channel`, `right-channel`, `left-channel`).
- **Attachment points** are controlled via `fromSide` and `toSide` properties (`left`, `right`, `top`, `bottom`).
- **Custom polylines** can be defined using the `via` array for precise path control.
- The renderer in `archify/renderers/workflow/render-workflow.mjs` processes these definitions into self-contained HTML/SVG output.

## Frequently Asked Questions

### What file defines the schema for Archify lifecycle transitions?

The schema is formally defined in [`archify/schemas/lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json). This file specifies the required properties for `lanes`, `states`, and `transitions`, including the optional routing controls like `route`, `fromSide`, and `via`.

### How do I create a transition between a waiting state and an active state?

Define the waiting state with `"type": "waiting"` in the `states` array, then create a transition object with `"from": "active-state-id"` and `"to": "waiting-state-id"`. Specify `fromSide` and `toSide` (e.g., `"right"` and `"left"`) to control which sides of the nodes connect, and set `"route": "straight"` or `"drop"` depending on your layout needs.

### Can I customize the path routing between two states?

Yes. Use the `via` property to specify an array of intermediate coordinate pairs (e.g., `"via": [[340,342],[402,342]]`) for custom polylines. Alternatively, use the `route` property to select predefined algorithms like `bottom-channel` or `straight`, and adjust `cornerRadius` for rounded corners.

### What command-line tool renders these diagrams?

Use `archify.mjs render lifecycle <input>.json <output>.html` to process the JSON definition and generate a self-contained HTML file. The rendered output, as seen in [`archify/examples/lifecycle-agent-run.html`](https://github.com/tt-a1i/archify/blob/main/archify/examples/lifecycle-agent-run.html), visually represents the states and transitions defined in your JSON configuration.