How to Create Lifecycle Diagrams with States and Terminal Outcomes in Archify

Archify's Lifecycle Renderer converts JSON definitions into interactive HTML diagrams by mapping states to specific lanes—main for phases, custom lanes for events, and terminal for final outcomes—using the schema defined in archify/schemas/lifecycle.schema.json.

Archify provides a specialized rendering pipeline for visualizing system lifecycles through structured JSON definitions. To create lifecycle diagrams with states and terminal outcomes in Archify, you define lanes, states, and transitions in a JSON file that conforms to the lifecycle schema, then process it through the dedicated CLI renderer. This approach generates clean, interactive HTML visualizations that clearly distinguish between ongoing phases, interrupting events, and final terminal states.

Understanding the Lifecycle Diagram Structure

Archify organizes lifecycle visualizations into three distinct horizontal bands. The top band contains phases mapped to the main lane, representing primary workflow stages like initialization or execution. The middle band hosts events and interruptions through custom lanes you define, while the bottom band displays terminal outcomes—success, failure, or neutral end states—through the reserved terminal lane.

This structure is enforced by the schema at [archify/schemas/lifecycle.schema.json](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json), which validates that your definition includes the required main and terminal lanes while allowing up to three additional event lanes in the middle band.

Configuring Lanes for States and Terminal Outcomes

The lane configuration determines how states are visually grouped and positioned in the final HTML output.

The Main Phase Lane

Every lifecycle diagram requires a lane with id: "main". This lane maps to the top Phase band and typically contains states of type start, active, or waiting that represent the primary workflow progression. States in this lane appear in the upper portion of the diagram, establishing the main horizontal flow of the lifecycle.

Event Lanes for Interruptions

You can define up to three additional lanes between main and terminal to represent interruptions, decisions, or recovery actions. These lanes use arbitrary IDs (such as interrupt or recover) and map to the middle Event band. States of type decision or external placed here visually separate transient actions from the main workflow, making complex branching logic easier to follow.

The Terminal Outcome Lane

To create terminal outcomes, you must include a lane with id: "terminal". This reserved lane maps to the bottom Outcome band and exclusively contains final states. Use state types success or failure here to represent definitive endpoints, or neutral for ambiguous conclusions. The renderer automatically positions these states at the diagram's base, creating clear visual exit points that distinguish final results from ongoing processes.

Defining States and Transitions

States require unique IDs, lane assignments, types, and labels. The type field determines both the visual styling and legend categorization—choose from start, active, waiting, decision, success, failure, neutral, or external. Optional x/y coordinates or col/yOffset values provide precise positioning control, though the renderer enforces minimum 10-pixel spacing between elements.

Transitions connect states using source and target IDs. You can specify routing presets like straight, drop, bottom-channel, or right-channel to control path geometry, or rely on auto-routing. The cornerRadius parameter (default 10) adjusts bend sharpness, and the renderer validates that transitions maintain at least 32-pixel lengths and avoid intersecting unrelated states when using the showcase quality profile.

Rendering the Diagram

Once your JSON definition is complete, use the Node.js renderer to generate the HTML visualization:

node archify/renderers/lifecycle/render-lifecycle.mjs input.lifecycle.json output.html

If you omit the output path, the renderer writes to the location specified in meta.output or defaults to lifecycle.html. For production-ready diagrams, set meta.quality_profile to "showcase" in your JSON to enforce stricter layout constraints, including prohibited line crossings and minimum segment lengths.

Complete Working Example

The following example from [archify/examples/agent-run.lifecycle.json](https://github.com/tt-a1i/archify/blob/main/archify/examples/agent-run.lifecycle.json) demonstrates a full lifecycle with phases, interruption handling, recovery, and terminal outcomes:

{
  "schema_version": 1,
  "diagram_type": "lifecycle",
  "meta": {
    "title": "Agent Run Lifecycle",
    "subtitle": "Phases, interruptions, recovery, and terminal exits",
    "viewBox": [980, 660],
    "quality_profile": "showcase"
  },
  "lanes": [
    { "id": "main", "label": "Phase" },
    { "id": "interrupt", "label": "Interrupt" },
    { "id": "recover", "label": "Recover" },
    { "id": "terminal", "label": "Outcome" }
  ],
  "states": [
    { "id": "s1", "lane": "main", "type": "start", "label": "01 Init", "col": 0 },
    { "id": "s2", "lane": "main", "type": "active", "label": "02 Run", "col": 1 },
    { "id": "s3", "lane": "interrupt", "type": "decision", "label": "Pause?", "col": 0 },
    { "id": "s4", "lane": "recover", "type": "active", "label": "Resume", "col": 0 },
    { "id": "s5", "lane": "terminal", "type": "success", "label": "Complete", "col": 0 },
    { "id": "s6", "lane": "terminal", "type": "failure", "label": "Error", "col": 1 }
  ],
  "transitions": [
    { "source": "s1", "target": "s2", "preset": "straight" },
    { "source": "s2", "target": "s3", "preset": "drop" },
    { "source": "s3", "target": "s4", "preset": "straight" },
    { "source": "s4", "target": "s2", "preset": "bottom-channel" },
    { "source": "s2", "target": "s5", "preset": "right-channel" },
    { "source": "s2", "target": "s6", "preset": "right-channel" }
  ],
  "cards": [
    {
      "id": "c1",
      "state": "s2",
      "title": "Run Details",
      "body": "Processing data, invoking sub-agents..."
    }
  ]
}

Render this example using:

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

Summary

• Archify lifecycle diagrams use a JSON schema defined in archify/schemas/lifecycle.schema.json to generate interactive HTML visualizations.
• Three horizontal bands organize content: main lane for phases (top), custom lanes for events (middle), and terminal lane for outcomes (bottom).
• Terminal outcomes require states of type success or failure placed in the terminal lane to create definitive visual endpoints.
• Transitions support routing presets (straight, drop, bottom-channel) and configurable cornerRadius for clean path visualization.
• Rendering occurs via archify/renderers/lifecycle/render-lifecycle.mjs, which accepts input JSON and outputs HTML with optional showcase quality enforcement.

Frequently Asked Questions

What file validates the structure of a lifecycle diagram in Archify?

The JSON schema at archify/schemas/lifecycle.schema.json enforces all structural requirements, including mandatory diagram_type set to "lifecycle", required main and terminal lanes, and valid state type enumerations.

How do I specify where a state appears in the diagram's vertical layout?

Assign the lane property to each state using one of your defined lane IDs. States in the main lane appear in the top band, states in terminal appear in the bottom band, and states in any other custom lane occupy the middle event band.

Can I render a lifecycle diagram without specifying an output filename?

Yes. If you omit the output argument from the CLI command, the renderer checks meta.output in your JSON definition, and if that's absent, it defaults to writing lifecycle.html in the current working directory.

What is the difference between active and decision state types?

The active type represents ongoing processes or tasks and renders with distinct styling in the phase or event bands, while the decision type indicates branching points or conditional logic, typically used in event lanes to show where the workflow may diverge based on specific conditions.

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