# How to Compare Two Architecture Snapshots Using Archify

> Easily compare two architecture snapshots using Archify. Generate precise Before Delta After visualizations to identify changes between JSON snapshots. Get started today

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-09-05

---

**Archify generates deterministic Before/Delta/After visualizations that precisely identify additions, removals, and modifications between two validated JSON snapshots.**

The open-source Archify project (`tt-a1i/archify`) enables architectural diffing by comparing validated Intermediate Representation (IR) files. Understanding how to compare two architecture snapshots allows teams to validate infrastructure changes, review refactoring decisions, and generate deterministic documentation without deploying to runtime environments.

## Prerequisites for Snapshot Comparison

Before running a comparison, you must have two **validated architecture snapshots** that conform to the Archify JSON schema. These files, typically referred to as the *base* and *head* snapshots, must pass Archify’s validation step to ensure layout rules and schema compliance. Each snapshot describes the complete architecture state at a specific point in time.

## Step 1 — Generate Validated Base and Head Snapshots

Produce two JSON IR files representing the architectural states you want to compare. These files can be generated by Archify itself or by any agent producing Archify-compatible JSON. Ensure both files pass validation—documented in [`README.md`](https://github.com/tt-a1i/archify/blob/main/README.md) (lines 18-20)—to guarantee deterministic diffing results.

## Step 2 — Execute the Comparison Command

Invoke the comparison logic through the CLI entry point located at `archify/bin/archify.mjs`. The `compare` sub-command parses both snapshots, computes the differences, and renders the output as documented in [`README.md`](https://github.com/tt-a1i/archify/blob/main/README.md) (lines 150-155).

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

```

**Command parameters explained:**
- `architecture` — The sub-command triggering diff logic
- [`base.json`](https://github.com/tt-a1i/archify/blob/main/base.json) — The original architecture snapshot
- [`head.json`](https://github.com/tt-a1i/archify/blob/main/head.json) — The modified architecture snapshot  
- [`architecture-delta.html`](https://github.com/tt-a1i/archify/blob/main/architecture-delta.html) — The output HTML visualization
- `--json` — Also produces a machine-readable receipt file ([`architecture-delta.receipt.json`](https://github.com/tt-a1i/archify/blob/main/architecture-delta.receipt.json))

The implementation in `archify/bin/archify.mjs` constructs a diff receipt containing categorized changes and generates the interactive HTML diagram showing the three views.

## Step 3 — Analyze the Delta Visualization

Open the generated HTML file in any modern browser to explore the three-pane view:

- **Before** — The baseline architecture state
- **Delta** — Highlighted changes (additions, removals, modifications)
- **After** — The target architecture state

The interface supports theme toggling, panning, zooming, and hovering over elements to inspect specific change details. For a concrete example, see [`examples/checkout-platform-delta.html`](https://github.com/tt-a1i/archify/blob/main/examples/checkout-platform-delta.html) in the repository, which demonstrates the visual output for a checkout platform comparison.

## Working with the Machine-Readable Receipt

Alongside the HTML visualization, Archify generates a JSON receipt file (e.g., [`checkout-platform-delta.receipt.json`](https://github.com/tt-a1i/archify/blob/main/checkout-platform-delta.receipt.json)) containing a deterministic description of every detected change. This receipt enables programmatic integration into CI/CD pipelines and automated review workflows.

```json
{
  "command": "compare",
  "schemaVersion": 1,
  "completeness": "complete",
  "changes": [
    {"type":"added","id":"node-42","detail":"New cache layer"},
    {"type":"removed","id":"node-17","detail":"Deprecated auth service"},
    {"type":"changed","id":"node-3","detail":"Updated DB driver version"}
  ]
}

```

**Change types detected:**
- **Added** — New architectural elements
- **Removed** — Deleted components
- **Changed** — Modified properties or configurations
- **Moved** — Relocated elements
- **Rerouted** — Altered connection paths

## Summary

- **Archify** compares two architecture snapshots by processing validated JSON IR files through the `compare` sub-command in `archify/bin/archify.mjs`.
- The command generates an interactive **Before/Delta/After** HTML visualization and a machine-readable JSON receipt.
- Change categories include **added**, **removed**, **changed**, **moved**, and **rerouted** architectural facts.
- The deterministic output allows teams to share exact architectural diffs through HTML, PNG, SVG, or JSON receipts.
- Reference implementations exist in [`examples/checkout-platform-delta.html`](https://github.com/tt-a1i/archify/blob/main/examples/checkout-platform-delta.html) and [`examples/checkout-platform-delta.receipt.json`](https://github.com/tt-a1i/archify/blob/main/examples/checkout-platform-delta.receipt.json).

## Frequently Asked Questions

### What file format is required to compare two architecture snapshots?

Archify requires validated JSON Intermediate Representation (IR) files that conform to the project's schema and layout rules. Both the base and head snapshots must pass validation to ensure accurate diffing and deterministic visualization output.

### Can I export the comparison diagram for documentation?

Yes. The generated HTML visualization can be shared directly, and the interface supports exporting the diff view to PNG or SVG formats for inclusion in documentation or pull request descriptions.

### What types of architectural changes does Archify detect?

According to the source analysis, Archify categorizes changes into five types: **added** (new elements), **removed** (deleted elements), **changed** (modified properties), **moved** (relocated components), and **rerouted** (altered connections between elements).

### Is the comparison output deterministic?

Yes. The diff generation is deterministic, meaning the same two input snapshots will always produce identical HTML visualizations and JSON receipts. This consistency enables reliable integration into automated CI/CD review pipelines.