How to Generate Lifecycle Diagrams with Archify: A Complete Guide

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.

Example structure:

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

npx skills add tt-a1i/archify -g

Create your JSON source file defining the state machine:

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:

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: Demo page containing built-in view definitions in the <script id="archify-guided-views-data"> element
• 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. The README at README.md lines 145-146 also demonstrates lifecycle diagram syntax and references the agent-run example showcasing states from queued through completed.

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