Archify Deliver Command: The Six Delivery Stages Explained

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

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

Delivery with strict visual quality checks:

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

Automated delivery with browser preview:

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

Atomic Delivery and Error Handling

According to 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: Documents the Atomic Verified Delivery contract and defines the six-stage pipeline requirements.
• 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 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).

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