How Archify Compares Architecture Diagrams Between Base and Head Commits

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:

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

Then generate the snapshot for your head branch:

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. According to 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:

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 as specified in 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 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, the comparison relies on a strict validation pipeline. Both base.json and 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 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 immediately after loading the base and head JSON files. The validation pipeline, specified in 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, and orchestration of the delta rendering pipeline documented in archify/SKILL.md.

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