How to Use Archify Lifecycle Diagrams for Agent Run Visualization

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 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 from the official CDN and initializes based on data attributes in the 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). 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:

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 and adds a custom "Quick Overview" guided view:

<!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 and outputs interactive SVG via 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 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. The interactive controls and export functionality shown in examples/lifecycle-agent-run.html extend this base template. The core rendering engine is bundled in archify.min.js served from the project CDN.

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