# Archify Lifecycle Diagrams: 7 Key Fields You Must Define

> Unlock Archify lifecycle diagram essentials. Discover the 7 critical fields schema_version meta lanes states transitions and cards needed for valid state visualizations.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-09-02

---

**Archify lifecycle diagrams require seven mandatory fields—`schema_version`, `diagram_type`, `meta`, `lanes`, `states`, `transitions`, and optionally `cards`—defined in a strict JSON schema that ensures valid, renderable state-based visualizations.**

Every Archify lifecycle diagram starts with a contract. The schema in [`archify/schemas/lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json) enforces this contract, guaranteeing that pipelines, agent runs, and release cycles can be modeled consistently and rendered without ambiguity. This article breaks down each required field with source-backed details and runnable examples.

---

## Schema Version and Diagram Type

Two fields lock your diagram to the lifecycle specification.

- **`schema_version`** — Must be the integer `1`. This pins your document to the current schema iteration and prevents silent breaking changes as Archify evolves.

- **`diagram_type`** — Must be exactly `"lifecycle"`. This discriminator tells Archify's validator and renderer which parsing path to activate.

From the source schema, lines 15–22 establish these constants:

```json
{
  "schema_version": 1,
  "diagram_type": "lifecycle"
}

```

---

## Meta Field: Human-Readable Metadata

The **`meta`** object (lines 23–31) is required and must contain at least a `title`. It carries presentation-layer hints that don't affect graph topology but control how the diagram appears to viewers.

**Required sub-field:**
- `title` — Display name for the diagram

**Common optional sub-fields:**
- `subtitle` — Secondary description
- `locale` — Language code for internationalization
- `animation` — Playback settings for lifecycle progression
- `visual_preset` — Predefined color and layout theme
- `quality_profile` — Render fidelity tier

```json
{
  "meta": {
    "title": "Deployment Pipeline",
    "subtitle": "Staging to production flow",
    "locale": "en-US",
    "visual_preset": "corporate"
  }
}

```

---

## Lanes: Visual Grouping Tracks

**`lanes`** organizes your diagram into 1–4 horizontal tracks (lines 92–105). Each lane requires:

| Sub-field | Purpose |
|-----------|---------|
| `id` | Unique string referenced by states |
| `label` | Display text for the lane header |

Typical lane arrangements include *Lifecycle phases*, *Interruptions*, *Recovery*, and *Terminal exits*.

```json
{
  "lanes": [
    { "id": "phases", "label": "Lifecycle phases" },
    { "id": "interrupts", "label": "Interruptions" }
  ]
}

```

---

## States: The Nodes of Your Lifecycle

The **`states`** array (lines 115–165) defines each step in your process. Archify requires **minimum 2 states** per diagram.

**Required state properties:**

| Property | Constraints |
|----------|-------------|
| `id` | Unique identifier string |
| `type` | One of: `start`, `active`, `waiting`, `decision`, `success`, `failure`, `neutral`, `external` |
| `label` | Display text |
| `lane` | Must match a lane `id` |
| `col` | Integer 0–4 for horizontal grid position |

**Optional visual properties:** `sublabel`, `tag`, `brand`, `step`, `width`, `height`, `yOffset`

The nine state types encode semantics that drive automatic styling:

- **`start`** — Entry point (green, distinctive marker)
- **`active`** — Currently executing state (pulsing indicator)
- **`waiting`** — Pending external signal (amber, clock icon)
- **`decision`** — Branching condition (diamond shape)
- **`success`** / **`failure`** / **`neutral`** — Terminal outcomes
- **`external`** — Systems outside the primary lifecycle boundary

```json
{
  "states": [
    { "id": "s0", "type": "start", "label": "Triggered", "lane": "phases", "col": 0 },
    { "id": "s1", "type": "waiting", "label": "Awaiting Approval", "lane": "phases", "col": 1 },
    { "id": "s2", "type": "decision", "label": "Approved?", "lane": "phases", "col": 2 },
    { "id": "s3", "type": "active", "label": "Deploying", "lane": "phases", "col": 3 },
    { "id": "s4", "type": "success", "label": "Live", "lane": "phases", "col": 4 }
  ]
}

```

---

## Transitions: Directed Edges Between States

**`transitions`** (lines 181–258) connect your states into a flow. Each transition requires:

| Property | Description |
|----------|-------------|
| `from` | Source state `id` |
| `to` | Destination state `id` |

**Optional routing and styling properties:**
- `label` — Edge annotation
- `note` — Longer explanatory text
- `variant` — Line style override
- `route` — Routing algorithm hint (`direct`, `orthogonal`, `curved`)
- `fromSide` / `toSide` — Attachment points (`top`, `bottom`, `left`, `right`)
- `via` — Intermediate waypoints
- `cornerRadius` — Corner smoothing
- `labelAt` / `labelDx` / `labelDy` — Label positioning

```json
{
  "transitions": [
    { "from": "s0", "to": "s1" },
    { "from": "s1", "to": "s2", "label": "timeout 24h" },
    { "from": "s2", "to": "s3", "label": "yes", "fromSide": "right", "toSide": "left" },
    { "from": "s2", "to": "s4", "label": "no", "variant": "dashed" }
  ]
}

```

---

## Cards: Optional Floating Annotations

The **`cards`** field (lines 262–265) is optional but powerful. It defines reusable annotation objects that can attach to states or transitions without cluttering the core graph structure. Cards inherit from Archify's common schema and support rich text, icons, and linked documentation.

Use cards for:
- Compliance requirements tied to specific states
- Runbook links for recovery procedures
- Version or timestamp metadata

---

## Complete Minimal Example

This valid lifecycle diagram demonstrates all required fields in a functioning configuration:

```json
{
  "schema_version": 1,
  "diagram_type": "lifecycle",
  "meta": {
    "title": "Simple Job Lifecycle"
  },
  "lanes": [
    { "id": "main", "label": "Lifecycle phases" }
  ],
  "states": [
    { "id": "s0", "type": "start", "label": "Queued", "lane": "main", "col": 0 },
    { "id": "s1", "type": "active", "label": "Running", "lane": "main", "col": 1 },
    { "id": "s2", "type": "success", "label": "Completed", "lane": "main", "col": 2 }
  ],
  "transitions": [
    { "from": "s0", "to": "s1" },
    { "from": "s1", "to": "s2" }
  ]
}

```

For production-grade patterns, examine [`archify/test/fixtures/v1-baseline/agent-run.lifecycle.json`](https://github.com/tt-a1i/archify/blob/main/archify/test/fixtures/v1-baseline/agent-run.lifecycle.json) in the repository—it implements multiple lanes, `waiting` states, decision branches, and recovery paths.

---

## Summary

- **Seven fields** define every Archify lifecycle diagram: `schema_version`, `diagram_type`, `meta`, `lanes`, `states`, `transitions`, and optional `cards`
- **Schema location:** [`archify/schemas/lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json) enforces validation rules for all fields
- **Minimum viability:** 2 states, 1 lane, 1 transition connecting entry to exit
- **State types** (`start`, `active`, `waiting`, `decision`, `success`, `failure`, `neutral`, `external`) drive automatic visual encoding
- **Lanes** (1–4) create visual hierarchy for complex flows
- **Test fixtures** in `archify/test/fixtures/v1-baseline/` demonstrate full feature coverage

---

## Frequently Asked Questions

### What happens if I omit a required field in an Archify lifecycle diagram?

The validator rejects the document. According to [`archify/schemas/lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json), missing `schema_version`, `diagram_type`, `meta`, `lanes`, `states`, or `transitions` produces a schema validation error before rendering begins. The error message identifies the specific missing property and its JSON path.

### Can I have more than 4 lanes in a lifecycle diagram?

No. The schema constrains `lanes` to a maximum of 4 items (lines 92–105). Exceeding this limit triggers a validation failure. This restriction ensures consistent rendering across all Archify viewers and prevents layout overflow in narrow display contexts.

### What's the difference between `neutral` and `external` state types?

**`neutral`** marks terminal or non-judgmental end states with standard styling, while **`external`** visually distinguishes systems outside your lifecycle's boundary using a different shape and color treatment. Use `external` when your diagram needs to reference upstream triggers or downstream systems that aren't part of the core process you control.

### How do I position states horizontally without overlap?

Assign unique `col` values (0–4) to states within the same lane. The `col` index maps to a fixed grid position. States in different lanes can share `col` values—they stack vertically. For fine-tuning, use optional `yOffset` to nudge states up or down within their lane.