# How to Use Archify for Lifecycle Diagrams: A Complete Guide

> Learn how to use Archify for lifecycle diagrams. This guide shows you how to convert JSON descriptions into interactive HTML diagrams with validation and animation.

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

---

**Archify converts JSON lifecycle descriptions into interactive HTML diagrams with built-in validation, keyboard navigation, and animated playback.**

The **Archify** open-source project provides a specialized rendering pipeline for visualizing system lifecycles as horizontal rail diagrams. This guide covers both the command-line renderer and the web UI, with complete examples from the `tt-a1i/archify` source code.

---

## Understanding Lifecycle Diagrams in Archify

A **lifecycle diagram** visualizes high-level process phases on a single horizontal rail. Typical flows include *queued → planning → executing → reviewing → completed*, with optional side rails for waiting states, failure-recovery paths, or cancellation branches.

The renderer organizes content into three vertical bands:

- **Primary phase band** (top): The `main` lane containing core progression states
- **Middle event band**: Custom lanes for intermediate events
- **Outcome band** (bottom): The `terminal` lane for final states

This layout is controlled by hard-coded constants in `archify/renderers/lifecycle/render-lifecycle.mjs` (lines 48-60): `phaseY`, `eventY`, `outcomeY`, and `phaseXs`.

---

## Authoring a Lifecycle JSON File

