How to Compare Two Architecture Versions Using Archify: A Step-by-Step Guide

Archify compares two validated architecture snapshots and produces a deterministic Architecture Delta report that highlights exactly what was added, removed, changed, or moved—entirely from typed JSON IR, without requiring live code or runtime data.

Comparing architecture versions is essential for code reviews, CI gating, and tracking system evolution. Archify makes this process fully deterministic by working with stable, typed JSON intermediate representations rather than source code or external services. This article walks through the complete workflow using the official Archify CLI and core delta module.

Prerequisites: Two Validated Architecture Snapshots

Before comparison, you need two validated architecture JSON files that describe your system at different points in time. These snapshots are typically generated from earlier pipeline stages or extracted from version control.

# Generate base snapshot (before changes)

node archify/bin/archify.mjs render architecture src/v1.json v1.html

# Generate head snapshot (after changes)

node archify/bin/archify.mjs render architecture src/v2.json v2.html

Each file must contain components and connections with stable id fields. The delta algorithm uses these IDs exclusively for matching—no heuristics or name-based alignment.

Running the Delta Command

The Archify CLI (archify/bin/archify.mjs) provides the compare architecture subcommand. Its usage signature, documented in the usage() function, is:

archify compare architecture <base.json> <head.json> [output.html] [--receipt path] [--json] [--quality standard|showcase] [--repo-root path]

Basic Comparison with HTML Output

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

This generates a three-panel HTML viewer: Before, Delta (with highlights), and After.

Including a Machine-Readable Receipt

# Print receipt to stdout

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

# Write receipt to separate file

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

The --json flag outputs the receipt directly; --receipt <path> saves it to a specified file while suppressing stdout noise.

What Happens Inside the Delta Algorithm

The core implementation lives in archify/delta/architecture-delta.mjs. Here's the internal flow:

1. Normalize inputs – both JSON files are parsed and validated; malformed input triggers a detailed diagnostic via inputDiagnostic
2. Enforce stable indexing – the stableIndex function verifies every component and connection carries a persistent id
3. Compute differences – compareEntities matches objects by ID and classifies changes into categories:
   • Semantic – meaningful architectural changes
   • Evidence – documentation or rationale updates
   • Scope – visibility or boundary modifications
   • Topology – connection structure changes
   • Geometry – visual layout adjustments
   • Provenance – origin or authorship metadata
   • Presentation – styling or rendering properties
4. Generate summary – summaryFor aggregates counts by status (added, removed, changed, moved)
5. Emit artifacts – HTML viewer + optional JSON receipt

Understanding the JSON Receipt

The receipt provides structured data for programmatic consumption—ideal for CI gates, PR bots, or downstream analysis tools.

{
  "summary": { "added": 3, "removed": 1, "changed": 2, "moved": 0 },
  "changes": [
    {
      "id": "comp-42",
      "status": "added",
      "classifications": ["semantic"],
      "changedFields": []
    },
    {
      "id": "conn-7",
      "status": "changed",
      "classifications": ["geometry"],
      "changedFields": ["/route"]
    }
  ]
}

• status – one of added, removed, changed, moved
• classifications – array of semantic categories from the delta algorithm
• changedFields – JSON pointers to modified properties (empty for additions/removals)

CLI Internals: How the Command Orchestrates

archify/bin/archify.mjs performs several setup steps before invoking the delta renderer:

• Parses arguments and validates file existence
• Sets renderer environment via rendererEnv for quality profile and repository root
• Spawns the delta renderer (render-architecture.mjs) through runNode
• Handles output – writes HTML and optionally emits the JSON receipt

The quality flag (--quality standard|showcase) affects rendering fidelity in the generated viewer, not the delta computation itself.

Complete Workflow Example

# 1. Generate snapshots at two commits

git checkout main
node archify/bin/archify.mjs render architecture ./arch.json base.json

git checkout feature-branch
node archify/bin/archify.mjs render architecture ./arch.json head.json

# 2. Compare and capture receipt for CI

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

# 3. Gate: fail if semantic changes detected

cat delta-receipt.json | jq '.changes[] | select(.classifications | contains(["semantic"])) | .id' \
    && echo "Semantic changes require review" && exit 1

Key Source Files

File	Purpose
archify/delta/architecture-delta.mjs	Core delta algorithm—normalization, ID enforcement, change classification, summary generation
archify/bin/archify.mjs	CLI entry point—argument parsing, input validation, renderer orchestration, receipt output
README.md (Architecture Delta section)	Official documentation with command syntax and examples

Summary

• Archify compares architecture versions using stable id matching on typed JSON IR, not source code or runtime data
• Run archify compare architecture <base> <head> <output.html> with optional --json or --receipt flags
• The delta algorithm in architecture-delta.mjs classifies every change into semantic categories for precise tracking
• Output includes an interactive HTML viewer and a machine-readable receipt for CI integration
• File paths, function names (compareEntities, stableIndex, summaryFor), and CLI behavior are implemented exactly as specified in the tt-a1i/archify repository

Frequently Asked Questions

What format must the input files be in?

Archify requires validated architecture JSON files—the typed intermediate representation produced by Archify's own render pipeline or compatible tools. These are standard JSON with a specific schema requiring stable id fields on every component and connection. The CLI validates structure via inputDiagnostic and aborts with detailed diagnostics if parsing fails.

Can I compare architectures from different codebases?

Yes, as long as both snapshots share stable id fields for matching components. The delta algorithm in architecture-delta.mjs uses id exclusively—no package names, file paths, or other heuristics. If IDs align, you can compare across branches, forks, or even independently modeled systems.

How do I automate checks in CI using the receipt?

Pass --receipt delta-receipt.json to write the machine-readable output, then parse it with standard tools. The receipt's summary object gives aggregate counts; the changes array provides per-item details. For example, gate merges on semantic changes using jq to detect classifications containing "semantic" as shown in the workflow example above.

What's the difference between --json and --receipt?

--json prints the receipt to stdout (useful for piping); --receipt <path> writes to a file and suppresses stdout output. Both produce identical receipt content. Choose based on whether you need shell pipeline integration or persistent file artifacts.

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