# Archify Atomic Delivery Workflow and Staging Explained: A Complete CI/CD Pipeline Guide

> Master the Archify atomic delivery workflow and staging for a robust CI/CD pipeline. Ensure verifiable and recoverable stages from commit to production.

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

---

**Archify models CI/CD delivery pipelines as typed workflow diagrams with atomic validation, ensuring that every stage—from developer commit to production rollout—is individually verifiable and safely recoverable.**

The Archify open-source project transforms release management into **machine-validated, human-readable diagrams**. Its atomic delivery workflow guarantees that no partially validated artifact ever reaches production, while its staging model makes cross-environment constraints explicit through lanes, phases, and groups.

---

## The Atomic Delivery Guarantee in Archify

According to the Archify source code, the `deliver` command enforces **all-or-nothing validation** before writing any artifact to disk. This atomicity prevents the "half-deployed" states that plague traditional CI/CD systems.

The validation pipeline runs three consecutive checks:

1. **Schema validation** against [`workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/workflow.schema.json) — enforces required fields, node/edge types, and variants.
2. **Layout validation** — verifies orthogonal arrows and label-route clearance.
3. **Quality-profile validation** — applies domain-specific rules (e.g., `showcase` profile).

Only when **all** checks pass does the atomic replacement occur. As implemented in `archify/bin/archify.mjs`, the `deliver` step swaps the previous HTML output for the newly validated one—never leaving the system in an intermediate state.

---

## Staging Model: Lanes as Deployment Environments

The **canonical Release Delivery workflow** lives in [`archify/examples/release-delivery.workflow.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/release-delivery.workflow.json). Its six **lanes** function as explicit staging boundaries, each representing a deployment environment with distinct ownership and validation rules.

| Lane | Purpose | Key Nodes |
|------|---------|-----------|
| **Developer** | Source change origination | `commit`, `pull_request` |
| **CI** | Reproducible build and blocking checks | `build`, `checks` |
| **Release Governance** | Human approval gate | `approval` |
| **Production** | Deployment and health verification | `deploy`, `verify_prod` |
| **Communication** | Public announcement | `announce` |
| **Exceptions** | Error handling and recovery | `failed`, `rollback` |

Each lane renders as a vertical swim-lane in the SVG output (lines 16-21 of the JSON). The **cross-lane constraints** are made visible through the `groups` section (lines 28-31), which includes:

- **Blocking checks** — forces CI lane success before approval becomes reachable.
- **Recovery path** — visually connects failure nodes across lanes.

---

## Phases, Groups, and Control Flow

Beyond lanes, Archify organizes workflows into **phases** and **groups** that provide higher-level staging abstractions.

### Phases (Logical Stage Bands)

Phases group adjacent columns into colored bands representing pipeline stages (lines 24-27):

- **Change** — initial code modification.
- **Build + verify** — artifact construction and quality gates.
- **Promote + observe** — production deployment and monitoring.

### Edges with Semantic Variants

Edges encode **control-flow semantics** through typed variants (lines 45-55):

| Variant | Meaning | Typical Use |
|---------|---------|-------------|
| `emphasis` | Standard progression | Success paths |
| `security` | Critical control point | Approvals, rollbacks |
| `dashed` | Conditional or failure | Exception routing |

Routing hints (`drop`, `outside-right`, `return-left`) prevent visual clutter when failure paths must cross multiple lanes.

---

## Failure Handling and the Rollback Path

The Archify atomic delivery workflow includes **explicit failure branches** that route to the Exceptions lane. Two primary failure modes trigger automatic rollback:

1. **Quality gate failure** — `checks → failed` (CI validation fails).
2. **Production verification failure** — `verify_prod → rollback` (deployment unhealthy).

The rollback edge (lines 53-55) uses:
- **Security variant** — signals criticality.
- **Outside-right route** — visually separates from forward-only flow.
- **Return-left hint** — routes back to an earlier recovery point.

This makes the **exception lane** a first-class staging environment, not an afterthought. Stakeholders can trace "what happens when" directly in the diagram without reading documentation.

