# Archify Delivery Workflow with Receipts: A Complete Guide

> Explore the Archify delivery workflow, a four-stage pipeline generating machine-readable receipts for validated, reproducible HTML artifacts. Learn how Archify ensures artifact integrity.

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

---

**Archify's delivery workflow is a deterministic four-stage pipeline that produces machine-readable receipts to guarantee only validated, reproducible HTML artifacts are published.**

The `tt-a1i/archify` repository implements a strict delivery contract that transforms JSON intermediate representation (IR) into verified diagrams. Every delivery generates a cryptographically signed receipt recording validation checks, artifact metrics, and SHA-256 hashes, ensuring atomic replacement of artifacts only when all quality gates pass.

## The Four-Stage Delivery Pipeline

Archify processes diagrams through a deterministic pipeline that separates generation from validation and delivery. Each stage builds upon the previous, with the receipt acting as the single source of truth for artifact integrity.

### 1. Generate

An agent (such as Raven, Cursor, or Claude Code) creates a typed JSON IR describing the architecture or workflow. This source file contains the complete specification of nodes, edges, and layout rules, but contains no rendered output.

### 2. Validate

Built-in validators in `archify/bin/archify.mjs` execute against the JSON IR:

- **Schema validation**: Ensures the IR conforms to the expected type structure
- **Layout rules**: Verifies orthogonal arrows and finite SVG boundaries
- **Legend clearance**: Confirms legends do not overlap diagram elements
- **Deterministic hashing**: Computes a SHA-256 hash of the expected artifact

These checks populate the receipt fields: `schema`, `layout`, `finite_svg`, `legend_clearance`, and `artifactSha256`.

### 3. Preview (Optional)

The preview mode watches the source file for changes and reloads only after passing validation. This desktop loop keeps the last-good artifact visible while invalid changes are being edited, preventing broken diagrams from entering the delivery stage.

### 4. Deliver

The delivery stage renders the validated source to HTML (or PNG/SVG/WebM). Located in `archify/bin/archify.mjs`, the delivery program writes a **receipt JSON** containing validation results, artifact metrics, and the final SHA-256 hash. According to the logic in `scripts/package-smoke.mjs`, the CLI throws an error if the receipt indicates any failure:

```js
throw new Error('packaged workflow delivery did not return a passing receipt');

```

## Anatomy of a Delivery Receipt

The receipt is a machine-readable JSON file produced alongside the artifact. A typical receipt contains the exact checks that were run, the metrics of the rendered artifact, and whether the delivery succeeded.

Running the delivery command produces output like this:

```bash
node archify/bin/archify.mjs deliver workflow \
    examples/agent-tool-call.workflow.json \
    /tmp/workflow.html \
    --quality showcase \
    --open \
    --json

```

The resulting receipt structure follows this schema:

```json
{
  "receipt": "12 nodes · 11 edges · 9/9 checks",
  "checksPassed": 9,
  "checkCount": 9,
  "composition": {
    "status": "pass",
    "profile": "showcase"
  },
  "nodeCount": 12,
  "edgeCount": 11,
  "artifactSha256": "a1b2c3d4e5f6..."
}

```

Key fields include:
- **`checksPassed`/`checkCount`**: The ratio of successful validation checks
- **`composition.status`**: Either "pass" or "fail" indicating overall validity
- **`artifactSha256`**: The 64-character SHA-256 hash of the generated HTML file

## Atomic Replacement Guarantee

The receipt acts as an atomic gate for artifact publication. The HTML file is written **only** when `checksPassed === checkCount`, ensuring that every published diagram is reproducible and auditable.

This mechanism prevents partial or corrupted deliveries. As implemented in `scripts/package-smoke.mjs`, the delivery workflow validates the receipt before considering the operation successful. If any check fails, the previous artifact remains in place, maintaining the integrity of the documentation gallery.

## Running the Delivery Command

To execute the delivery workflow and generate a receipt, use the CLI entry point at `archify/bin/archify.mjs`:

```bash

# Generate the receipt while delivering the workflow

node archify/bin/archify.mjs deliver workflow \
    archify/examples/agent-tool-call.workflow.json \
    ./my-workflow.html \
    --quality showcase \
    --json

```

This command:
1. Validates the source JSON against schema and layout rules
2. Renders the HTML artifact
3. Computes the SHA-256 hash
4. Writes both [`my-workflow.html`](https://github.com/tt-a1i/archify/blob/main/my-workflow.html) and its accompanying receipt

## Programmatic Receipt Validation

Downstream consumers can verify deliveries without re-running the entire pipeline by inspecting the receipt file:

```js
const receipt = JSON.parse(
  fs.readFileSync('my-workflow.html.receipt.json', 'utf8')
);

if (receipt.checksPassed !== receipt.checkCount) {
  throw new Error('Delivery failed – see receipt for details');
}
console.log('Delivery succeeded! SHA‑256:', receipt.artifactSha256);

```

For automated testing, assert against specific receipt fields:

```js
import assert from 'assert';
import receipt from '../my-workflow.html.receipt.json';

assert.equal(receipt.checksPassed, receipt.checkCount);
assert.ok(receipt.artifactSha256.length === 64);

```

The [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) file defines the complete receipt schema and delivery contract, while `docs/gallery/artifacts/` contains real-world examples of delivered HTML files with their corresponding receipts.

## Summary

- Archify's delivery workflow consists of **Generate**, **Validate**, **Preview**, and **Deliver** stages
- The **receipt** is a JSON file recording validation checks, metrics, and SHA-256 hashes
- **Atomic replacement** occurs only when `checksPassed` equals `checkCount`
- **Programmatic validation** allows downstream tools to verify artifacts without re-running validators
- Key files include `archify/bin/archify.mjs` (CLI), [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) (schema), and `scripts/package-smoke.mjs` (CI validation)

## Frequently Asked Questions

### What happens if validation fails during delivery?

If any check fails during the delivery stage, the CLI throws an error and the artifact file is **not** replaced. As seen in `scripts/package-smoke.mjs`, the workflow ensures that only receipts with `checksPassed === checkCount` authorize artifact publication, preventing invalid diagrams from entering the gallery.

### Where is the receipt stored after delivery?

The receipt is written alongside the output artifact with a [`.receipt.json`](https://github.com/tt-a1i/archify/blob/main/.receipt.json) extension. For example, delivering to [`./my-workflow.html`](https://github.com/tt-a1i/archify/blob/main/./my-workflow.html) produces [`./my-workflow.html.receipt.json`](https://github.com/tt-a1i/archify/blob/main/./my-workflow.html.receipt.json) in the same directory, making it easy for CI systems to locate and validate.

### Can I verify a delivered artifact without re-running the pipeline?

Yes. The receipt contains the `artifactSha256` field, which is the SHA-256 hash of the generated HTML file. Consumers can compute the hash of the artifact locally and compare it against the receipt value to verify integrity without executing the validation suite.

### What checks are recorded in the receipt?

The receipt records schema validation, layout rules (orthogonal arrows, finite SVG, legend clearance), and composition status. Specific fields include `schema`, `layout`, `finite_svg`, `legend_clearance`, and `composition.status`, providing a complete audit trail of the validation process.