Archify Lifecycle Diagrams: 7 Key Fields You Must Define

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

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

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

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

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

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

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

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