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

> Easily compare Archify architecture diagrams using the CLI. Generate JSON receipts and HTML visualizations to pinpoint added, removed, or modified components. Automate your diagram analysis.

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

---

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

```bash

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

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