# How the Archify Comparison CLI Generates Delta Artifacts: A 13-Step Pipeline

> Learn how the Archify comparison CLI generates delta artifacts. Discover the 13-step pipeline for comparing architecture JSON files and creating interactive HTML reports.

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

---

**The Archify comparison CLI generates delta artifacts by canonicalizing two architecture JSON files, computing SHA-256 semantic hashes, running a comparison algorithm to detect structural changes, and merging annotated SVGs into an interactive HTML report with an embedded JSON receipt.**

The `archify compare` command in the `tt-a1i/archify` repository produces a complete visual diff between two architecture diagrams. Understanding how the Archify comparison CLI generates delta artifacts requires tracing its modular pipeline from CLI argument parsing through atomic file writing, with each stage implemented in dedicated source modules.

## CLI Entry Point and Runtime Loading

The process begins in `archify/bin/archify.mjs` where the `commandCompare` function (lines 11–20) parses command-line arguments and dispatches the comparison workflow. The CLI dynamically imports the delta engine to keep the core binary lightweight.

At lines 20–24, the code attempts to import `architecture-delta.mjs` using a `try … import` block, aborting with a user-friendly error if the module cannot be found. This separation ensures the comparison logic loads only when needed.

## Safe Output Path Resolution

Before processing inputs, the CLI guarantees deterministic filenames using `resolveOutputPath` from `output-path.mjs`. Calls at lines 41–46 and 62–69 in `archify/bin/archify.mjs` validate the output location for both the HTML artifact and its accompanying receipt, preventing accidental overwrites and handling directory creation automatically.

## Input Validation and Canonicalization

The pipeline reads and validates both JSON inputs before any comparison occurs. The `renderValidatedArchitecture` function (lines 76–89) renders each file once to verify the diagrams are valid, reporting errors via `reportCompareFailure` if validation fails.

To ensure deterministic geometry, each diagram is transformed to its *canonical* form. The `canonicalArchitecture` function in `archify/delta/architecture-delta.mjs` (lines 53–66) sorts component IDs and normalizes fields, eliminating spurious differences caused by formatting variations.

The CLI then computes SHA-256 hashes of both the raw input and the canonical JSON using Node.js `createHash` (lines 73–81). These hashes become part of the receipt but are deliberately omitted from the final artifact to keep the output stable under purely cosmetic changes.

## The Comparison Algorithm and IR Generation

The core semantic analysis happens in `compareArchitecture` within `archify/delta/architecture-delta.mjs` (lines 26–88). This function analyzes the two canonical diagrams and produces a **Comparison IR** (`compareIr`) that tracks:

- Added, removed, or changed components
- Modified connections and boundaries
- Presentation and provenance changes

This intermediate representation serves as the source of truth for all downstream visual annotations.

## SVG Processing and Delta Annotation

The pipeline extracts renderable graphics from each side using `extractArchitectureSvg` (lines 26–30), which pulls the `<svg>` element from the renderer-generated HTML.

Next, `annotateArchitectureSideSvg` (lines 26–44) decorates every node, edge, and boundary with `data-delta-state` attributes and optional classification markers. This annotation makes the SVG elements self-describing, indicating exactly which items changed, moved, or remained stable.

The `buildDeltaSvg` function (lines 107–165) performs the visual merge. It combines the *base* and *head* SVGs, inserts "phantom" elements for removed or moved items, adds delta markers ( + , − , ~ , ↔ ), and prefixes all IDs to avoid collisions between the two diagrams.

## HTML Rendering and Atomic File Writing

The final artifact is constructed by `renderArchitectureDeltaHtml` in `archify/delta/architecture-delta.mjs` (lines 45–78). This generates a self-contained HTML page containing:

- The merged delta SVG with interactive annotations
- Optional embedded snapshots of raw HTML or SVG
- A JSON receipt embedded in a `<script id="archify-compare-receipt">` tag
- UI controls for view switching, export, and interactive review

The CLI writes outputs atomically. At lines 114–131 in `archify/bin/archify.mjs`, the generated HTML (`htmlCandidate`) and JSON receipt (`finalReceipt`) are written to a staging directory, then committed to the final locations via `commitComparePair` at line 158. A `finally` block (lines 80–86) ensures the temporary staging directory is removed even if errors occur.

## Practical Usage Examples

```bash

# Basic usage – compare two architecture JSON files

archify compare architecture base.json head.json delta.html

# Write the receipt alongside the HTML (explicit path)

archify compare architecture base.json head.json \
    --receipt delta.receipt.json

# Produce JSON-only output (machine-readable) without the HTML artifact

archify compare architecture base.json head.json --json

```

Each command invokes the same pipeline, differing only in the final serialization step according to the flags provided.

## Summary

- **Entry Point**: The `commandCompare` function in `archify/bin/archify.mjs` orchestrates the entire workflow, dynamically loading the delta engine at runtime.
- **Validation First**: `renderValidatedArchitecture` ensures both inputs are renderable before canonicalization or comparison begins.
- **Deterministic Geometry**: `canonicalArchitecture` normalizes diagrams to eliminate formatting-based differences.
- **Semantic Comparison**: The `compareArchitecture` algorithm generates a Comparison IR capturing changes to components, connections, and boundaries.
- **Visual Merge**: `buildDeltaSvg` creates the final overlay with phantom elements, collision-free IDs, and delta markers.
- **Atomic Output**: Files are written to a staging area and renamed atomically, producing [`architecture-delta.html`](https://github.com/tt-a1i/archify/blob/main/architecture-delta.html) and [`architecture-delta.receipt.json`](https://github.com/tt-a1i/archify/blob/main/architecture-delta.receipt.json).

## Frequently Asked Questions

### What is the purpose of canonicalization in the delta generation pipeline?

Canonicalization ensures that two semantically identical diagrams produce the same delta output regardless of formatting differences. The `canonicalArchitecture` function in `architecture-delta.mjs` (lines 53–66) sorts component IDs and normalizes fields, preventing false positives from non-semantic variations like key ordering or whitespace.

### How does the CLI prevent file collisions when writing delta artifacts?

The `resolveOutputPath` utility in `output-path.mjs` validates output paths before writing, and the `commitComparePair` mechanism (line 158 in `archify/bin/archify.mjs`) writes to a temporary staging directory first. This atomic rename pattern ensures that users never see partially written files, even if the process is interrupted.

### What information does the JSON receipt contain compared to the HTML artifact?

The JSON receipt contains machine-readable metadata including SHA-256 hashes of both raw and canonical inputs, change counts, proof levels, and provenance data. The HTML artifact contains the visual delta SVG and interactive UI but excludes the hashes to remain stable under formatting changes. The receipt is embedded within the HTML via a script tag with ID `archify-compare-receipt` for downstream tooling.

### Can the comparison run without generating the visual HTML output?

Yes. Using the `--json` flag, the CLI executes the full validation, canonicalization, and comparison pipeline but serializes only the JSON receipt to stdout or a specified file. This mode is useful for CI pipelines that need to detect changes programmatically without rendering overhead.