Skip to main content
The overlay system allows you to layer additional data on top of the base code graph. Overlays change node colors, sizes, and add visual indicators based on external data sources.

​
How Overlays Work

Overlays add attributes to existing nodes. The visualization then uses these attributes to modify the display:
1

Base Graph

Your code structure with nodes (classes, methods) and edges (dependencies, calls).
2

Apply Overlay

A plugin analyzes external data (git, coverage, etc.) and writes attributes to nodes.
3

Visualize

The frontend reads these attributes and maps them to colors, sizes, or badges.

​
Attribute Prefixes

Each overlay stores data with a unique prefix to avoid conflicts:
PrefixOverlayExample Attributes
git:Git Activitygit:churn, git:authors, git:lastModified
coverage:Test Coveragecoverage:percent, coverage:lines, coverage:branches
complexity:Complexitycomplexity:cyclomatic, complexity:cognitive
ownership:Code Ownershipownership:team, ownership:author
layout:Layout (built-in)layout:x, layout:y, layout:z
This prefix system enables clean removal—just delete all attributes starting with a prefix.

​
Overlay Definition

Each overlay defines how it should be visualized: 
interface OverlayDefinition {
  id: string;           // Unique identifier
  name: string;         // Display name
  type: 'color' | 'size' | 'badge';
  attribute: string;    // Which node attribute to visualize
  legend: Legend;       // How to interpret values
  defaultEnabled: boolean;
}

​
Visual Types

TypeEffectUse Case
colorChanges node colorContinuous values (coverage %)
sizeChanges node sizeMagnitude values (complexity)
badgeAdds icon/labelCategorical data (team name)

​
Built-in Overlays

​
Git Activity

Shows code churn and authorship:
AttributeDescription
git:churnNumber of changes to this file
git:authorsNumber of unique contributors
git:lastModifiedDate of last change
Use case: Find hotspots that change frequently and might need refactoring.

​
Test Coverage

Shows which code is tested:
AttributeDescription
coverage:percentLine coverage percentage
coverage:linesNumber of covered lines
coverage:branchesBranch coverage percentage
Use case: Identify untested code that needs attention.

​
Complexity

Shows code complexity metrics:
AttributeDescription
complexity:cyclomaticCyclomatic complexity
complexity:cognitiveCognitive complexity
complexity:locLines of code
Use case: Find overly complex code that’s hard to maintain.

​
Code Ownership

Shows team boundaries:
AttributeDescription
ownership:teamPrimary team owner
ownership:authorPrimary author
ownership:sharedWhether multiple teams touch this
Use case: Understand team boundaries and potential conflicts.

​
API Flow

​
1. List Available Overlays

GET /api/overlays
Returns all plugins and their overlay definitions.

​
2. Apply Overlay

POST /api/overlays/git-activity/apply
Runs the plugin, which writes attributes to nodes.

​
3. Fetch Graph

GET /api/graph
Nodes now include overlay attributes: 
{
  "nodes": [
    {
      "id": "MyApp.UserService",
      "name": "UserService",
      "type": "Class",
      "git:churn": 45,
      "git:authors": 3,
      "coverage:percent": 85.5
    }
  ]
}

​
4. Remove Overlay

DELETE /api/overlays/git-activity/apply
Removes all attributes with that plugin’s prefix.

​
Combining Overlays

Multiple overlays can be active simultaneously:
  • Git Activity: Colors nodes by churn
  • Test Coverage: Adds coverage badges
  • Complexity: Sizes nodes by complexity
The frontend can toggle each visualization independently.

​
Single Source of Truth

Overlay configuration lives in code, not in config files:

Do

  • Plugin defines overlays in C# code
  • API exposes overlay definitions
  • Frontend fetches and renders dynamically

Don't

  • JSON config files for overlays
  • Render config in database
  • Hardcoded colors in frontend
This ensures consistency and makes it easy to add new overlays.

​
What’s Next?

Custom Overlays

Create your own overlay plugin

Plugin System

Deep dive into the plugin architecture