How to Use Archify for Lifecycle Diagrams: A Complete Guide

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. 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

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:

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

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

<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

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

{
  "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	JSON Schema defining valid lifecycle structure
archify/renderers/lifecycle/README.md	Quick-start documentation
archify/examples/agent-run.lifecycle.json	Production-ready example with waiting and recovery states
docs/start.html	Web UI entry point with lifecycle tab
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
• 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, 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. 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, 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 when you select the Lifecycle diagram type.

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