Archify Lifecycle Diagram Schema: Complete Reference for Phase and Event Structure

Archify uses a JSON schema where "lanes" represent phases and "states" represent events, with mandatory transitions linking events across up to four horizontal bands.

The Archify diagramming engine models lifecycle diagrams through a strict JSON schema that maps business process concepts—phases and events—to specific structural elements. This guide breaks down the archify/schemas/lifecycle.schema.json schema, showing how to construct valid lifecycle diagrams with proper phase columns and event nodes.

Schema Overview and Required Top-Level Properties

Every Archify lifecycle diagram must include six mandatory properties at the root level. The diagram is validated against archify/schemas/lifecycle.schema.json before rendering.

Property	Type	Purpose
schema_version	integer	Fixed to 1 for version validation
diagram_type	string	Must be "lifecycle"
meta	object	Title, presets, animation settings, and view configuration
lanes	array	Phase columns—horizontal bands grouping events
states	array	Events—nodes positioned within a specific phase and column
transitions	array	Directed edges connecting events
cards	object	Optional side-panel context panels
viewBox	array	Optional SVG viewport dimensions [420+, 566+]

The schema enforces these requirements to ensure consistent rendering across all lifecycle diagrams in the Archify ecosystem.

Meta Configuration: Titles, Presets, and Animation

The meta object (lines 22–99 of lifecycle.schema.json) controls visual presentation and metadata. This section directly impacts how the phase and event structure appears to viewers.

{
  "title": "Onboarding Lifecycle",
  "subtitle": "User journey from signup to activation",
  "output": "onboarding-diagram",
  "animation": "trace",
  "visual_preset": "classic",
  "quality_profile": "showcase",
  "views": {},
  "legend": {},
  "viewBox": [800, 600]
}

Key meta properties for lifecycle diagrams:

• animation: "trace" creates animated path drawing; "none" renders static
• visual_preset: Controls color and styling—options include classic, signal-flow, blueprint, editorial
• quality_profile: "standard" for drafts, "showcase" for production output

Each preset affects how phase bands and event nodes are styled, making meta essential for professional lifecycle diagram presentation.

Lanes: Defining Phase Columns in Lifecycle Diagrams

The lanes array defines phase columns—horizontal bands that organize events logically. According to lines 101–122 of the schema, lanes follow a strict structure.

"lanes": [
  { "id": "discovery", "label": "Discovery" },
  { "id": "evaluation", "label": "Evaluation" },
  { "id": "purchase", "label": "Purchase" },
  { "id": "retention", "label": "Retention" }
]

Lane constraints in the Archify lifecycle schema:

• Minimum: 1 lane
• Maximum: 4 lanes
• Required properties: id (must match common.id pattern), label (display string)
• No additional properties: Plain objects only

The id value becomes the reference key for placing events into specific phase columns through the lane property in state definitions.

States: Positioning Events Within Phase Columns

Events in Archify lifecycle diagrams are modeled as states—nodes with specific positions within a phase (lane) and column index. Lines 123–186 of the schema define the complete state structure.

{
  "states": [
    {
      "id": "landing-page",
      "type": "start",
      "label": "Landing Page Visit",
      "sublabel": "Organic or paid traffic",
      "tag": "entry",
      "step": "S1",
      "lane": "discovery",
      "col": 0,
      "width": 48,
      "height": 36,
      "yOffset": 0
    }
  ]
}

State Type Values

Type	Visual Style	Use Case
start	Entry node	Beginning of lifecycle
active	Processing indicator	Ongoing activities
waiting	Paused state	Pending external input
decision	Diamond shape	Branch points
success	Positive completion	Goals achieved
failure	Error/termination	Process failures
neutral	Informational	Neutral milestones
external	Boundary crossing	External system touchpoints

Phase Column Positioning

The lane and col properties control where events appear:

• lane: Must match an id from the lanes array—ties event to a specific phase
• col: Integer 0–4 specifying horizontal position within the lane

This two-dimensional positioning—phase by lane, progression by column—creates the classic lifecycle timeline visualization.

Transitions: Connecting Events Across Phases

Transitions (lines 187–276) define directed edges between events, including options for complex routing across phase boundaries.

{
  "transitions": [
    {
      "id": "t1",
      "from": "landing-page",
      "to": "feature-tour",
      "label": "Converts",
      "note": "Trigger: scroll depth > 50%",
      "variant": "solid-success",
      "route": "straight",
      "fromSide": "right",
      "toSide": "left"
    }
  ]
}

