How State Transitions Are Rendered in Archify Lifecycle Diagrams

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. 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, 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 demonstrates standard state progression:

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

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

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

Summary

• Archify lifecycle diagrams are defined in JSON following the strict 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. 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, visually represents the states and transitions defined in your JSON configuration.

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