# Archify Deliver Command: The Six Delivery Stages Explained

> Explore Archify deliver command's six essential stages: Input, Prepare, Render, Check, Receipt, and Commit. Ensure verified HTML artifacts with this atomic pipeline.

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

---

**Archify's `deliver` command executes a deterministic, atomic six-stage pipeline—Input, Prepare, Render, Check, Receipt, and Commit—that guarantees only verified HTML artifacts are published.**

Archify is an open-source toolchain that transforms JSON architecture specifications into self-contained HTML diagrams. The `deliver` command implements a fail-safe delivery pipeline designed to prevent corrupted artifacts from reaching production. According to the source code in `archify/bin/archify.mjs`, this pipeline processes every delivery request through six distinct stages that isolate the candidate artifact until final verification is complete.

## The Six Delivery Stages in Archify's Deliver Command

The delivery pipeline follows a strict linear sequence defined in the repository's [`ROADMAP.md`](https://github.com/tt-a1i/archify/blob/main/ROADMAP.md) under the *Atomic Verified Delivery* specification. Each stage must succeed before the next begins, ensuring that failures never compromise existing published artifacts.

### 1. Input Stage

The **Input** stage reads the supplied JSON description and validates that the file is both readable and syntactically correct. This initial gate guarantees that only well-formed source documents enter the processing pipeline, preventing malformed inputs from triggering errors in downstream renderers.

### 2. Prepare Stage

During the **Prepare** stage, Archify normalizes the input data by resolving relative paths, applying default values from configuration files, and setting up a temporary candidate directory. This isolation mechanism ensures that partial or failed renders never contaminate the existing artifact directory, providing a reproducible working environment for every delivery request.

### 3. Render Stage

The **Render** stage invokes the appropriate renderer module (located in `archify/renderers/*/render-*.mjs`) based on the diagram type—such as architecture, workflow, sequence, or dataflow. This renderer generates a self-contained HTML file within the candidate directory, producing the visual artifact that will eventually be delivered if all quality checks pass.

### 4. Check Stage

In the **Check** stage, Archify runs built-in artifact and composition validations via `archify/checker.mjs`. These checks verify geometry constraints, layout integrity, and reference count accuracy against Archify's quality and safety rules. If the rendered HTML violates any architectural standards, the pipeline halts here and discards the candidate.

### 5. Receipt Stage

The **Receipt** stage computes a byte count and SHA-256 hash of the verified artifact, then generates a JSON receipt documenting the outcome of all previous stages. This machine-readable proof of delivery includes cryptographic verification that CI systems and automated agents can rely on for audit trails and reproducibility guarantees.

### 6. Commit Stage

The final **Commit** stage performs an atomic rename operation, moving the candidate artifact to the final output path only if all five preceding stages succeeded. If any stage failed, Archify removes the candidate directory entirely, leaving any existing published artifact untouched. This atomic guarantee ensures that observers never see partially written or corrupted files.

## CLI Usage and Code Examples

The `archify deliver` sub-command in `archify/bin/archify.mjs` exposes these stages through a consistent CLI interface. Every execution returns a JSON receipt on STDOUT indicating success or failure.

Basic delivery of a workflow diagram:

```bash
archify deliver workflow examples/my-workflow.json \
    output/my-workflow.html --json

```

Delivery with strict visual quality checks:

```bash
archify deliver architecture arch/diagram.json \
    arch/diagram.html --quality showcase --json

```

Automated delivery with browser preview:

```bash
archify deliver dataflow dataflow.json \
    dataflow.html --open --json

```

## Atomic Delivery and Error Handling

According to [`CHANGELOG.md`](https://github.com/tt-a1i/archify/blob/main/CHANGELOG.md), Archify introduced structured receipts alongside the atomic delivery pipeline to provide deterministic feedback. A successful delivery returns a receipt containing `ok: true`, `specification.sha256`, `specification.bytes`, and `stage: "commit"`. 

When failures occur, the receipt contains `ok: false` and a `diagnostics` array identifying the exact stage that failed—whether during Input validation, Check violations, or filesystem errors in Commit. This granularity allows automation scripts to respond appropriately to specific failure modes without parsing log files.

## Key Implementation Files

- **`archify/bin/archify.mjs`**: The CLI entry point that parses the `deliver` sub-command, extracts quality flags and repository roots, sets up the environment, and orchestrates the six delivery stages.
- **`archify/renderers/*/render-*.mjs`**: Individual renderer modules invoked during the Render stage for each supported diagram type.
- **`archify/checker.mjs`**: Implements the Check stage validation logic, enforcing geometry and composition rules against rendered HTML.
- **[`ROADMAP.md`](https://github.com/tt-a1i/archify/blob/main/ROADMAP.md)**: Documents the *Atomic Verified Delivery* contract and defines the six-stage pipeline requirements.
- **[`CHANGELOG.md`](https://github.com/tt-a1i/archify/blob/main/CHANGELOG.md)**: Records the introduction of structured receipts and atomic delivery guarantees introduced in recent versions.

## Summary

- Archify's `deliver` command implements a **six-stage atomic pipeline**: Input → Prepare → Render → Check → Receipt → Commit.
- The **Commit stage** guarantees atomicity by only renaming the candidate file after all verification succeeds, preventing partial writes.
- **JSON receipts** provide machine-readable proof of delivery with SHA-256 hashes and byte counts for every successful artifact.
- The **Check stage** enforces geometry and layout rules to ensure published diagrams meet architectural quality standards.
- Source implementation resides primarily in `archify/bin/archify.mjs`, with renderers in `archify/renderers/` and validation logic in `archify/checker.mjs`.

## Frequently Asked Questions

### What happens if the Render stage fails in Archify's deliver command?

If the Render stage fails, the pipeline immediately halts and the Commit stage never executes. The Check and Receipt stages are skipped, and Archify removes the temporary candidate directory without modifying any existing output files. The JSON receipt returned to STDOUT will contain `ok: false` and a `diagnostics` array pinpointing the renderer error.

### How does Archify ensure that failed deliveries don't corrupt existing artifacts?

Archify implements an atomic commit strategy using a temporary candidate directory during the Prepare stage. The Commit stage only performs a filesystem rename of the candidate to the final output path after all five previous stages succeed. If any stage fails—including Input validation or Check failures—the candidate directory is deleted, leaving previously published artifacts completely untouched.

### What information does the JSON receipt from `archify deliver` contain?

The JSON receipt contains either success or failure metadata. On success, it includes `ok: true`, the `stage: "commit"` identifier, `specification.sha256` containing the artifact's cryptographic hash, and `specification.bytes` recording the file size. On failure, it returns `ok: false` with a `diagnostics` array describing which stage failed and why, enabling automated CI systems to react programmatically to delivery outcomes.

### Where are the delivery stages defined in the Archify source code?

The six delivery stages are explicitly documented in [`ROADMAP.md`](https://github.com/tt-a1i/archify/blob/main/ROADMAP.md) under the *Atomic Verified Delivery* section, while the orchestration logic resides in `archify/bin/archify.mjs`. The individual stage implementations are distributed across the renderer modules in `archify/renderers/*/render-*.mjs` (Render stage) and `archify/checker.mjs` (Check stage).