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

> Explore the Archify lifecycle diagram schema. Understand how lanes define phases and states define events, with mandatory transitions connecting events in this comprehensive reference.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: api-reference
- Published: 2026-08-05

---

**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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/lifecycle.schema.json)) controls visual presentation and metadata. This section directly impacts how the phase and event structure appears to viewers.

```json
{
  "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.

```json
"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.

```json
{
  "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.

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

```json
{
  "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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/docs/gallery/sources/agent-run.lifecycle.json) | Production example of phase/event structure | Full file |
| [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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.