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

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, 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).

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). 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 (lines 22-24).

{
  "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 (lines 24-26), a failure state is defined as:

{
  "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:

{
  "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).

{
  "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:

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:

{
  "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 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.

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