# How to Generate Lifecycle Diagrams with Archify: A Complete Guide

> Learn to generate interactive lifecycle diagrams with Archify using the render lifecycle command. Visualize state machines with self-contained HTML/SVG artifacts.

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

---

**Archify generates interactive lifecycle diagrams from typed JSON Intermediate Representation (IR) using the `render lifecycle` CLI command or chat-enabled agents, producing self-contained HTML/SVG artifacts that visualize state machines.**

Archify is an open-source diagramming framework hosted at `tt-a1i/archify` that transforms structured data into deterministic visual outputs. When you generate lifecycle diagrams with Archify, you create declarative JSON views defining ordered state sequences, invoke the dedicated lifecycle renderer implemented in `archify/renderers/lifecycle/render-lifecycle.mjs`, and receive interactive HTML pages with embedded SVG diagrams.

## What Are Lifecycle Diagrams in Archify?

Archify supports five distinct diagram types—**architecture**, **workflow**, **sequence**, **data-flow**, and **lifecycle**—each backed by a dedicated renderer that consumes typed JSON IR. The **lifecycle** renderer specifically visualizes state machines, displaying ordered phases such as `queued → planning → executing → reviewing → completed` on horizontal rails.

According to the source code in `archify/renderers/lifecycle/render-lifecycle.mjs`, the renderer highlights waiting periods, retry loops, and terminal outcomes including `failed`, `cancelled`, or `expired`. Lifecycle elements are distinguished using the color `#be123c` (red) as documented in the repository README.

## Prerequisites: The Three Required Components

To successfully generate a lifecycle diagram, you must provide three specific inputs:

### 1. A JSON View Definition

The view is a plain JavaScript object with an `id`, `type: "lifecycle"`, and a `focus` array containing the ordered list of states to emphasize. The full set of built-in views resides in the hidden `<script id="archify-guided-views-data">` element within [`examples/lifecycle-agent-run.html`](https://github.com/tt-a1i/archify/blob/main/examples/lifecycle-agent-run.html).

Example structure:

```json
{
  "id": "main-lifecycle",
  "label": "Main lifecycle",
  "type": "lifecycle",
  "focus": ["queued", "planning", "executing", "reviewing", "completed"],
  "note": "Follow the ordered phases from accepted request to completed response."
}

```

### 2. A Generation Prompt

When using chat-enabled agents such as Cursor, Claude-Code, Codex, or OpenCode, provide a prompt specifying the view type and target states:

```

Analyze the repository, then use Archify to create a lifecycle diagram of the agent-run process. Show the states queued → planning → executing → reviewing → completed.

```

### 3. The Renderer Invocation

Execute the lifecycle renderer either via CLI or programmatically. The CLI entry point at `archify/bin/archify.mjs` parses commands using the syntax `render lifecycle`.

## Step-by-Step CLI Generation

For deterministic generation outside of chat agents, use the following workflow:

First, install Archify globally:

```bash
npx skills add tt-a1i/archify -g

```

Create your JSON source file defining the state machine:

```bash
cat > lifecycle.json <<'EOF'
{
  "id": "agent-run",
  "type": "lifecycle",
  "focus": ["queued", "planning", "executing", "reviewing", "completed"],
  "note": "Agent run lifecycle from request to response."
}
EOF

```

Render the diagram to HTML using the exact file paths from the source tree:

```bash
node archify/bin/archify.mjs render lifecycle \
     --input lifecycle.json \
     --output agent-run.lifecycle.html

```

## Output Features and Interactivity

The resulting artifact is a self-contained HTML file with no external dependencies. Key capabilities include:

- **Theme switching**: Toggle between dark and light modes via the `data-theme` attribute
- **Export options**: Copy PNG to clipboard or download static SVG and animated WebM formats
- **Guided story views**: Interactive controls that focus on specific states, such as "Human and input waits"
- **Parallel state visualization**: Optional side-bands displaying concurrent process flows alongside the primary horizontal rail

Because the diagram is generated from pure JSON, the output validates against schemas defined in `archify/scripts/generate-validators.mjs` and can be embedded directly into READMEs, release notes, or shared on social media.

## Key Implementation Files

Understanding the following source files provides insight into the generation pipeline:

- **`archify/renderers/lifecycle/render-lifecycle.mjs`**: Core renderer implementation that validates JSON schema and produces SVG/HTML output
- **`archify/bin/archify.mjs`**: CLI entry point handling the `render lifecycle` command parsing
- **`archify/scripts/generate-validators.mjs`**: Schema validation generator for all diagram types including lifecycle
- **[`examples/lifecycle-agent-run.html`](https://github.com/tt-a1i/archify/blob/main/examples/lifecycle-agent-run.html)**: Demo page containing built-in view definitions in the `<script id="archify-guided-views-data">` element
- **[`README.md`](https://github.com/tt-a1i/archify/blob/main/README.md)**: High-level documentation including the diagram type table and usage examples

## Summary

- **Archify generates lifecycle diagrams** from JSON IR using dedicated renderers that produce deterministic HTML/SVG artifacts
- **Required inputs** include a JSON view with `type: "lifecycle"`, a focus array of ordered states, and either CLI invocation or agent prompts
- **CLI command**: `node archify/bin/archify.mjs render lifecycle --input <file> --output <file>`
- **Output features** include theme switching, multi-format export (PNG/SVG/WebM), and interactive guided views
- **Source files** are located in `tt-a1i/archify`, with the core logic in `render-lifecycle.mjs` and schemas validated via `generate-validators.mjs`

## Frequently Asked Questions

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

Archify validates lifecycle diagrams against a strict schema generated by `archify/scripts/generate-validators.mjs`. The JSON must include an `id`, `type` set to `"lifecycle"`, and a `focus` array containing ordered state strings. Additional optional fields include `label` for display names and `note` for descriptive text.

### Can I customize the colors in lifecycle diagrams?

The lifecycle renderer uses `#be123c` (red) as the default distinguishing color for lifecycle elements hardcoded in the rendering logic. While the current implementation in `render-lifecycle.mjs` uses fixed color values for consistency, you can modify the source or post-process the generated SVG for custom color schemes.

### How do I export lifecycle diagrams to PNG or SVG?

Generated lifecycle diagrams include an interactive export menu in the HTML output. You can copy PNG directly to the clipboard or download static SVG files for documentation. For animated sequences, the export menu provides WebM format options suitable for presentations and social media sharing.

### Where can I find examples of lifecycle diagram definitions?

Built-in lifecycle view examples are embedded in the `<script id="archify-guided-views-data">` element within [`examples/lifecycle-agent-run.html`](https://github.com/tt-a1i/archify/blob/main/examples/lifecycle-agent-run.html). The README at [`README.md`](https://github.com/tt-a1i/archify/blob/main/README.md) lines 145-146 also demonstrates lifecycle diagram syntax and references the agent-run example showcasing states from `queued` through `completed`.