# How Archify Lifecycle Diagrams Represent State Machines with Wait States, Retries, and Terminal States

> Learn how Archify lifecycle diagrams visualize state machines using semantic lanes and strict state types for pauses retries and terminal exits Get a clear view of execution flows.

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

---

**Archify lifecycle diagrams use a JSON-IR schema with semantic lanes (`main`, `waiting`, `exceptions`, `terminal`) and strict state type classifications to visually separate active execution flows from pauses, retry loops, and terminal exits.**

The `tt-a1i/archify` repository provides a specialized renderer that transforms structured JSON intermediate representations into clean, horizontally-oriented state machine diagrams. By enforcing the schema defined in [`archify/schemas/lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json), the tool creates clear visual distinctions between transient execution states, blocking wait conditions, recoverable failures, and final termination points.

## The Lane-Based Schema Architecture

Archify organizes state machines into **lanes**—logical groupings that control horizontal positioning and semantic meaning. The schema defines lanes in an array of objects with `id` and `label` properties (lines 63-84 in [`archify/schemas/lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json)).

Standard lane configurations include:

- **`main`**: Contains the primary execution rail with `start`, `active`, and `decision` state types
- **`waiting`**: Isolates pause states that suspend execution without ending the process  
- **`exceptions`**: Houses recoverable failure states and retry logic
- **`terminal`**: Dedicated to final exit states with no outgoing transitions

Each state declares its lane assignment via the `lane` property, while the `col` property determines left-to-right ordering within the lane. The schema enforces that all `lane` values must reference entries in the top-level `lanes` array.

