How to Define States and Transitions in Archify Lifecycle Diagrams

To define states and transitions in Archify lifecycle diagrams, create a JSON file that follows the 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, 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:

• 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:

{
  "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 illustrates complex routing between multiple lanes using explicit side attachments and custom paths:

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

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 that embeds the SVG representation and interactive controls.

Summary

• Archify lifecycle diagrams are defined via JSON following the strict lifecycle.schema.json specification located at 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 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.

Where can I find reference examples of Archify lifecycle definitions?

The tt-a1i/archify repository includes 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, showing how the JSON definitions translate to interactive SVG diagrams.

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