# How to Use Archify Lifecycle Diagrams for Agent Run Visualization

> Visualize autonomous agent workflows with Archify lifecycle diagrams. Explore interactive state machines rendered to SVG with guided views and keyboard navigation.

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

---

**Archify lifecycle diagrams visualize autonomous agent workflows as interactive state machines using a JSON intermediate representation rendered to SVG, supporting guided views, keyboard navigation, and export to multiple formats.**

Archify lifecycle diagrams provide a structured way to model and explore the complete state machine of an autonomous agent run. The open-source `tt-a1i/archify` repository provides the rendering engine and JSON schema needed to transform workflow definitions into interactive visualizations. By configuring lanes, states, and transitions in a JSON IR file, you can generate guided views that track an agent from initial queuing through planning, execution, and terminal outcomes.

## Understanding Lifecycle Diagram Components

Archify lifecycle diagrams organize agent runs into distinct visual components that map directly to state machine concepts. The diagram separates logical concerns into horizontal lanes while encoding workflow logic through typed states and directed transitions.

### Lanes, States, and Transitions

The diagram structure consists of four core elements defined in the JSON IR:

- **Lanes** – Horizontal rails that group related states logically (e.g., the main lifecycle rail, interruption lanes for approval or blocked states, and recovery loops)
- **States** – Nodes representing each phase with specific visual types: `start`, `active`, `waiting`, `failure`, `success`, or `decision`
- **Transitions** – Directed edges connecting states that support visual variants including `default`, `security` (for approval gates), and `emphasis` (for retry loops)
- **Cards** – Inline documentation panels that summarize logical areas such as the main path, human input gates, or terminal recovery states

### Guided Views and Navigation

**Guided views** are pre-defined chapters that focus the viewer on specific paths through the lifecycle. These views filter the diagram to highlight subsets like the main linear flow, human-in-the-loop wait states, or recovery and terminal exits. Views are defined in the JSON `views` array and accessed via the UI panel or keyboard shortcuts.

## Configuring the JSON Intermediate Representation

All diagram content originates from a JSON IR (intermediate representation) file that Archify's client-side engine parses into interactive SVG.

### Key Schema Fields

Every lifecycle diagram JSON must specify `diagram_type: "lifecycle"` to trigger the correct rendering preset. The essential structure includes:

- `lanes` – Array of lane objects with `id` and `label` properties
- `states` – Array of node objects requiring `id`, `type` (visual classification), `label` (display text), and `lane` (parent rail)
- `transitions` – Array of connection objects with `from`, `to`, and optional `variant` properties
- `views` – Array of guided view definitions with `id`, `label`, `focus` (array of state IDs to highlight), and `note` fields

### Defining States and Transitions

