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

> Compare two architecture versions with Archify. Generate a detailed Architecture Delta report from typed JSON IR, highlighting all changes without live code or runtime data. Easy step-by-step guide.

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

---

**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.

```bash

# 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

```bash
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

```bash

# 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.

```json
{
  "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

```bash

# 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`](https://github.com/tt-a1i/archify/blob/main/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.