# State Types for Lifecycle Diagrams in Archify: The Complete Guide

> Explore Archify's seven state types for lifecycle diagrams: Start, Planning, Executing, Waiting, Reviewing, Terminal Success, and Terminal Failure. Customize visuals and workflow.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: deep-dive
- Published: 2026-09-10

---

**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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.json). Each state requires an `id`, `label`, and `category` property mapped to the valid schema values.

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

```bash
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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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.