States represent distinct phases in [`docs/gallery/sources/agent-run.lifecycle.json`](https://github.com/tt-a1i/archify/blob/main/docs/gallery/sources/agent-run.lifecycle.json) such as `queued`, `planning`, `executing`, `reviewing`, and terminal states like `completed`, `cancelled`, or `expired`. Transitions encode the flow logic, with security-gate edges for approval checkpoints and emphasis variants for retry loops.

## Rendering the Diagram

Once your JSON IR is complete, Archify provides two primary methods to render the visualization.

### Option A: Direct HTML Embed

Host your JSON file publicly and embed the diagram directly using Archify's runtime. The renderer loads via [`archify.min.js`](https://github.com/tt-a1i/archify/blob/main/archify.min.js) from the official CDN and initializes based on data attributes in the HTML:

```html
<script src="https://tt-a1i.github.io/archify/archify.min.js"></script>

<div class="diagram-container" data-detail-level="read">
  <svg viewBox="0 0 980 660"
       data-preset="classic"
       data-quality-profile="showcase"
       data-animation="trace">
  </svg>
</div>

```

To load your specific JSON, include a script tag with `id="archify-guided-views-data"` containing your IR or guided view overrides (see lines 4450-4455 in [`examples/lifecycle-agent-run.html`](https://github.com/tt-a1i/archify/blob/main/examples/lifecycle-agent-run.html)). The runtime automatically merges custom views with the base diagram definition.

### Option B: Stand-alone Viewer URL

For quick sharing without custom HTML, use the generic viewer URL pattern:

```text
https://tt-a1i.github.io/archify/start.html?type=lifecycle&source=<URL-to-your-json>

```

This loads the Archify start page with the lifecycle preset pre-selected and imports your IR from the provided source URL.

## Interacting with Agent Run Visualizations

The rendered SVG supports rich interaction for exploring complex agent workflows.

### Keyboard Navigation

Archify implements several keyboard shortcuts for diagram navigation:

- `R` – Toggle route visualization
- `+` / `-` – Zoom in and out
- `M` – Open radar view for orientation
- `[` / `]` – Switch between guided views
- `P` – Play the current guided view animation
- `T` – Toggle between light and dark themes
- `E` – Open the export dialog

### Exporting Diagrams

Press `E` to access export options. Archify supports exporting to **PNG**, **JPEG**, **WebP**, **SVG**, or **WebM** formats, allowing you to embed static assets in documentation, slide decks, or internal wikis while preserving the interactive version for live exploration.

## Practical Implementation Example

The following HTML skeleton loads the bundled agent-run lifecycle from [`docs/gallery/sources/agent-run.lifecycle.json`](https://github.com/tt-a1i/archify/blob/main/docs/gallery/sources/agent-run.lifecycle.json) and adds a custom "Quick Overview" guided view:

```html
<!DOCTYPE html>
<html lang="en" data-theme="dark" data-preset="classic">
<head>
  <meta charset="UTF-8">
  <title>My Agent Run Lifecycle</title>
  <script src="https://tt-a1i.github.io/archify/archify.min.js"></script>
</head>
<body>
  <!-- Custom guided view definition -->
  <script id="archify-guided-views-data" type="application/json">
  [
    {
      "id": "quick-overview",
      "label": "Quick Overview",
      "focus": ["queued", "planning", "executing", "completed"],
      "note": "Show the essential linear flow without interruptions."
    }
  ]
  </script>

  <div class="diagram-container" data-detail-level="read">
    <svg viewBox="0 0 980 660"
         data-preset="classic"
         data-quality-profile="showcase"
         data-animation="trace"
         role="img"
         aria-labelledby="archify-diagram-title">
      <title id="archify-diagram-title">My Agent Run Lifecycle</title>
    </svg>
  </div>
</body>
</html>

```

The `data-preset="classic"` attribute applies the standard color scheme and typography, while `data-animation="trace"` enables the path-tracing animation on load. The custom guided view merges automatically with any views defined in the source JSON.

## Summary

- Archify lifecycle diagrams model agent runs as state machines with lanes, typed states, and variant transitions defined in a JSON IR file.
- The renderer consumes `diagram_type: "lifecycle"` JSON from files like [`docs/gallery/sources/agent-run.lifecycle.json`](https://github.com/tt-a1i/archify/blob/main/docs/gallery/sources/agent-run.lifecycle.json) and outputs interactive SVG via [`archify.min.js`](https://github.com/tt-a1i/archify/blob/main/archify.min.js).
- Embed diagrams directly using HTML data attributes or share via `start.html?type=lifecycle&source=<URL>` query parameters.
- Interact with diagrams using keyboard shortcuts (`[/]` for guided views, `E` for export, `T` for themes) and hover states for detail inspection.
- Export final visualizations to PNG, SVG, or WebM for documentation while maintaining the live interactive version.

## Frequently Asked Questions

### What is the minimum JSON required to render a lifecycle diagram?

You need a JSON object with `diagram_type: "lifecycle"`, at least one lane in the `lanes` array, states with `id`, `type`, `label`, and `lane` properties, and transitions connecting `from` and `to` state IDs. The file [`docs/gallery/sources/agent-run.lifecycle.json`](https://github.com/tt-a1i/archify/blob/main/docs/gallery/sources/agent-run.lifecycle.json) demonstrates the full schema with multiple lanes and guided views.

### How do I add custom guided views to an existing lifecycle diagram?

Inject additional view definitions through a `<script id="archify-guided-views-data" type="application/json">` tag in your HTML. Archify automatically merges these with the views defined in the source JSON IR. Each view requires an `id`, `label`, array of `focus` state IDs, and an optional `note` string.

### Can I use Archify lifecycle diagrams without hosting the JSON file publicly?

Yes. For local development or private networks, serve the JSON from a local web server and reference it via relative path in the HTML embed method, or load it programmatically. The stand-alone viewer URL method requires public hosting since the Archify renderer fetches the source via HTTP.

### Where is the rendering logic implemented in the Archify repository?

The base HTML template containing SVG scaffolding and theme handling resides in [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html). The interactive controls and export functionality shown in [`examples/lifecycle-agent-run.html`](https://github.com/tt-a1i/archify/blob/main/examples/lifecycle-agent-run.html) extend this base template. The core rendering engine is bundled in [`archify.min.js`](https://github.com/tt-a1i/archify/blob/main/archify.min.js) served from the project CDN.