# How Archify Detects Cosmetic Reformatting Changes in Architecture Diffs

> Learn how Archify detects cosmetic reformatting in architecture diffs. It canonicalizes JSON, computes structural diffs, and filters non-rendering changes to provide accurate comparisons.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: deep-dive
- Published: 2026-09-09

---

**Archify detects cosmetic reformatting changes by first canonicalizing architecture JSON artifacts to strip visual and layout metadata, then computing a structural diff via `architectureDeltaChangeRows()`, and finally filtering out any deltas that affect only rendering properties like node coordinates, themes, or presets.**

In the `tt-a1i/archify` repository, architecture diffs must distinguish between substantive structural modifications and superficial visual adjustments. The tool achieves this distinction by normalizing JSON artifacts before comparison, ensuring that shifts in node positioning or color schemes do not trigger false semantic alerts while genuine structural changes remain visible.

## The Canonicalization Strategy

Before any comparison occurs, Archify applies a **canonicalization** step to both the previous and current architecture snapshots. This process systematically removes fields that are purely visual or layout-oriented.

The normalization strips attributes such as:

- **Node coordinates** (`x`, `y` positioning values)
- **Theme selections** (color palettes and styling configurations)
- **Preset identifiers** (viewer presets like "Classic" or "Signal Flow")
- **Rendering metadata** (any fields under `layout` or `view` schema sections)

By removing these volatile visual properties, Archify produces a normalized structural representation that reflects only the architectural topology—nodes, edges, and their semantic relationships.

## Deep Diff Computation

Once both artifacts are canonicalized, Archify executes a deep JSON diff to identify changes. This logic is implemented in `archify/delta/architecture-delta.mjs`.

The `architectureDeltaChangeRows()` function performs the comparison, traversing the normalized object trees to detect additions, deletions, and modifications. At this stage, the diff captures every structural variance between the two snapshots.

## The Cosmetic Filter

After generating the raw diff, Archify applies a **cosmetic-filter** layer. This filter examines each detected change to determine whether the modified fields belong to the visual metadata category removed during canonicalization.

If a change entry differs only in properties related to positioning, themes, or presets, the filter discards it from the final output. Changes affecting structural identifiers, connection mappings, or node types remain flagged as **semantic** changes and are surfaced in the diff view.

## Implementation in Source Code

### Core Module: architecture-delta.mjs

The primary diff logic resides in `archify/delta/architecture-delta.mjs`. This module exports `architectureDeltaChangeRows()`, which orchestrates the canonicalization, comparison, and filtering pipeline.

According to the source structure, the CLI entry point at `archify/bin/archify.mjs` imports this delta module to execute diff operations from the command line. The test suite in `archify/test/architecture-delta.test.mjs` validates that cosmetic changes are properly suppressed while structural changes are accurately reported.

### Practical Usage Example

```javascript
import { architectureDeltaChangeRows } from 'archify/delta/architecture-delta.mjs';

// Load two architecture JSON snapshots
const oldArch = await fetch('/path/to/old/architecture.json').then(r => r.json());
const newArch = await fetch('/path/to/new/architecture.json').then(r => r.json());

// Compute diff rows with automatic cosmetic filtering
const diffRows = architectureDeltaChangeRows({ before: oldArch, after: newArch });

// Output contains only semantic changes; visual reformatting is omitted
console.log(diffRows);

```

When executed, this code processes the inputs through the canonicalization pipeline. Changing a node's `x`/`y` coordinates updates only the `layout` section, which is stripped during normalization, resulting in no diff entry. Conversely, modifying a node's type or connection triggers a semantic change that appears in `diffRows`.

## Summary

- **Canonicalization** strips visual noise from architecture JSON before comparison.
- **Deep diff** identifies structural changes between normalized snapshots via `architectureDeltaChangeRows()`.
- **Cosmetic filtering** discards changes affecting only coordinates, themes, or presets.
- **Source implementation** is concentrated in `archify/delta/architecture-delta.mjs` with CLI support in `archify/bin/archify.mjs`.

## Frequently Asked Questions

### What qualifies as a cosmetic change in Archify?

Cosmetic changes include modifications to node positioning coordinates, theme selections, color palettes, and viewer preset identifiers. These properties reside in `layout` or `view` sections of the architecture schema and affect only visual rendering, not structural topology.

### How does Archify handle node coordinate changes?

Node coordinate changes are removed during the canonicalization phase that precedes diff computation. Since `x` and `y` values are stripped from both snapshots, positional shifts produce no delta entries in the final output.

### Where is the diff logic implemented?

The core diff engine is implemented in `archify/delta/architecture-delta.mjs`, specifically within the `architectureDeltaChangeRows()` function. The module is imported by the CLI entry point at `archify/bin/archify.mjs` and tested in `archify/test/architecture-delta.test.mjs`.

### Can developers customize which fields are considered cosmetic?

While the canonicalization logic follows a fixed schema targeting `layout` and `view` properties, the modular structure of `architecture-delta.mjs` allows for configuration of stripped fields. Developers can modify the normalization rules to include additional visual metadata or retain specific layout attributes if their use case requires them.