What Is Canonicalization in Archify's Architecture Comparison? A Deep Dive into Deterministic Diagram Diffing

Canonicalization in Archify is the deterministic process that transforms an authored architecture diagram into a stable, viewer-state-free artifact, enabling reliable before-and-after comparisons by stripping transient UI decorations and ensuring identical inputs always produce identical SVG, HTML, or PNG outputs.

Archify (available at tt-a1i/archify) uses canonicalization to solve the problem of comparing architecture diagrams across versions. When you generate a diagram from a JSON intermediate representation (IR), the raw output often contains viewer-specific state like camera transforms or animation frames that make diffing unreliable. Canonicalization freezes the diagram into its pure, author-intended form.

What Is Canonicalization in Archify?

Canonicalization is the core pipeline that converts a language model-generated JSON IR into a deterministic, stable artifact. According to the source code in archify/renderers/architecture/render-architecture.mjs, this process deliberately removes any runtime-specific metadata while preserving the structural "truth" of the diagram.

The process guarantees three critical properties:

• No viewer-state or runtime decorations – UI-only overlays, temporary camera transforms, and animation frames are stripped out entirely.
• Exact, reproducible output – The same JSON source always yields the identical SVG, HTML, PNG, or share-card, which is essential for reliable diffing.
• Immutable snapshots – Once generated, a canonical artifact represents an immutable state of the architecture at a specific point in time.

In archify/SKILL.md, the contract for rendering explicitly defines canonical export as the standard output format for all durable artifacts, ensuring that downstream tools can depend on consistent structure.

Why Canonicalization Matters for Architecture Comparison

Architecture comparison in Archify relies on deterministic delta analysis between two canonical snapshots. Without canonicalization, comparing a "Before" and "After" state would generate false positives from incidental UI variations rather than actual structural changes.

The comparison workflow operates as follows:

1. Generate canonical snapshot A – The base architecture state is rendered to a canonical HTML/SVG file.
2. Generate canonical snapshot B – The updated architecture is processed through the same canonicalization pipeline.
3. Execute delta analysis – The compare architecture CLI command runs a deterministic analysis that reports exactly which components were added, removed, changed, or moved.

Because both snapshots are canonical, the diff is guaranteed to be repeatable and free from transient rendering differences. The test suite in archify/test/architecture-delta.test.mjs verifies this behavior by asserting that identical inputs produce byte-identical outputs before comparison logic executes.

How to Generate Canonical Artifacts in Archify

Archify provides CLI commands to generate canonical artifacts for sharing and comparison. These commands are implemented in archify/bin/archify.mjs.

Exporting a Canonical Share Card

The Copy Share Card command creates a canonical 1200 × 630 PNG image suitable for READMEs or release notes:

node archify/bin/archify.mjs deliver architecture examples/web-app.architecture.json \
    ./web-app-canonical.html --quality showcase --open \
    && node archify/bin/archify.mjs export --type png ./web-app-canonical.html

This produces:

• web-app-canonical.html – The canonical HTML representation
• A PNG file containing the exact, repeatable visual representation of the diagram

Comparing Two Canonical Snapshots

The Architecture Delta command compares two canonical snapshots and generates an HTML report:

node archify/bin/archify.mjs compare architecture \
    examples/web-app-before.architecture.json \
    examples/web-app-after.architecture.json \
    ./web-app-delta.html --json

The output web-app-delta.html contains a precise listing of facts such as:

• Added components
• Removed edges
• Changed roles
• Moved relationships

All derived from the canonical versions of the diagrams stored in the JSON files.

The Canonicalization Pipeline: Key Implementation Files

Understanding canonicalization requires examining specific files in the tt-a1i/archify repository:

archify/renderers/architecture/render-architecture.mjs The core renderer responsible for building canonical SVG and HTML output. This module ensures that all generated markup excludes viewer-specific state and follows deterministic ordering of elements.

archify/SKILL.md Defines the full contract for rendering, validation, and canonical export. This document specifies which properties must be preserved and which must be stripped during the canonicalization process.

archify/test/architecture-delta.test.mjs The test suite that verifies canonical delta behavior. These tests ensure that the comparison logic receives truly canonical inputs and produces consistent, predictable diffs.

docs/research-architecture-delta-pr-proof-2026-07-23.md Contains an in-depth discussion of the canonical delta proof-of-concept, including edge cases handled by the canonicalization algorithm.

examples/web-app.architecture.json A concrete example of architecture source JSON used to generate canonical artifacts, demonstrating the input format before canonicalization processing.

Summary

• Canonicalization transforms transient architecture diagrams into deterministic, stable artifacts by stripping UI-only state and runtime decorations.
• The process enables reliable architecture comparison by ensuring that "Before" and "After" snapshots are byte-for-byte reproducible when their source JSON is unchanged.
• Archify generates canonical share cards at 1200 × 630 resolution for documentation and canonical delta reports via the compare architecture CLI command.
• Key implementation files include render-architecture.mjs for rendering logic and architecture-delta.test.mjs for validation of comparison behavior.

Frequently Asked Questions

What file formats does Archify's canonicalization support?

Archify outputs canonical artifacts in SVG, HTML, and PNG formats. The archify/bin/archify.mjs export command supports --type parameters for selecting between these formats, with HTML serving as the canonical intermediate representation that other formats are derived from.

How does canonicalization prevent false positives in architecture diffs?

By removing viewer-state variables such as camera position, zoom level, and animation frames, canonicalization ensures that only structural changes to components, edges, and relationships appear in the delta report. As documented in the research notes, this eliminates noise from incidental rendering variations that would otherwise appear as false modifications.

Can I customize what gets stripped during canonicalization?

According to archify/SKILL.md, the canonicalization contract is strictly enforced to guarantee interoperability. While the renderer in render-architecture.mjs handles the stripping logic, the specific attributes removed (such as camera transforms and temporary overlays) are standardized across all exports to maintain consistency in the comparison pipeline.

What is the standard resolution for canonical share cards?

The Copy Share Card command generates canonical images at 1200 × 630 pixels, an aspect ratio optimized for social media sharing and documentation embedding. This resolution is hardcoded in the delivery pipeline to ensure consistent branding across all exported architecture diagrams.

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