# How Archify Compares Architecture Diagrams Between Base and Head Commits

> Learn how Archify compares architecture diagrams between base and head commits. It generates an interactive HTML delta view highlighting architectural changes for your code.

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

---

**Archify generates a delta view by converting repository snapshots to typed JSON intermediate representations, then executing a compare sub-command that produces an interactive HTML diagram highlighting added, removed, changed, or moved architectural facts.**

Archify is an open-source architecture visualization tool that enables deterministic comparison of structural changes across git commits. When you need to compare architecture diagrams between base and head commits—such as when reviewing a pull request—the tool implements a validation-first workflow that transforms codebases into machine-readable snapshots before diffing. This process ensures that only verified architectural facts contribute to the final delta visualization.

## Generating JSON Intermediate Representations

The comparison workflow begins by generating **JSON Intermediate Representations (IR)** for each commit state. Archify's CLI entry point at `archify/bin/archify.mjs` provides a `generate` command that converts repository descriptions into typed JSON snapshots.

Run the generator against your base branch first:

```bash
git checkout main
node archify/bin/archify.mjs generate architecture . > base.json

```

Then generate the snapshot for your head branch:

```bash
git checkout feature-branch
node archify/bin/archify.mjs generate architecture . > head.json

```

These JSON files must conform to the schema defined in [`archify/schemas/architecture.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.json). According to [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md), a validation pipeline ensures structural integrity before any comparison occurs.

## Running the Compare Sub-Command

With both snapshots created, invoke the `compare` action implemented in `archify/bin/archify.mjs`. This command consumes the two JSON IR files and renders the delta output.

Execute the comparison:

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

```

The CLI validates both inputs against [`archify/schemas/architecture.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.json) as specified in [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md), which defines the renderer contract and validation pipeline. Only after successful validation does the tool proceed to compute differences between the base and head commits.

## Understanding the Delta Output

The resulting [`architecture-delta.html`](https://github.com/tt-a1i/archify/blob/main/architecture-delta.html) presents three logical panels: **Before**, **Delta**, and **After**. This visualization color-codes architectural facts based on their change status:

- **Added** facts appear in the head snapshot but not the base
- **Removed** facts existed in the base but were deleted
- **Changed** facts underwent modification between commits
- **Moved** facts changed location but maintained identity

Adding the `--json` flag produces a machine-readable report alongside the HTML. This JSON output describes each change with specific metadata including change type and affected node IDs, enabling integration with CI pipelines or downstream automation tools.

## Validation-First Architecture

According to the source code in [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md), the comparison relies on a strict validation pipeline. Both [`base.json`](https://github.com/tt-a1i/archify/blob/main/base.json) and [`head.json`](https://github.com/tt-a1i/archify/blob/main/head.json) must pass schema validation before the delta computation begins. This validation-first approach prevents corrupted or malformed snapshots from producing misleading architectural diffs.

The `archify/bin/archify.mjs` file implements this logic, ensuring that the compare sub-command only processes verified facts. This deterministic pipeline guarantees consistent results when comparing architecture diagrams between base and head commits across different environments.

## Summary

- Archify converts repository states to JSON IR files using the `generate` command in `archify/bin/archify.mjs`
- The `compare` sub-command requires two validated JSON snapshots and produces both HTML and JSON outputs
- Delta visualization uses color-coding to distinguish between added, removed, changed, and moved architectural facts
- Schema validation at [`archify/schemas/architecture.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.json) ensures data integrity before comparison
- Machine-readable JSON reports enable CI/CD integration for automated architecture reviews

## Frequently Asked Questions

### How does Archify validate the JSON snapshots before comparison?

Archify enforces schema validation defined in [`archify/schemas/architecture.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.json) immediately after loading the base and head JSON files. The validation pipeline, specified in [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md), ensures both snapshots conform to the expected structure before the compare logic executes any diff operations.

### Can I use Archify's comparison feature in CI pipelines?

Yes. By including the `--json` flag when running `node archify/bin/archify.mjs compare`, you receive a structured JSON report describing all architectural changes. This machine-readable output includes change types and affected node IDs, making it suitable for automated gates in continuous integration workflows.

### What types of changes does the delta diagram detect?

The HTML delta diagram identifies four categories of changes: **added** facts (new in head), **removed** facts (deleted from base), **changed** facts (modified between versions), and **moved** facts (relocated but preserving identity). These appear across the Before, Delta, and After panels in the generated visualization.

### Where is the compare command implemented in the source code?

The compare sub-command is implemented in `archify/bin/archify.mjs`, which serves as the CLI entry point. This file handles argument parsing, JSON validation against [`archify/schemas/architecture.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.json), and orchestration of the delta rendering pipeline documented in [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md).