# How Archify's Compare Command Works for Architecture Deltas: A Technical Breakdown

> Understand how Archify compare command works for architecture deltas. Learn how it validates JSON snapshots, computes semantic deltas, and creates HTML visualizations with cryptographic receipts.

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

---

**The `archify compare` command validates two JSON architecture snapshots, canonicalizes their structure to ensure deterministic hashing, computes a semantic delta, and atomically commits an HTML visualization paired with a cryptographic receipt.**

Archify is an open-source architecture visualization framework that treats infrastructure changes as first-class artifacts. The **Archify compare command for architecture deltas** enables teams to audit structural drift between deployment states by producing side-by-side Before/Delta/After visualizations backed by machine-readable verification receipts. This implementation guarantees reproducible diffs by canonicalizing inputs and validating each snapshot before any comparison logic executes.

## CLI Argument Parsing and Path Resolution

The compare workflow begins in `archify/bin/archify.mjs`, where the `extractCompareOptions` function (lines 74‑98) handles command-line interface parsing. The command expects the signature:

```bash
archify compare architecture <base.json> <head.json> [output.html]

```

Optional flags include `--receipt` to control side-car JSON generation and `--json` to output machine-readable results to stdout. The parser sanitizes positional arguments and rejects unknown options to prevent ambiguous inputs. Using the shared `output-path.mjs` helper, `resolveOutputPath` (lines 48‑53, 70‑75) determines safe output paths for both the HTML artifact and its companion receipt file, deriving the receipt filename by appending [`.receipt.json`](https://github.com/tt-a1i/archify/blob/main/.receipt.json) to the base output name.

## Validating and Canonicalizing Architecture Snapshots

Before any delta computation occurs, Archify validates both input snapshots to ensure structural integrity. The `renderValidatedArchitecture` function processes each JSON file through the standard architecture renderer located in `archify/renderers/architecture/render-architecture.mjs`. If validation fails, the command aborts immediately with diagnostic messages that specify whether the error occurred in the `base` or `head` side.

After successful validation, the workflow canonicalizes both inputs (lines 74‑77 in the main CLI). This sorting and deterministic layout step ensures that geometry and cryptographic hashes remain stable across different execution environments. By canonicalizing after validation but before hashing, Archify eliminates false positives caused by non-semantic formatting differences while guaranteeing that only valid architectures enter the comparison pipeline.

## Computing the Delta Intermediate Representation

With validated, canonical snapshots in hand, the command invokes `compareArchitecture` from `archify/delta/architecture-delta.mjs` (lines 80‑92). This function performs three critical operations:

1. **Semantic Hashing**: Calculates SHA‑256 hashes of each canonical diagram
2. **Fact Extraction**: Identifies added, removed, or changed architectural facts between snapshots
3. **Metadata Assembly**: Records raw hashes, byte counts, and verification flags into a comparison IR (Intermediate Representation)

The delta IR captures not just structural changes but also cryptographic proof of each snapshot's state, enabling later verification without re-accessing the original JSON files.

## Rendering Side-by-Side Visual Diffs

The visualization phase extracts SVG representations from the previously validated renders using `extractArchitectureSvg`. These raw diagrams pass through `annotateArchitectureSideSvg` to mark them as "Before" or "After" views, while `buildDeltaSvg` constructs a third visualization showing only the changed elements.

The `renderArchitectureDeltaHtml` function (lines 112‑126) assembles these three SVGs—base annotated, head annotated, and delta-only—into a single HTML artifact. This output undergoes final validation via `validateArchitectureDeltaHtml` to ensure the integration preserved semantic integrity. The resulting HTML provides an interactive, browser-ready view of architectural drift suitable for code reviews and compliance audits.

## Atomic Commitment and Receipt Generation

Archify guarantees write consistency through atomic file operations. The `commitComparePair` function (lines 14‑38) first writes both the HTML artifact and its receipt JSON to a temporary staging directory, then performs an atomic rename to the final target paths. This approach prevents partial writes and ensures that consumers never encounter corrupted or incomplete delta reports.

The receipt construction (lines 126‑135) generates a machine-readable JSON file containing the compare IR (excluding raw hashes for size efficiency), the artifact's SHA‑256 hash, byte size, and a summary of all validation checks that passed. When invoked with `--json`, the command outputs this receipt directly to stdout; otherwise, it prints a concise textual summary including output path, verification status, and receipt location.

## Practical Usage Examples

Execute a standard comparison with automatic receipt generation:

```bash
node archify/bin/archify.mjs compare architecture \
  examples/checkout-platform.base.architecture.json \
  examples/checkout-platform.head.architecture.json \
  architecture-delta.html

```

This command creates [`architecture-delta.html`](https://github.com/tt-a1i/archify/blob/main/architecture-delta.html) containing the visual diff and [`architecture-delta.receipt.json`](https://github.com/tt-a1i/archify/blob/main/architecture-delta.receipt.json) with cryptographic proofs and validation metadata.

For CI/CD pipelines requiring machine-readable output:

```bash
node archify/bin/archify.mjs compare architecture \
  examples/checkout-platform.base.architecture.json \
  examples/checkout-platform.head.architecture.json \
  --json

```

The `--json` flag suppresses HTML generation and streams the receipt JSON to stdout, enabling automated governance checks and inventory updates.

## Summary

- **Deterministic Processing**: The Archify compare command canonicalizes inputs after validation to ensure stable cryptographic hashes and eliminate formatting noise.
- **Cryptographic Verification**: Each comparison generates a receipt recording SHA‑256 hashes, byte counts, and validation flags, creating an auditable trail of architectural changes.
- **Atomic Output**: The `commitComparePair` mechanism prevents partial writes by staging files before atomic rename operations.
- **Modular Architecture**: Key logic resides in `archify/delta/architecture-delta.mjs` for delta computation and `archify/bin/archify.mjs` for orchestration, with clear separation between validation, rendering, and I/O concerns.

## Frequently Asked Questions

### How does Archify ensure that architecture deltas are deterministic?

Archify enforces determinism by running each input through `renderValidatedArchitecture` to ensure structural validity, then canonicalizing the valid snapshots (lines 74‑77). This canonicalization sorts keys and normalizes layout, ensuring that identical architectures produce identical SHA‑256 hashes regardless of original formatting. The `compareArchitecture` function then operates on these canonical forms to guarantee that delta calculations reflect only semantic changes.

### What information does the Archify compare receipt contain?

The receipt JSON records the comparison IR with added/removed/changed facts, the final artifact's SHA‑256 hash and byte size, and a summary of all verification checks that passed for the base, head, and delta views. The receipt intentionally excludes raw content hashes to reduce size while maintaining cryptographic proof of the comparison's validity.

### Can the compare command output results without generating HTML files?

Yes. When invoked with the `--json` flag, the command suppresses HTML generation and receipt file creation, instead printing the machine-readable receipt JSON directly to stdout. This mode supports CI/CD pipelines and automated governance systems that require structured data without browser-visual artifacts.

### Where does the delta computation logic live in the codebase?

The core delta algorithm resides in `archify/delta/architecture-delta.mjs`, specifically within the `compareArchitecture` function. This module handles semantic hashing, fact extraction, and IR generation. SVG manipulation helpers like `extractArchitectureSvg` and `buildDeltaSvg` also reside in this file, while orchestration logic remains in `archify/bin/archify.mjs`.