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

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

{
  "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	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	Renderer implementation details and coordinate formulas
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 and implemented in 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 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 (lines 64–67). The renderer converts abstract col values to pixel positions using these predefined mappings rather than dynamic calculation.

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