# How Lifecycle Phase Columns Align With Event Columns in Archify: A Visual Layout Guide

> Understand how Archify's lifecycle phase columns align with event columns using a visual layout guide. Learn about the +2 column offset and staggered three-band layout for clear data visualization.

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

---

**Archify's lifecycle diagrams use a fixed +2 column offset where event column N shares the same X-coordinate as phase column N+2, creating a staggered three-band layout.**

Archify renders **lifecycle diagrams** as structured visual flows with three horizontal bands: phase (main rail), event (middle band), and outcome (terminal). The alignment between **lifecycle phase columns** and **event columns** follows a deliberate mathematical offset that prevents visual collisions while enabling straight-line transitions. This article explains the exact mapping rules defined in the Archify source code and how to apply them in your own diagrams.

## The Three-Band Layout Structure

Archify organizes lifecycle diagrams into distinct horizontal lanes, each with its own column range and coordinate mapping.

| Band | Lane ID | Column Range | X-Coordinate Behavior |
|------|---------|--------------|----------------------|
| **Phase** | `main` | 0 → 4 | 94 px, 248 px, 402 px, 556 px, 710 px |
| **Event** | any event lane | 0 → 2 | Aligned under phase column **N + 2** |
| **Outcome** | `terminal` | 0 → 2 | Aligned under phase column **N + 2** |

The **phase columns** occupy the full 0–4 range on the top rail. The **event and outcome columns** use a compressed 0–2 range that maps to the right portion of the phase rail. This creates visual breathing room between the main flow and secondary events.

## The +2 Column Offset Rule

The core alignment principle is simple: **every event column is shifted right by two positions** relative to the phase rail.

- Event column **0** → aligns with phase column **2**
- Event column **1** → aligns with phase column **3**
- Event column **2** → aligns with phase column **4**

As documented in [`archify/renderers/lifecycle/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/renderers/lifecycle/README.md): "event/terminal `col: N` uses the same x coordinate as main `col: N + 2`." This offset guarantees that events never overlap with early-phase states while allowing terminal transitions to drop vertically when they terminate at aligned positions.

## Practical JSON Example

The following lifecycle diagram demonstrates proper **event column alignment** in practice. Note how the `event` lane uses `col: 0` and `col: 1`, which render beneath phase columns 2 and 3 respectively.

```json
{
  "schema_version": 1,
  "diagram_type": "lifecycle",
  "meta": {
    "title": "Sample Lifecycle Alignment",
    "viewBox": [980, 660]
  },
  "lanes": [
    { "id": "main", "label": "Phase", "type": "phase" },
    { "id": "event", "label": "Event", "type": "event" },
    { "id": "terminal", "label": "Outcome", "type": "outcome" }
  ],
  "states": [
    { "id": "s1", "lane": "main", "col": 0, "label": "Start" },
    { "id": "s2", "lane": "main", "col": 1, "label": "Processing" },
    { "id": "s3", "lane": "main", "col": 2, "label": "Review" },
    { "id": "e1", "lane": "event", "col": 0, "label": "User-Approval" },
    { "id": "e2", "lane": "event", "col": 1, "label": "External-Call" }
  ],
  "transitions": [
    { "source": "s1", "target": "e1", "type": "straight" },
    { "source": "e1", "target": "s3", "type": "straight" },
    { "source": "s3", "target": "terminal", "type": "drop" }
  ]
}

```

When rendered, `e1` appears directly beneath "Review" (phase column 2), and `e2` beneath the next phase state. The straight `s1 → e1` and `e1 → s3` transitions work cleanly because the offset positions events in the visual flow's natural path.

## Source Documentation

The alignment rules are formally specified across three key files in the `tt-a1i/archify` repository:

| File | Relevance |
|------|-----------|
| [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) | Author-facing explanation: "phase columns `0..4` occupy the main rail; event/terminal column `N` in `0..2` aligns exactly beneath main column `N + 2`" |
| [`archify/renderers/lifecycle/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/renderers/lifecycle/README.md) | Renderer implementation details and coordinate formulas |
| [`archify/schemas/lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json) | Schema validation for `col` values and lane structure |

These sources collectively enforce the offset behavior at validation, documentation, and rendering layers.

## Why the Offset Matters

The +2 offset serves two design purposes:

1. **Visual separation** — Early phase states (columns 0–1) remain unobstructed by event bands, preserving left-to-right readability of the primary flow.

2. **Transition geometry** — Events typically trigger mid-lifecycle (reviews, approvals, external calls). Aligning them with phase columns 2–4 places them where transitions naturally converge, minimizing connector line angles.

When a terminal outcome shares column alignment with its triggering event, the `type: "drop"` transition renders as a clean vertical line—an intentional visual idiom for completion in Archify's lifecycle diagrams.

## Summary

- **Lifecycle phase columns** span 0–4 on the `main` lane with fixed pixel coordinates.
- **Event columns** span 0–2 and align with phase columns via the **N → N+2** rule.
- The offset is documented in [`SKILL.md`](https://github.com/tt-a1i/archify/blob/main/SKILL.md) and implemented in [`renderers/lifecycle/README.md`](https://github.com/tt-a1i/archify/blob/main/renderers/lifecycle/README.md).
- JSON authors should assign `col` values aware that event `0` renders under phase `2`.

## Frequently Asked Questions

### How do I position an event directly under a specific phase state?

Use the inverse formula: **event column = phase column − 2**. To align under phase column 3, set `"col": 1` in the event lane.

### Can I use event columns beyond 0–2?

No. The schema in [`lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/lifecycle.schema.json) restricts event lanes to columns 0–2, and the renderer's coordinate table only defines mappings for that range. Exceeding it triggers validation errors.

### What happens if I place a phase state in column 4 and an event in column 2?

Both occupy X-coordinate 710 px. The renderer draws the phase state in the top band and the event in the middle band—vertical separation prevents overlap, and a `type: "drop"` transition between them renders as a straight vertical line.

### Where is the coordinate mapping actually calculated?

The X-coordinate lookup happens in the lifecycle renderer based on tables defined in [`archify/renderers/lifecycle/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/renderers/lifecycle/README.md) (lines 64–67). The renderer converts abstract `col` values to pixel positions using these predefined mappings rather than dynamic calculation.