All lifecycle diagrams begin with a JSON file conforming to [`archify/schemas/lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json). The schema requires three top-level keys:

| Key | Purpose |
| --- | --- |
| `lanes` | Groups of states (`main`, `terminal`, or custom identifiers) |
| `states` | Individual nodes with `id`, `type`, and optional `label`/`note` |
| `transitions` | Directed edges connecting states with optional `label` and `type` |

### State Types Available

- `start` — Initial state (typically in `main` lane)
- `active` — Processing states
- `waiting` — Paused or blocked states
- `decision` — Branching points
- `success` / `failure` / `neutral` — Terminal outcomes
- `external` — External system references

Style classes map these types to color tokens (`c-frontend`, `c-backend`, `c-cloud`) and text classes (`t-frontend`, `t-backend`) defined in lines 63-82 of `render-lifecycle.mjs`.

---

## Rendering from the Command Line

The Node.js renderer validates your JSON against the schema and produces a standalone HTML file.

### Basic Usage

```bash
node archify/renderers/lifecycle/render-lifecycle.mjs \
     path/to/your.lifecycle.json \
     path/to/output.html

```

The script performs three operations:

1. **Validates** input using `throwDiagnosticProblems` (line 14) against the lifecycle schema
2. **Computes layout** with fixed positioning constants
3. **Writes HTML** containing accessible SVG, legend, and interactive controls

### Minimal Example

Create [`minimal.lifecycle.json`](https://github.com/tt-a1i/archify/blob/main/minimal.lifecycle.json):

```json
{
  "diagram_type": "lifecycle",
  "lanes": [
    { "id": "main", "label": "Phase" },
    { "id": "terminal", "label": "Outcome" }
  ],
  "states": [
    { "id": "queued", "type": "start",  "label": "Queued" },
    { "id": "planning", "type": "active", "label": "Planning" },
    { "id": "executing", "type": "active", "label": "Executing" },
    { "id": "reviewing", "type": "decision", "label": "Reviewing" },
    { "id": "completed", "type": "success", "label": "Completed" }
  ],
  "transitions": [
    { "from": "queued",   "to": "planning" },
    { "from": "planning", "to": "executing" },
    { "from": "executing","to": "reviewing" },
    { "from": "reviewing","to": "completed" }
  ]
}

```

Render and open:

```bash
node archify/renderers/lifecycle/render-lifecycle.mjs \
     minimal.lifecycle.json \
     minimal.html
open minimal.html

```

---

## Using the Web UI Alternative

The main entry point at [`docs/start.html`](https://github.com/tt-a1i/archify/blob/main/docs/start.html) provides a browser-based interface with pre-loaded samples.

### How the Web UI Works

The page contains a dropdown of diagram types. Selecting **Lifecycle** injects configuration data via a script element:

```html
<script id="start-data" type="application/json">
{
  "lifecycle": {
    "id":"agent-run",
    "type":"lifecycle",
    "proof":"agent-run",
    "presentation":{ "preset":"classic", "motion":"static", "views":"optional" },
    "en":{ 
      "title":"Agent run lifecycle", 
      "question":"How does an agent progress from request to response?" 
    }
  }
}
</script>

```

The UI embeds the same renderer logic found in `render-lifecycle.mjs`. To display your own lifecycle, replace the script content with your diagram configuration.

### Self-Hosted Example

```html
<!DOCTYPE html>
<html>
<head>
  <title>My Lifecycle</title>
  <script src="https://tt-a1i.github.io/archify/start.js" defer></script>
</head>
<body>
  <script id="archify-guided-views-data" type="application/json">
  [
    {
      "id":"my-process",
      "type":"lifecycle",
      "focus":["queued","planning","executing","reviewing","completed"],
      "note":"Simple request-response flow"
    }
  ]
  </script>
</body>
</html>

```

Open the file, click the **Lifecycle** tab, and Archify renders your diagram immediately.

---

## Adding Failure-Recovery Paths

Side rails become essential when modeling error handling. This example adds a failure-recovery loop:

```json
{
  "lanes": [
    { "id": "main", "label": "Phase" },
    { "id": "recovery", "label": "Recovery" }
  ],
  "states": [
    { "id":"executing", "type":"active", "label":"Executing" },
    { "id":"failed",    "type":"failure","label":"Failed", "lane":"recovery" },
    { "id":"retry",     "type":"active", "label":"Retry", "lane":"recovery" }
  ],
  "transitions": [
    { "from":"executing", "to":"failed",  "type":"failure", "label":"error" },
    { "from":"failed",    "to":"retry",   "type":"default", "label":"retry" },
    { "from":"retry",     "to":"executing","type":"default" }
  ]
}

```

The renderer draws a branch from the main rail to the recovery lane and back, creating a clear visual of the resilience pattern.

---

## Interactive Features in Generated Diagrams

Both the CLI and web outputs provide identical interaction capabilities:

| Shortcut | Action |
| --- | --- |
| `R` | Route/trace the lifecycle flow |
| `+` / `-` | Zoom in/out |
| `M` | Toggle radar/overview view |
| `P` | Play animation |
| `T` | Toggle theme |
| `E` | Export diagram |

**Hover-to-trace** highlights the complete path through states. The **clickable legend** filters by state type (e.g., `c-frontend` for start states).

---

## Key Source Files for Lifecycle Diagrams

| File | Purpose |
| --- | --- |
| `archify/renderers/lifecycle/render-lifecycle.mjs` | Core Node renderer with validation, layout, and HTML generation |
| [`archify/schemas/lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json) | JSON Schema defining valid lifecycle structure |
| [`archify/renderers/lifecycle/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/renderers/lifecycle/README.md) | Quick-start documentation |
| [`archify/examples/agent-run.lifecycle.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/agent-run.lifecycle.json) | Production-ready example with waiting and recovery states |
| [`docs/start.html`](https://github.com/tt-a1i/archify/blob/main/docs/start.html) | Web UI entry point with lifecycle tab |
| [`README.md`](https://github.com/tt-a1i/archify/blob/main/README.md) | Project overview with lifecycle screenshot |

---

## Summary

- **Archify lifecycle diagrams** require JSON input with `lanes`, `states`, and `transitions` keys, validated against [`lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/lifecycle.schema.json)
- **Command-line rendering** uses `render-lifecycle.mjs`, which applies fixed layout constants and outputs standalone HTML
- **Web UI rendering** loads the same engine via [`start.html`](https://github.com/tt-a1i/archify/blob/main/start.html), accepting configuration through script elements
- **Interaction features** include keyboard shortcuts, hover-tracing, theme switching, and animated playback
- **Failure-recovery patterns** use additional lanes placed in the middle event band between primary phases and terminal outcomes

---

## Frequently Asked Questions

### What JSON schema does Archify use for lifecycle validation?

Archify validates all lifecycle files against [`archify/schemas/lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json). This schema mandates three top-level properties: `lanes` (state groups), `states` (nodes with typed identifiers), and `transitions` (directed edges). The renderer calls `throwDiagnosticProblems` at line 14 of `render-lifecycle.mjs` to surface validation errors with diagnostics.

### Can I customize the vertical positioning of lanes in a lifecycle diagram?

No. The renderer uses hard-coded constants (`phaseY`, `eventY`, `outcomeY`) in lines 48-60 of `render-lifecycle.mjs`. The `main` lane always renders in the primary phase band (top), `terminal` in the outcome band (bottom), and all other lanes in the middle event band. This fixed layout ensures consistent visual language across all Archify diagrams.

### How do I add keyboard navigation to my lifecycle diagram?

Keyboard shortcuts are automatically included in all HTML output. Press `R` to trace routes, `P` to play animations, `T` to toggle themes, and `E` to export. These bindings require no additional configuration—they are injected by `render-lifecycle.mjs` during HTML generation.

### Where can I find a complete production example of an Archify lifecycle?

The repository includes [`archify/examples/agent-run.lifecycle.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/agent-run.lifecycle.json), which demonstrates an agent-run lifecycle with phases, waiting states, and recovery paths. This file is also pre-loaded in the web UI at [`docs/start.html`](https://github.com/tt-a1i/archify/blob/main/docs/start.html) when you select the Lifecycle diagram type.