# How to Visualize Lifecycles with Archify: A Complete Guide to JSON-to-SVG Rendering

> Learn to visualize lifecycles with Archify. This guide details how Archify renders concise JSON lifecycle descriptions into production-ready SVG diagrams using its six-stage pipeline.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: tutorial
- Published: 2026-09-06

---

**Archify converts concise JSON lifecycle descriptions into production-ready SVG diagrams through a six-stage rendering pipeline defined in `archify/renderers/lifecycle/render‑lifecycle.mjs`.**

The **lifecycle** is a three-band diagram format in Archify that models processes spanning phases, events, and outcomes. Whether you're documenting agent workflows, deployment pipelines, or business processes, Archify transforms structured JSON into embeddable, styleable graphics without manual drawing tools.

---

## Core Lifecycle Structure

Every lifecycle diagram rests on three fixed horizontal **bands** (lanes):

- **Phase lane (`main`)** — The primary progression of your process
- **Event lane** — Interruptions, recoveries, or intermediate steps
- **Outcome lane (`terminal`)** — Final states (success, failure, termination)

Within these lanes, you place **states** at specific column positions. **Transitions** connect states with optional labels, routing hints, and notes.

The schema enforcing this structure lives in [[`archify/schemas/lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json)](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json).

---

## The Rendering Pipeline

The lifecycle renderer operates in six distinct phases, each implemented as a specific function in `render‑lifecycle.mjs`:

### 1. Diagram Loading (`loadDiagramWithBrandMarks`)

Reads the JSON definition, extracts metadata (viewBox, locale, quality profile), identifies template paths, and resolves output destinations.

### 2. State Geometry (`measureState`)

Maps each state to concrete coordinates based on:
- **Band assignment** (`phase`, `event`, `outcome`)
- **Column positioning** (`col` index)
- **Optional overrides** (`width`, `height`, `yOffset`)

### 3. Model Validation (`validateLifecycle`)

Performs comprehensive checks before rendering:
- Duplicate state IDs
- Lane existence and reserved ID compliance (`main`, `terminal`)
- Column bounds violations
- Non-finite coordinate detection
- Label overflow against viewBox constraints
- Brand-mark conflicts
- Spatial overlaps (state-to-state, state-to-label, label-to-transition-path)

### 4. Port and Path Computation (`automaticPortSpread`, `pathFor`)

- Distributes connection points automatically around state perimeters
- Builds cached Bézier paths for every transition
- Applies routing hints (`straight`, `bottom-channel`, `top-channel`) when specified

### 5. SVG Section Rendering

Emits layered SVG elements in order:
- Background grid
- Lifecycle bands with labels
- Primary rail connecting phase states
- Transition paths with arrowheads
- State rectangles with **type-specific fills** (`start`, `active`, `waiting`, `decision`, `success`, `failure`)
- Sub-labels, tags, and brand-mark anchors
- Transition labels and optional notes
- Legend swatches

### 6. Output Generation (`writeDiagram`)

Writes the final SVG file, optionally wrapped in HTML with interactive controls.

---

## JSON Schema Reference

| Key | Required | Description |
|-----|----------|-------------|
| `states` | Yes | Array of state objects with `id`, `label`, `type`, `lane`, `col` |
| `lanes` | Yes | Lane definitions; must include `main` and `terminal` |
| `transitions` | No | Edge array linking `from` → `to` with optional `label`, `note`, `route`, `via` |
| `meta` | No | Presentation controls: `viewBox`, `locale`, `legend`, `quality` |

### State Object Properties

```json
{
  "id": "planning",
  "label": "Planning",
  "type": "active",
  "lane": "main",
  "col": 1,
  "width": 120,
  "height": 60,
  "yOffset": 0,
  "sublabel": "AI-assisted",
  "tag": "v2.1",
  "step": 2
}

```

| Property | Required | Description |
|----------|----------|-------------|
| `id` | Yes | Unique identifier, used in transition targeting |
| `label` | Yes | Display text for the state |
| `type` | Yes | Visual style: `start`, `active`, `waiting`, `decision`, `success`, `failure` |
| `lane` | Yes | Band placement: `main`, `event`, or `terminal` |
| `col` | Yes | Horizontal position index |
| `width`/`height` | No | Override default dimensions |
| `yOffset` | No | Vertical adjustment within lane |
| `sublabel` | No | Secondary text below main label |
| `tag` | No | Small badge text |
| `step` | No | Numeric indicator |

### Transition Object Properties

```json
{
  "from": "planning",
  "to": "executing",
  "label": "run",
  "note": "Triggers on approval",
  "route": "bottom-channel",
  "via": ["checkpoint"],
  "channelX": 400,
  "channelY": 200,
  "fromSide": "bottom",
  "toSide": "left"
}

```

---

## Complete Workflow Example

### Step 1: Define the Lifecycle JSON

```bash
cat > agent-run.lifecycle.json <<'EOF'
{
  "states": [
    { "id": "queued",    "label": "Queued",    "type": "start",   "lane": "main",     "col": 0 },
    { "id": "planning",  "label": "Planning",  "type": "active",  "lane": "main",     "col": 1 },
    { "id": "executing", "label": "Executing", "type": "waiting", "lane": "event",    "col": 0, "yOffset": 20 },
    { "id": "reviewing", "label": "Reviewing", "type": "decision","lane": "event",    "col": 1 },
    { "id": "completed", "label": "Completed", "type": "success", "lane": "terminal", "col": 0 }
  ],
  "lanes": [
    { "id": "main",     "label": "Lifecycle phases" },
    { "id": "event",    "label": "Interruptions + recovery" },
    { "id": "terminal", "label": "Outcomes" }
  ],
  "transitions": [
    { "from": "queued",    "to": "planning",  "label": "start" },
    { "from": "planning",  "to": "executing", "label": "run" },
    { "from": "executing", "to": "reviewing", "label": "review" },
    { "from": "reviewing", "to": "completed", "label": "finish" }
  ],
  "meta": { "viewBox": [980, 660] }
}
EOF

```

### Step 2: Render via CLI

```bash
npx archify render lifecycle agent-run.lifecycle.json -o agent-run.lifecycle.html

```

The output [`agent-run.lifecycle.html`](https://github.com/tt-a1i/archify/blob/main/agent-run.lifecycle.html) contains:
- The rendered SVG with all specified states and transitions
- CSS classes for type-based styling (`typeClass`, `textClass`)
- Optional UI controls for zoom and legend toggling

---

## Minimal Valid Example

For quick testing, use this three-state specification:

```json
{
  "states": [
    { "id": "s1", "label": "Start", "type": "start",   "lane": "main",     "col": 0 },
    { "id": "s2", "label": "Work",  "type": "active",  "lane": "event",    "col": 0 },
    { "id": "s3", "label": "Done",  "type": "success", "lane": "terminal", "col": 0 }
  ],
  "lanes": [
    { "id": "main",     "label": "Phases" },
    { "id": "event",    "label": "Events" },
    { "id": "terminal", "label": "Outcomes" }
  ],
  "transitions": [
    { "from": "s1", "to": "s2", "label": "run" },
    { "from": "s2", "to": "s3", "label": "finish" }
  ],
  "meta": { "viewBox": [800, 600] }
}

```

---

## Key Implementation Files

| File | Purpose |
|------|---------|
| [`archify/renderers/lifecycle/render-lifecycle.mjs`](https://github.com/tt-a1i/archify/blob/main/archify/renderers/lifecycle/render-lifecycle.mjs) | Core renderer implementing all six pipeline stages |
| [[`archify/schemas/lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json)](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json) | JSON Schema validation for lifecycle definitions |
| [[`archify/examples/agent-run.lifecycle.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/agent-run.lifecycle.json)](https://github.com/tt-a1i/archify/blob/main/archify/examples/agent-run.lifecycle.json) | Production-ready example with multiple state types |
| [[`docs/start.html`](https://github.com/tt-a1i/archify/blob/main/docs/start.html)](https://github.com/tt-a1i/archify/blob/main/docs/start.html) | Web UI demonstrating the lifecycle tab |

---

## Customization Options

### Visual Styling

State types map to CSS classes automatically:
- `.lifecycle-state-start` — Entry points
- `.lifecycle-state-active` — In-progress phases
- `.lifecycle-state-waiting` — Blocking or idle states
- `.lifecycle-state-decision` — Branching points
- `.lifecycle-state-success` / `.lifecycle-state-failure` — Terminal outcomes

Override these classes in your template or embed custom CSS in the output HTML.

### Routing Control

Guide transition paths with the `route` property:
- `straight` — Direct line (default)
- `bottom-channel` — Route below states
- `top-channel` — Route above states

Use `fromSide` and `toSide` (`top`, `bottom`, `left`, `right`) to force specific attachment points.

---

## Summary

- **Archify lifecycle diagrams** visualize processes across three fixed bands: phases, events, and outcomes.
- The renderer in `render‑lifecycle.mjs` processes JSON through six validated stages to produce SVG output.
- State placement uses `lane` + `col` coordinates; transitions support automatic or hinted routing.
- The CLI command `npx archify render lifecycle <file.json>` generates ready-to-embed HTML/SVG.
- Full JSON Schema validation ensures diagrams render correctly before SVG generation begins.

---

## Frequently Asked Questions

### What are the required lane IDs for a valid lifecycle diagram?

Every lifecycle must include `main` (the phase rail) and `terminal` (the outcome rail). The `event` lane is conventional but optional. The `validateLifecycle` function explicitly checks for these reserved IDs and rejects definitions missing either required lane.

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

Yes. Archify assigns CSS classes based on state `type` values. The generated SVG includes classes like `.lifecycle-state-active` and `.lifecycle-text-decision`. Provide custom CSS in your template or post-process the output. The `meta.quality` profile can also select predefined color palettes.

### How does Archify prevent overlapping elements in complex diagrams?

The `validateLifecycle` function runs spatial collision detection against states, labels, and transition paths. It flags non-finite coordinates, label overflow beyond the viewBox, and physical overlaps. Failures throw descriptive errors before SVG generation, allowing you to adjust column positions or dimensions.

### What routing options exist for transitions between non-adjacent states?

Use the `route` property with values `straight`, `bottom-channel`, or `top-channel` to control path geometry. For precise control, specify `channelX`/`channelY` coordinates for waypoints, or `fromSide`/`toSide` hints to force connection points. The `automaticPortSpread` algorithm distributes ports when multiple transitions originate from the same state.