Semantic Diff Engine

NeoArc analyses changes as architectural decisions, not line-level diffs. Every change is classified as structural or cosmetic, giving architects a meaningful view of what actually matters.

February 23, 2026

Standard Git diffs show line-level changes in JSON files. For architecture documentation, this creates noise: a node repositioned on a diagram canvas produces dozens of changed lines that are structurally irrelevant. NeoArc's Semantic Diff Engine analyses changes at the architectural level, classifying each modification by its significance.

How It Works

Structural vs Cosmetic Changes

The engine distinguishes between changes that affect architectural meaning and those that affect presentation only:

Resource Type	Structural Changes	Cosmetic Changes
Graph Node	Label, properties, tags, constraints	x, y, isPinned
Schema	Type, extends, fields	Name, description
REST Endpoint	Method, path, parameters, requestBody	Summary, description
Diagram Shape	ShapeType, text, metadata	x, y, width, height, colours
Diagram Connection	Source, target, pathType	Waypoints, strokeColour

Change Classification

At the resource level, each change is classified into one of four categories:

UUID-Based Resource Matching

Every resource in NeoArc has a stable UUID that persists across renames, moves, and restructuring. The semantic diff engine matches resources by UUID, not by file path or display name. This means:

Rename Detection

Renaming a schema from "OrderV1" to "Order" is detected as a rename, not a delete-and-add.

Move Detection

Moving a diagram shape to a different position is detected as a cosmetic change on the same resource.

Reference Stability

References between resources use UUIDs. A renamed resource does not break its downstream references.

History Continuity

The full change history of a resource is preserved across renames and restructuring.

Integration with Git Workflow

The semantic diff engine powers several features across NeoArc:

Feature	How Semantic Diff is Used
Working tree diff	Shows architectural changes in unstaged files
Staged diff	Shows what will be included in the next checkpoint
Track comparison	Compares architectural state between two tracks (branches)
Baseline comparison	Measures drift from a governance-approved baseline
Conflict resolution	Classifies conflicts as independent (auto-resolvable) or competing (require decision)
Change feed	Generates architectural change summaries for each checkpoint

Deep Git Integration

NeoArc wraps Git with architecture-first concepts: checkpoints instead of commits, tracks instead of branches, baselines instead of tags. Semantic diff, conflict resolution, drift analytics, and shelving provide a complete governance workflow.

Drift Dashboard and Analytics

Monitor how far your architecture has drifted from a governance-approved baseline. Visual gauges, hotspot detection, change frequency heatmaps, and a chronological change feed give architects full visibility into architectural evolution.