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

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

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

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

Preview locally before delivery:

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):

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	Full JSON IR of the atomic delivery pipeline
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	Companion example showing runbook staging model
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 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.

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