How to Compare Two Archify Architecture Diagrams: CLI and Automation Guide

Use the archify compare command to generate a JSON receipt and HTML visualization that highlights semantic differences—added, removed, or modified kinds—between two architecture JSON files.

Archify is an open-source tool for visualizing and version-controlling system architecture diagrams using a semantic JSON format. Whether you are reviewing infrastructure changes or validating deployment proposals, learning how to compare two Archify architecture diagrams helps you identify drift between frontend, backend, database, and other service kinds. The comparison engine in the tt-a1i/archify repository, documented in README_EN.md, produces machine-readable receipts and interactive HTML reports that make architectural changes visible to developers and automated CI pipelines.

Using the Archify CLI Compare Command

The primary interface for diffing diagrams is the compare command implemented in archify/bin/archify.mjs. This command accepts two .architecture.json files, computes semantic differences between component kinds, and outputs both a validation receipt and a visualization file.

Run the comparison from your terminal:

# Generate an HTML diff view (defaults to architecture-delta.html if --output is omitted)

archify compare path/to/first.architecture.json \
                path/to/second.architecture.json \
                --output diff.html

# Export only the JSON receipt for programmatic processing

archify compare path/to/first.architecture.json \
                path/to/second.architecture.json \
                --receipt receipt.json

The --output flag creates a standalone HTML file that opens in any browser, while --receipt saves the raw comparison data for CI validation.

Understanding the Comparison Receipt Structure

Every comparison generates a receipt object that follows a strict schema. As demonstrated in examples/checkout-platform-delta.receipt.json, the receipt contains:

• command: Always set to "compare"
• ok: Boolean indicating whether the comparison executed successfully
• completeness: String value (typically "complete") describing the analysis coverage
• changes: Array describing added, removed, or modified kind-to-kind relationships
• validation: Object containing checksPassed and checkCount for policy enforcement

Validating Receipts Programmatically

You can parse the receipt JSON in Node.js to enforce architectural policies before allowing deployments. The validation logic checks the ok status, completeness, and validation counters:

import { readFile } from "fs/promises";

async function validateCompare() {
  const receipt = JSON.parse(
    await readFile("receipt.json", "utf-8")
  );
  
  if (!receipt.ok ||
      receipt.completeness !== "complete" ||
      receipt.validation?.checksPassed !== receipt.validation?.checkCount) {
    throw new Error("Comparison failed – see receipt for details");
  }
  
  console.log("Comparison succeeded", receipt.changes);
}

validateCompare();

This pattern allows downstream tools to gate releases based on architectural compliance.

Rendering the Visual Diff

Opening the HTML file generated by the --output flag launches Archify’s viewer component. As shown in examples/archify-repo.html, the interface renders a side-by-side comparison with color-coded nodes and arrows. You can select up to two semantic kinds to filter the view: selecting one kind displays traffic patterns, while selecting two reveals direct-link comparisons between specific service types. The visualization embeds the original diagrams alongside the changes array, making it easy to correlate structural modifications with the visual representation.

Automating Comparisons in CI Pipelines

For continuous integration workflows, use the --receipt flag to produce machine-readable output and avoid browser dependencies. The scripts/package-smoke.mjs file demonstrates how to invoke the compare command and assert receipt properties in automated test suites. By checking that receipt.ok is true and that the changes array contains only expected modifications, you can fail builds when architectural drift violates defined policies or when unauthorized components appear in the diff.

Summary

• Use archify compare to diff two .architecture.json files via the CLI entry point in archify/bin/archify.mjs
• The command produces both an HTML report for manual review and a JSON receipt for automation
• Receipts contain changes, validation, and completeness fields that describe semantic differences between kinds
• Reference examples/checkout-platform-delta.receipt.json for the expected JSON schema
• Integrate validation logic using patterns from scripts/package-smoke.mjs to enforce architecture policies in CI/CD

Frequently Asked Questions

What file format does Archify use for architecture diagrams?

Archify uses a JSON-based format with the .architecture.json extension. These files define semantic kinds—such as frontend, backend, and database components—that the comparison engine analyzes for structural differences rather than simple text changes.

How does the Archify comparison handle renamed components?

The comparison engine tracks semantic kinds and relationships. When you compare two Archify architecture diagrams, the receipt's changes array identifies additions and removals of relationships between kinds. A renamed component appears as the removal of the old kind relationship and the addition of a new one, preserving the semantic integrity of the diff.

Can I automate architecture diagram comparisons in GitHub Actions?

Yes. Configure your workflow to run archify compare with the --receipt flag, then parse the resulting JSON to check the ok and validation fields. The validation example in scripts/package-smoke.mjs shows how to programmatically assert that checksPassed equals checkCount, allowing you to fail builds when architectural drift is detected.

What is the difference between the HTML output and the JSON receipt?

The HTML output provides an interactive visualization with color-coded nodes and arrows for manual review in a browser, based on the viewer implementation in examples/archify-repo.html. The JSON receipt contains machine-readable data about the comparison, including the changes array and validation results, designed for automated processing in CI/CD pipelines and policy enforcement scripts.

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