Heatmap overlay

The heatmap overlay colours the current structure by a metric you choose. It leaves the structure itself alone: same packages, same source folders, same classes, same dependencies. What you gain is the ability to read shape and risk in one glance, instead of holding one of them in your head while you stare at the other.

Reach for it once the structural question is already settled and the follow-up arrives: "fine, but which of these is actually a problem?" Unstable, too concrete, heavily depended on, complex, large, over-exposed, under-covered. The overlay is how you work out which boxes on screen have earned your afternoon.

Supported lenses

The overlay turns up wherever metric colour can sit on top of existing geometry: Topology Graph, Package Matrix, and Composition. In those three, the banner tells you both halves of the read at once, naming the active lens state and the active heatmap metric.

Subsystems and Hotspots are the exception. They already use colour natively, as part of their curated metric-space views, so there's no global overlay to add on top. Even when the metric looks like the one you picked, that colour is coming from somewhere else. It's a common enough mix-up that it gets its own section below.

Metric selection

The metric menu will colour by stability, abstraction, distance from the main sequence, relative visibility, fan-in, fan-out, size, complexity, and coverage, wherever the data exists. Java and Kotlin projects get bytecode-backed package metrics. TypeScript artifact analysis works from source-folder and source-file labels, so don't be thrown when the banner says source folder count where you were expecting class count.

One habit worth forming: pair the overlay with a structural narrowing. Current Focus, a pinned subject, Cycles Only, a filtered graph, any of them. A whole-project heatmap is good for orientation. A focused heatmap is the one that turns into a ticket.

Package and Subsystem values

The Heatmap bar can colour by Package or Subsystem. Package mode uses each visible package or source folder's own metric value. Subsystem mode colours a folder boundary with the corresponding rollup for its complete repository-scoped subtree, including architecture units currently hidden inside a collapsed boundary.

This does not switch to the Subsystems lens or alter the dependency structure. It changes the metric question asked of the same structural geometry: “how is this unit doing?” versus “what pressure is contained beneath this boundary?”

Normalization and thresholds

Colour is calibrated against metric thresholds, which is what stops a single outlier from painting the whole project red and making every codebase look equally dangerous. Green means low pressure for the selected metric. Red means high pressure. Coverage inverts that reading, because with coverage it's the weak numbers that should be pulling your eye.

When a metric has no natural ceiling, set the full-red point yourself under Metric Thresholds. It's worth the minute it takes. It's what keeps repeated investigations comparable, so you can tell a package that genuinely improved from one that merely looks better because the visible subset changed underneath it.

Composition heatmaps

Composition is a containment lens. Treemap, Sunburst, and Circle Pack draw package hierarchy and mass, never dependencies. Switch a heatmap on and that hierarchy picks up the colour of the selected metric, which is how you catch the overlap that tends to matter: the places where code mass and metric pressure are sitting on top of each other.

For package-level Composition, the colour describes the package or subtree being drawn. For class-level Composition, the metrics on offer follow whatever class and source-file evidence AtlasArc holds for the current analysis source.

Native colour versus overlay colour

Subsystems and Hotspots bake their selected view straight into X, Y, size, and colour. Subsystems Boundary Risk uses instability colour as part of the preset. Hotspots Galaxy views can use colour as one metric dimension among several. None of that is the global Heatmap overlay, however much it looks the part.

The banner settles it. If it says Heatmap, you're reading the overlay. If it names a Subsystems preset or a Hotspots view and stays quiet about Heatmap, the colour belongs to that lens's selected view.