# How the Diff-Overlay Tracks Git Changes Within the Knowledge Graph

> Discover how the diff-overlay tracks Git changes by mapping file paths to knowledge graph nodes and propagating impact. Visualize enriched context as JSON.

- Repository: [Egonex/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything)
- Tags: internals
- Published: 2026-06-18

---

**The diff-overlay tracks Git changes by mapping modified file paths to existing knowledge graph nodes, propagating impact through "contains" relationships and one-hop edges, then persisting the enriched context as JSON for dashboard visualization.**

The **diff-overlay** feature in the [Egonex-AI/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything) repository bridges Git version control with knowledge graph visualization. When developers run the `/understand-diff` skill, the system analyzes commit differences and overlays change data onto the architectural graph, highlighting exactly which components changed and what depends on them.

## Mapping Git File Changes to Knowledge Graph Nodes

### Identifying Changed Files in the Graph

The process begins in [`understand-anything-plugin/src/diff-analyzer.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/src/diff-analyzer.ts) where the `buildDiffContext` function receives the list of files changed between two Git commits. It iterates through every node in the knowledge graph, comparing each node's `filePath` property against the Git-reported changes (lines 31-42):

```typescript
for (const file of changedFiles) {
  // ...
  if (node.filePath === file) {
    changedNodeIds.add(node.id);
    // ...
  }
}

```

Files that match existing nodes are added to the `changedNodeIds` set, while unmatched paths are tracked separately as **unmapped files**—indicating the graph may need re-analysis to include new components.

### Propagating Changes to Child Nodes

Changes cascade downward through "contains" relationships. When a file node is modified, all child nodes (such as classes or functions inside that file) are also marked as changed (lines 44-49):

```typescript
if (edge.type === "contains" && changedNodeIds.has(edge.source)) {
  changedNodeIds.add(edge.target);
}

```

This propagation ensures that the `changedNodeIds` set captures both the modified files and their internal components.

## Computing Affected Nodes and Relationships

### One-Hop Impact Analysis

After identifying changed nodes, the analyzer calculates **affected nodes**—entities that share direct relationships with changed components. The system examines every edge where either the source or target is a changed node (lines 57-69):

```typescript
if (sourceChanged || targetChanged) {
  impactedEdges.push(edge);
  // ...
  affectedNodeIds.add(edge.target);
  // ...
}

```

These edges become `impactedEdges`, and the opposite endpoints become affected nodes, creating a complete picture of immediate architectural impact.

### Layer-Based Impact Detection

The analyzer then determines which architectural layers (API, Service, UI, etc.) contain changed or affected nodes (lines 74-77):

```typescript
layers.filter(layer => layer.nodeIds.some(id => allImpactedIds.has(id)))

```

This filtering allows the dashboard to highlight entire architectural slices that require attention during the commit review.

## Generating the Diff-Overlay Output

Once the context is built, `formatDiffAnalysis` converts the `DiffContext` into a structured markdown report (lines 90-197 in [`diff-analyzer.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/diff-analyzer.ts)). The skill then serializes the full context to [`.understand-anything/diff-overlay.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/diff-overlay.json) (lines 79-87):

```typescript
import { buildDiffContext } from "./diff-analyzer";
import type { KnowledgeGraph } from "@understand-anything/core";

async function generateOverlay(graph: KnowledgeGraph, changedFiles: string[]) {
  const ctx = buildDiffContext(graph, changedFiles);
  const markdown = formatDiffAnalysis(ctx);
  await Deno.writeTextFile(".understand-anything/diff-overlay.json", JSON.stringify(ctx));
  return markdown;
}

```

The resulting JSON includes the project name, original file list, changed node IDs, affected node IDs, impacted edges, affected layers, and any unmapped files.

## Visualizing Changes in the Dashboard

The dashboard dev server serves the overlay via a route configured in [`understand-anything-plugin/packages/dashboard/vite.config.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/dashboard/vite.config.ts) (lines 295-296), mapping [`/diff-overlay.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main//diff-overlay.json) to the physical file. The front-end loads this data in [`understand-anything-plugin/packages/dashboard/src/App.tsx`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/dashboard/src/App.tsx) (line 168):

```typescript
const overlayUrl = dataUrl("diff-overlay.json", accessToken);
const overlay = await fetch(overlayUrl).then(res => res.json());

```

The visualization layer applies distinct highlighting:

- **Red-tinted nodes** for changed components
- **Layer-colored nodes** for affected components  
- **Highlighted edges** showing impacted relationships
- **Unmapped files list** alerting users to graph coverage gaps

## Summary

- The **diff-overlay** correlates Git file changes with knowledge graph nodes by matching `filePath` properties in [`understand-anything-plugin/src/diff-analyzer.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/src/diff-analyzer.ts).
- **Child propagation** through "contains" edges ensures internal components inherit change status from their parent files.
- **One-hop impact analysis** identifies related nodes and edges that connect to changed components, mapping architectural ripple effects.
- **Layer detection** groups changes by architectural slice (API, Service, UI) for quick assessment of affected domains.
- The system persists results to [`.understand-anything/diff-overlay.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/diff-overlay.json) and serves them via the dashboard's Vite dev server for real-time visualization.

## Frequently Asked Questions

### How does the diff-overlay handle files not yet in the knowledge graph?

Files reported by Git that lack corresponding nodes in the graph are tracked as **unmapped files** in the `DiffContext` object. The dashboard displays these separately, alerting users that the graph may need re-analysis to include new or renamed components.

### What determines whether a node is "affected" versus "changed"?

**Changed nodes** directly correspond to files modified in the Git commit or their children via "contains" relationships. **Affected nodes** are those connected to changed nodes by any edge type within one hop—their immediate architectural neighbors that may experience impact from the changes.

### Can the diff-overlay track changes across multiple commits?

The `buildDiffContext` function accepts any array of file paths, typically generated by comparing two Git commits. While the example shows single commit comparisons, the underlying logic supports arbitrary file lists, allowing the skill to analyze ranges or custom change sets by adjusting the Git command that feeds the `changedFiles` parameter.

### Where is the diff-overlay data stored and how is it accessed?

The overlay persists as JSON to [`.understand-anything/diff-overlay.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/diff-overlay.json) in the project root. The dashboard's Vite configuration ([`understand-anything-plugin/packages/dashboard/vite.config.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/dashboard/vite.config.ts)) maps requests for [`/diff-overlay.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main//diff-overlay.json) to this physical file, enabling the front-end to fetch it via standard HTTP requests using the `dataUrl` helper with appropriate access tokens.