How to Compare Two Architecture Snapshots Using Archify

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 (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 (lines 150-155).

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 — The original architecture snapshot
• head.json — The modified architecture snapshot
• architecture-delta.html — The output HTML visualization
• --json — Also produces a machine-readable receipt file (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 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) containing a deterministic description of every detected change. This receipt enables programmatic integration into CI/CD pipelines and automated review workflows.

{
  "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 and 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.

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