Routing options handle phase-to-phase connections:

• auto (default): Automatic path calculation
• straight: Direct line
• drop/bottom-channel/top-channel/right-channel/left-channel: Structured routing for complex diagrams

The via array accepts waypoint coordinates for precise path control when automatic routing is insufficient.

Complete Lifecycle Diagram Example

This minimal valid example demonstrates phase columns (lanes) with positioned events (states) and connecting transitions:

{
  "schema_version": 1,
  "diagram_type": "lifecycle",
  "meta": {
    "title": "Customer Acquisition Lifecycle",
    "visual_preset": "signal-flow",
    "animation": "trace"
  },
  "lanes": [
    { "id": "awareness", "label": "Awareness" },
    { "id": "consideration", "label": "Consideration" },
    { "id": "conversion", "label": "Conversion" }
  ],
  "states": [
    {
      "id": "social-ad",
      "type": "external",
      "label": "Social Ad",
      "lane": "awareness",
      "col": 0
    },
    {
      "id": "website-visit",
      "type": "start",
      "label": "Website Visit",
      "lane": "awareness",
      "col": 1
    },
    {
      "id": "demo-request",
      "type": "decision",
      "label": "Request Demo?",
      "lane": "consideration",
      "col": 2
    },
    {
      "id": "qualified-lead",
      "type": "active",
      "label": "Qualified Lead",
      "lane": "consideration",
      "col": 3
    },
    {
      "id": "closed-won",
      "type": "success",
      "label": "Closed Won",
      "lane": "conversion",
      "col": 4
    }
  ],
  "transitions": [
    { "from": "social-ad", "to": "website-visit", "route": "straight" },
    { "from": "website-visit", "to": "demo-request", "route": "auto" },
    { "from": "demo-request", "to": "qualified-lead", "label": "Yes" },
    { "from": "qualified-lead", "to": "closed-won", "variant": "solid-success" }
  ]
}

This structure produces a three-phase lifecycle diagram with five events positioned across columns 0–4, rendered with signal-flow styling and trace animation.

Optional Cards for Enhanced Event Context

The cards property references common.schema.json#/$defs/cards (line 278) for side-panel information panels. Cards attach to specific events to provide extended documentation without cluttering the main diagram.

Cards are particularly useful for lifecycle diagrams where event nodes need detailed explanations, supporting metrics, or procedural documentation.

Key Source Files for Lifecycle Schema Reference

File	Purpose	Lines
archify/schemas/lifecycle.schema.json	Primary JSON Schema definition	1–280+
archify/renderers/lifecycle/render-lifecycle.mjs	Runtime validation and SVG generation	Full module
docs/gallery/sources/agent-run.lifecycle.json	Production example of phase/event structure	Full file
archify/schemas/common.schema.json	Shared type definitions referenced by lifecycle schema	Various

These files in the tt-a1i/archify repository contain the authoritative definitions for all lifecycle diagram schema elements.

Summary

• Archify lifecycle diagrams use lanes for phases and states for events, positioned via lane (phase ID) and col (0–4 column index) properties
• The schema requires schema_version (must be 1), diagram_type ("lifecycle"), meta, lanes, states, and transitions
• Lane limits: 1–4 phase columns maximum
• State types: start, active, waiting, decision, success, failure, neutral, external
• Transitions support multiple routing strategies and can cross phase boundaries with channel or waypoint routing
• Complete schema validation occurs in render-lifecycle.mjs against lifecycle.schema.json

Frequently Asked Questions

What is the maximum number of phases in an Archify lifecycle diagram?

Archify lifecycle diagrams support 1 to 4 phases maximum, defined in the lanes array. This limit is enforced by lifecycle.schema.json (lines 101–122). Exceeding four lanes causes validation failure in the renderer.

How do I position an event in a specific phase column?

Use the lane property to select the phase (referencing a lane id) and the col property (integer 0–4) to set horizontal position within that phase. The combination of lane and col creates the two-dimensional grid positioning for lifecycle events.

Can events exist without a phase assignment?

No—all states require a valid lane property matching an id from the lanes array. The schema defines lane as a required string property (lines 123–186). Unassigned events fail validation in render-lifecycle.mjs.

What file validates lifecycle diagram structure?

The archify/schemas/lifecycle.schema.json file provides the JSON Schema definition, validated at runtime by archify/renderers/lifecycle/render-lifecycle.mjs. The renderer checks schema_version first, then validates lanes, states, and transitions against their respective subschemas before generating SVG output.

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