State semantics are controlled by the `type` enum, which includes `start`, `active`, `waiting`, `decision`, `success`, `failure`, `neutral`, and `external` (lines 101-113 in [`lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/lifecycle.schema.json)). These types govern visual styling and validation rules during rendering.

## Modeling Wait States

Wait states represent execution pauses where the system awaits external input or conditions. To define a wait state, set `type: "waiting"` and place the state in the `waiting` lane, as demonstrated in [`archify/examples/agent-run.lifecycle.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/agent-run.lifecycle.json) (lines 22-24).

```json
{
  "id": "approval",
  "type": "waiting",
  "label": "Needs Approval",
  "lane": "waiting",
  "col": 0
}

```

The renderer visually separates these states from the main execution rail, creating a distinct track that indicates suspension without termination. Transitions from wait states typically lead back to `active` states in the main lane or to terminal exits, but never create cycles that bypass the wait condition.

## Implementing Retry Loops and Recovery

Retry logic is modeled through **failure states** with `type: "failure"` placed in the `exceptions` lane. These states represent recoverable errors that can transition back to earlier active states, forming visual retry loops. The transition object supports a `via` property defining coordinate arrays for routing arrows and a `variant` property for styling distinctions.

In [`archify/examples/agent-run.lifecycle.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/agent-run.lifecycle.json) (lines 24-26), a failure state is defined as:

```json
{
  "id": "failed",
  "type": "failure",
  "label": "Failed",
  "lane": "exceptions",
  "col": 0
}

```

Transitions back to the main lane create recovery paths. For example, a transition from `failed` to `planning` with a `via` route draws a curved arrow indicating the retry flow:

```json
{
  "from": "failed",
  "to": "planning",
  "variant": "security",
  "via": [[300, 200], [300, 100]]
}

```

The renderer applies "recoverable error" styling to these paths, distinguishing them from terminal failures.

## Configuring Terminal States

Terminal states represent non-recoverable endings and reside exclusively in the `terminal` lane. They require the `tag: "terminal"` property and use either `type: "failure"` or `type: "success"` depending on the exit condition (lines 25-27 in [`agent-run.lifecycle.json`](https://github.com/tt-a1i/archify/blob/main/agent-run.lifecycle.json)).

```json
{
  "id": "cancelled",
  "type": "failure",
  "label": "Cancelled",
  "lane": "terminal",
  "col": 0,
  "tag": "terminal"
}

```

The renderer enforces that terminal states have **no outgoing edges**, making them strict visual endpoints. The schema validation ensures that no transitions originate from states carrying the `tag: "terminal"` property, preventing invalid state machine definitions.

## Rendering the Diagram

To generate the SVG visualization, execute `archify/renderers/lifecycle/render-lifecycle.mjs` with the JSON-IR input file and desired HTML output path:

```bash
node archify/renderers/lifecycle/render-lifecycle.mjs \
  archify/examples/agent-run.lifecycle.json \
  examples/lifecycle-agent-run.html

```

The renderer processes the lane definitions to create a **phase-map layout**, arranging the main execution rail horizontally while positioning waiting, exception, and terminal states in parallel tracks. This produces an uncluttered visualization that clearly differentiates the happy path from alternative flows.

Complete example combining all three concepts:

```json
{
  "schema_version": 1,
  "diagram_type": "lifecycle",
  "meta": {
    "title": "Simple Order Lifecycle",
    "viewBox": [800, 400]
  },
  "lanes": [
    { "id": "main", "label": "Process" },
    { "id": "waiting", "label": "Pauses" },
    { "id": "exceptions", "label": "Recovery" },
    { "id": "terminal", "label": "Exit" }
  ],
  "states": [
    { "id": "new", "type": "start", "label": "New", "lane": "main", "col": 0 },
    { "id": "pay", "type": "active", "label": "Pay", "lane": "main", "col": 1 },
    { "id": "review", "type": "waiting", "label": "Review", "lane": "waiting", "col": 0 },
    { "id": "failed", "type": "failure", "label": "Failed", "lane": "exceptions", "col": 0 },
    { "id": "cancel", "type": "failure", "label": "Cancelled", "lane": "terminal", "col": 0, "tag": "terminal" }
  ],
  "transitions": [
    { "from": "new", "to": "pay", "variant": "default" },
    { "from": "pay", "to": "review", "variant": "default" },
    { "from": "pay", "to": "failed", "variant": "default", "via": [[300, 200]] },
    { "from": "review", "to": "cancel", "variant": "default" }
  ]
}

```

## Summary

- **Archify lifecycle diagrams** use a strict JSON-IR schema to model state machines with four semantic lanes: `main`, `waiting`, `exceptions`, and `terminal`.
- **Wait states** use `type: "waiting"` and reside in the `waiting` lane to visually separate execution pauses from active flow.
- **Retry logic** is implemented via `failure` type states in the `exceptions` lane with transitions looping back to active states using the `via` routing property.
- **Terminal states** require `tag: "terminal"` and placement in the `terminal` lane, with the renderer enforcing zero outgoing transitions.
- The `render-lifecycle.mjs` tool transforms these definitions into horizontal SVG diagrams with distinct visual tracks for each lane type.

## Frequently Asked Questions

### How does Archify distinguish between a temporary pause and a permanent failure?

Archify uses **state types** and **lane assignment** to differentiate these conditions. A temporary pause is a state with `type: "waiting"` placed in the `waiting` lane, indicating the process awaits external input. A permanent failure uses `type: "failure"` with `tag: "terminal"` in the `terminal` lane, signaling that no recovery transitions are permitted.

### Can a terminal state transition to another state in Archify lifecycle diagrams?

No. The schema enforces that terminal states have **no outgoing edges**. When a state includes `tag: "terminal"` and resides in the `terminal` lane, the renderer automatically disables outgoing transitions, making it a strict endpoint. This validation prevents invalid state machine definitions where a process could exit and then resume.

### What properties control the visual routing of retry arrows in Archify?

The `via` property in transition objects defines coordinate arrays for routing retry arrows around other states. Additionally, the `variant` property applies distinct styling classes (such as "security" or "default") to visually distinguish retry paths from standard transitions in the rendered SVG output.

### Where is the formal schema definition for Archify lifecycle diagrams?

The formal JSON Schema is located at [`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 file defines the `lanes` array structure (lines 63-84), the `type` enum for state classifications (lines 101-113), and validation rules for transitions and state properties.