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

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 and 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:

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, and generates a side-car JSON receipt (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:

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 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:

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}