---

## Meta Views and Interactive Tracing

The `meta.views` section (lines 9-13) provides **pre-defined focus shortcuts**:

```json
"views": [
  {"id": "commit-to-checks", "name": "Commit to green build"},
  {"id": "approval-to-production", "name": "Approval to production"},
  {"id": "rollback-path", "name": "Rollback path"}
]

```

These enable:
- **Per-stage focus** — isolate specific pipeline segments.
- **Card-driven storytelling** — three explanatory cards summarize audit-trail requirements.
- **Interactive tracing** — click any node to see upstream/downstream reachability.

---

## CLI Commands for Atomic Delivery

Use these commands to validate, preview, and deliver workflows with atomic guarantees.

**Validate a workflow against schema and quality profile:**

```bash
node archify/bin/archify.mjs validate workflow \
  archify/examples/release-delivery.workflow.json \
  --quality showcase \
  --json

```

**Preview locally before delivery:**

```bash
node archify/bin/archify.mjs preview workflow \
  archify/examples/release-delivery.workflow.json \
  /tmp/release-delivery.html \
  --quality showcase

```

**Atomically deliver (replaces previous HTML only on success):**

```bash
node archify/bin/archify.mjs deliver workflow \
  archify/examples/release-delivery.workflow.json \
  examples/release-delivery.html \
  --quality showcase \
  --open

```

The `validate` step enforces atomic guarantees; `preview` supports rapid authoring loops; `deliver` performs the final all-or-nothing write.

---

## Key Source Files

| File | Role |
|------|------|
| [`archify/examples/release-delivery.workflow.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/release-delivery.workflow.json) | Full JSON IR of the atomic delivery pipeline |
| [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) | JSON-Schema defining node types, edge variants, and validation rules |
| `archify/bin/archify.mjs` | CLI entry point for `validate`, `preview`, `deliver` |
| [`archify/examples/incident-response.workflow.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/incident-response.workflow.json) | Companion example showing runbook staging model |
| [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) | Formal contract for delivery semantics |

---

## Summary

- **Atomic validation** ensures no partially validated workflow ever reaches production—the `deliver` command validates schema, layout, and quality profile before any disk write.
- **Lanes as stages** create explicit ownership boundaries: Developer → CI → Release Governance → Production → Communication → Exceptions.
- **Cross-lane groups** make blocking constraints visible, such as required CI checks before human approval.
- **Semantic edge variants** encode control flow: emphasis for success, security for critical gates, dashed for exceptions.
- **Rollback paths** are first-class diagram elements with dedicated routing hints, not hidden in documentation.

---

## Frequently Asked Questions

### How does Archify prevent half-validated workflows from being delivered?

The `deliver` command in `archify/bin/archify.mjs` performs three validations—schema, layout, and quality profile—entirely in memory. Only when all pass does it atomically replace the previous HTML output. If any check fails, no file is modified and the command exits with an error code.

### What is the difference between `preview` and `deliver` commands?

`preview` generates a temporary HTML file for local inspection without validation guarantees, supporting rapid authoring iterations. `deliver` enforces the full atomic validation pipeline and performs a permanent, all-or-nothing write to the specified output path.

### How do lanes represent deployment environments in Archify?

Each lane in [`release-delivery.workflow.json`](https://github.com/tt-a1i/archify/blob/main/release-delivery.workflow.json) corresponds to a responsibility domain that functions as a staging boundary: code originates in Developer, builds in CI, gains approval in Release Governance, deploys to Production, announces in Communication, and recovers through Exceptions. The vertical swim-lane rendering makes environment progression visually explicit.

### Can Archify workflows model rollback and failure scenarios?

Yes—failure nodes (`failed`, `rollback`) live in the dedicated Exceptions lane. Edges from quality gates or production verification route to these nodes using security-variant, outside-right-routed edges that visually separate exception paths from normal flow. The `meta.views` include a dedicated "Rollback path" focus shortcut.