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

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).

---

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

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

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

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

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

The output 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:

{
  "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	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)	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)	Production-ready example with multiple state types
[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.

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