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

> Learn to create lifecycle diagrams with states and terminal outcomes in Archify. Visualize your system's progress through interactive HTML diagrams using custom lanes and defined schemas.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-08-08

---

**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`](https://github.com/tt-a1i/archify/blob/main/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)](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:

```bash
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`](https://github.com/tt-a1i/archify/blob/main/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)](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:

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

```bash
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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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.