State Types for Lifecycle Diagrams in Archify: The Complete Guide

Archify defines seven distinct state categories for lifecycle diagrams—Start, Planning, Executing, Waiting, Reviewing, Terminal Success, and Terminal Failure—that control visual styling and workflow progression in archify/schemas/lifecycle.json.

The tt-a1i/archify repository provides a declarative diagramming engine where lifecycle diagrams visualize process progression through strictly typed states. Each state must declare a category that determines its visual representation, position on the diagram rail, and relationship to terminal outcomes.

The Seven State Categories for Archify Lifecycle Diagrams

Archify’s lifecycle renderer recognizes seven logical state categories that map to specific phase types in a workflow. These categories are hard-coded in the lifecycle schema and drive the visual layout engine.

Category	Schema Value	Purpose	Example States
Start / Queued	start	Initial entry point before work begins	queued
Planning / Preparing	pre-process	Setup and preparation activities	planning
Executing / In-flight	executing	Core processing and active work	executing
Waiting / Human-wait	wait	Paused states awaiting input or approval	approval, blocked
Reviewing	review	Checkpoint examination of results	reviewing
Terminal – Success	terminal-success	Successful completion endpoints	completed, success
Terminal – Failure	terminal-failure, terminal-cancellation	Error, cancellation, or expiry endpoints	failed, cancelled, expired

The Terminal category splits into three schema values—terminal-success, terminal-failure, and terminal-cancellation—to distinguish between successful completion, retryable errors, and permanent cancellation states.

Schema Implementation and Category Values

The canonical definitions for lifecycle state types reside in archify/schemas/lifecycle.json. This schema enumerates the allowed category property values for each state object and validates that all state declarations conform to one of the seven logical types.

Valid category strings include:

• start
• pre-process
• executing
• wait
• review
• terminal-success
• terminal-failure
• terminal-cancellation

Each state in a lifecycle JSON definition must reference one of these schema values to ensure proper rendering.

Visual Rendering Based on State Types

The rendering engine located at archify/renderers/lifecycle/render-lifecycle.mjs consumes these category values to generate three distinct visual components:

• Rail: A horizontal track running left-to-right from start through executing to terminal states
• Bands: Visual separators that distinguish waiting periods (wait category) from active processing (executing and pre-process categories)
• Colored Markers: Distinct fill colors for terminal states, with terminal-success rendered differently from terminal-failure and terminal-cancellation to highlight success versus failure paths

The renderer assigns specific coordinates and color codes based on the category metadata, ensuring that waiting states visually interrupt the flow while terminal states appear as endpoints.

Built-in Lifecycle Views and State Groupings

The reference implementation in examples/lifecycle-agent-run.html demonstrates three built-in views that filter and focus on specific state type groupings:

1. Main Lifecycle View: Displays the standard flow queued → planning → executing → reviewing → completed, emphasizing the happy path from start through terminal success
2. Human-waits View: Isolates interaction points by focusing on states executing → approval → reviewing → blocked, highlighting where the process pauses for human input without becoming terminal
3. Recovery-and-exits View: Maps failure handling through executing → failed → blocked → cancelled → expired, distinguishing between retryable failures and permanent cancellation states

These views validate that the state type system supports both linear progression and complex branching with multiple terminal outcomes.

Practical Implementation: Defining States in JSON

To declare states in an Archify lifecycle diagram, construct a JSON object following the schema defined in archify/schemas/lifecycle.json. Each state requires an id, label, and category property mapped to the valid schema values.

{
  "id": "sample-lifecycle",
  "type": "lifecycle",
  "states": [
    { "id": "queued",      "label": "Queued",      "category": "start" },
    { "id": "planning",    "label": "Planning",    "category": "pre-process" },
    { "id": "executing",   "label": "Executing",   "category": "executing" },
    { "id": "approval",    "label": "Approval",    "category": "wait" },
    { "id": "reviewing",   "label": "Reviewing",   "category": "review" },
    { "id": "completed",   "label": "Completed",   "category": "terminal-success" },
    { "id": "failed",      "label": "Failed",      "category": "terminal-failure" },
    { "id": "cancelled",   "label": "Cancelled",   "category": "terminal-cancellation" }
  ],
  "transitions": [
    { "from": "queued",    "to": "planning" },
    { "from": "planning",  "to": "executing" },
    { "from": "executing", "to": "approval" },
    { "from": "approval",  "to": "reviewing" },
    { "from": "reviewing", "to": "completed" },
    { "from": "executing", "to": "failed" },
    { "from": "executing", "to": "cancelled" }
  ]
}

This structure allows the renderer to position states correctly on the rail and apply appropriate styling based on the assigned category.

Rendering from the Command Line

After defining state types in your JSON file, generate the visualization using the Archify CLI. The render-lifecycle command processes the state definitions and category assignments to produce the HTML output.

node archify/bin/archify.mjs render lifecycle examples/lifecycle-sample.json out.html --preset=signal-flow

The CLI invokes the rendering logic from archify/renderers/lifecycle/render-lifecycle.mjs, which interprets the state categories to generate the rail, bands, and terminal markers.

Summary

• Archify lifecycle diagrams use seven state categories: Start, Planning, Executing, Waiting, Reviewing, Terminal Success, and Terminal Failure
• Schema values are defined in archify/schemas/lifecycle.json as: start, pre-process, executing, wait, review, terminal-success, terminal-failure, and terminal-cancellation
• The rendering engine in render-lifecycle.mjs maps these categories to visual components including rails, waiting bands, and colored terminal markers
• Terminal states split into success, failure, and cancellation types to distinguish final outcomes
• Waiting states create visual interruptions in the flow for human-in-the-loop processes
• Example implementations in examples/lifecycle-agent-run.html demonstrate filtering views by state type groupings

Frequently Asked Questions

What are the valid state category values in Archify's lifecycle schema?

The archify/schemas/lifecycle.json file defines eight valid category values: start, pre-process, executing, wait, review, terminal-success, terminal-failure, and terminal-cancellation. These map to seven logical state types, with terminal states split into three distinct schema values to differentiate successful completion from error conditions.

How does Archify visually distinguish between waiting and executing states?

The renderer in archify/renderers/lifecycle/render-lifecycle.mjs assigns bands to waiting states (category wait) that visually separate them from active processing states (executing and pre-process). Waiting states appear as distinct interruptions in the horizontal rail, typically with different background styling or padding, while executing states flow continuously along the main rail track.

Can I define custom state categories beyond the seven built-in types?

No, the lifecycle schema enforces a closed enum of category values. All states must declare one of the predefined categories—start, pre-process, executing, wait, review, terminal-success, terminal-failure, or terminal-cancellation—to ensure consistent rendering behavior. Custom visual distinctions should be achieved through state id and label properties rather than new category types.

Where is the lifecycle rendering logic implemented in the Archify source code?

The primary rendering implementation resides in archify/renderers/lifecycle/render-lifecycle.mjs. This module consumes the state category metadata to calculate positions on the lifecycle rail, determine band placement for waiting periods, and assign color codes to terminal states. The CLI entry point at archify/bin/archify.mjs invokes this renderer when processing lifecycle diagram commands.

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