# How to Compare Two Architecture Diagrams Using Archify: The Complete Guide

> Compare architecture diagrams with Archify. This guide shows how to perform deterministic delta comparisons on JSON snapshots, generating HTML visualizations and detailed JSON receipts.

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

---

**Archify performs deterministic Architecture Delta comparisons between two validated JSON snapshots, producing both an HTML visualization and a machine-readable JSON receipt that tracks added, removed, changed, moved, or rerouted components.**

Archify is an open-source tool from the tt-a1i/archify repository that enables developers to compare two architecture diagrams programmatically. Whether you are reviewing infrastructure changes in a pull request or auditing system drift, you can compare two architecture diagrams using Archify's deterministic delta algorithm to generate reproducible visual and machine-readable reports.

## Preparing Architecture Snapshots for Comparison

Before running a comparison, both diagrams must be expressed as Archify's typed JSON Intermediate Representation (IR). The CLI validates and canonicalizes these inputs in `archify/bin/archify.mjs` before any delta calculation begins. Store your baseline and target states as separate JSON files (for example, [`base.json`](https://github.com/tt-a1i/archify/blob/main/base.json) and [`head.json`](https://github.com/tt-a1i/archify/blob/main/head.json)). The canonicalization step reorders components and connections consistently, ensuring that identical logical structures produce identical outputs regardless of input ordering.

## Running the Architecture Delta Comparison

Archify supports both CLI and programmatic workflows through the `compareArchitecture` function implemented in `archify/delta/architecture-delta.mjs`.

### CLI Usage

Invoke the comparison via the CLI entry point:

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

```

This command validates both JSON files, executes the comparison, writes an HTML artifact to [`architecture-delta.html`](https://github.com/tt-a1i/archify/blob/main/architecture-delta.html), and generates a side-car JSON receipt ([`architecture-delta-receipt.json`](https://github.com/tt-a1i/archify/blob/main/architecture-delta-receipt.json)). The receipt captures SHA-256 hashes of the raw and canonical inputs for integrity verification.

### Programmatic Usage

For custom scripts or CI integration, import the comparison function directly:

```javascript
import { compareArchitecture } from './archify/delta/architecture-delta.mjs';
import { readFileSync } from 'fs';

// Load JSON IR files
const base = JSON.parse(readFileSync('base.json', 'utf8'));
const head = JSON.parse(readFileSync('head.json', 'utf8'));

// Perform the comparison
const receipt = compareArchitecture(base, head, {
  // optional evidence about verification status
  baseVerified: true,
  headVerified: true,
});

// The receipt contains a `delta` field describing the changes
console.log('Compare receipt:', receipt);

```

## Understanding the Comparison Output

The comparison generates two primary artifacts designed for both human review and automated processing.

### The Delta Visualization (HTML)

Archify writes an [`architecture-delta.html`](https://github.com/tt-a1i/archify/blob/main/architecture-delta.html) file that renders a three-panel **Before / Delta / After** view. The rendering logic in `buildDeltaSvg` translates the structured delta object into visual differences, highlighting architectural changes such as rerouted connections or modified components.

### The Machine Receipt (JSON)

The JSON receipt contains SHA-256 hashes of both the raw and canonical inputs, ensuring integrity and reproducibility. It includes a `checks` array listing added, removed, changed, moved, or rerouted facts. Inspect specific changes programmatically:

```javascript
function listChanges(receipt) {
  return receipt.checks
    .filter(c => c.kind === 'change')
    .map(c => `${c.id}: ${c.before} → ${c.after}`);
}

```

## Core Comparison Algorithm

The `compareArchitecture` function in `archify/delta/architecture-delta.mjs` implements a deterministic comparison through these phases:

1. **Shape Validation**: The `requireComparableShape` helper verifies both snapshots share at least one component ID and compatible structures. If no shared components exist, the comparison aborts with a clear error code recorded in the receipt.

2. **Indexing**: The `stableIndex` function indexes components and connections by stable IDs, enabling precise tracking of moves and modifications rather than treating relocated elements as deletions and additions.

3. **Evidence Verification**: When verification flags are provided, the system validates that snapshots refer to the same Git repository and revision, enabling higher-trust *revision-pinned* proof levels.

4. **Semantic Hashing**: The algorithm generates semantic hashes of canonical representations to detect changes that affect logic but not visual layout.

5. **Receipt Generation**: All findings—including machine-readable error codes with suggested fixes—serialize into the receipt format validated by `archify/test/architecture-delta.test.mjs`.

## Summary

- Archify compares two architecture diagrams using deterministic **Architecture Delta** logic implemented in `archify/delta/architecture-delta.mjs`.
- Inputs must be validated JSON IR files that undergo canonicalization to ensure reproducible outputs with identical SHA-256 hashes for identical inputs.
- The CLI command `compare architecture` generates both HTML visualizations and JSON receipts via `archify/bin/archify.mjs`.
- The `compareArchitecture` function offers programmatic access for CI/CD integration, returning structured delta objects that track added, removed, changed, moved, and rerouted facts.
- Machine-readable receipts include error codes and integrity checks suitable for automated pipeline gates and audit trails.

## Frequently Asked Questions

### What input format does Archify require for comparing architecture diagrams?

Archify requires diagrams expressed as typed JSON Intermediate Representation (IR) files. Each input JSON undergoes validation and canonicalization in `archify/bin/archify.mjs` before comparison, ensuring consistent ordering of components and connections to guarantee deterministic outputs regardless of source formatting.

### How does Archify ensure deterministic comparison results?

The comparison is deterministic because the canonicalization step in `compareArchitecture` reorders components and connections consistently before rendering. This ensures the same input pair always generates identical HTML, PNG/SVG, and receipt files, enabling reliable artifact caching and reproducible architecture reviews.

### Can I integrate Archify comparisons into CI/CD pipelines?

Yes. You can invoke comparisons programmatically by importing `compareArchitecture` from `archify/delta/architecture-delta.mjs` and processing the returned receipt. The JSON receipt includes machine-readable error codes and a `checks` array suitable for automated validation gates, or you can use the `--json` CLI flag to output the receipt for shell script processing.

### What happens if the two architecture diagrams share no common components?

The `requireComparableShape` validation inside `compareArchitecture` verifies that input snapshots share at least one component ID. If no shared components exist, the comparison aborts immediately and records a machine-readable error code in the receipt with suggested fixes, preventing meaningless diff generation.