Risk

Hotspots

A metric-space lens with Map and Galaxy renderers for comparing package or class signals, then relating nearby package candidates through real dependencies.

The Hotspots lens plots packages or classes in metric space so outliers are visible before you choose a refactoring target. It has two renderers. Map shows which packages stand out. The Galaxy Chart adds another signal and reveals which nearby candidates actually depend on one another.

The question the lens answers is specific: which packages or classes deserve attention first? A gnarly package that nothing else uses is a local problem. A gnarly package that half your service layer depends on is a systemic one. Plotting multiple dimensions at once lets you stop guessing about where to focus refactoring effort.

Hotspots opens in Package Map, Recursive scope, with the Coupling preset. That gives the first read a reproducible question before you change item type, scope, axes, or renderer.

Map View

Map is the direct two-dimensional read. X and Y position each point, while size and colour add two more signals. What a quadrant means depends on the selected preset. Zone Map has the familiar Instability and Abstractness zones. Complexity, Coupling, CC vs Coverage, and the other presets ask different questions, so there is no universal dangerous corner or universally safe centre.

Start with a built-in preset when you want a reproducible question, then adjust the metrics when the evidence points somewhere more specific. Direct and Recursive scope, Packages and Classes, and the selected point stay part of the investigation when you change renderer.

Screenshot: opening Package Map with Coupling preset, X and Y axes, size and colour legends, ranked list, and one selected package

The reproducible first shortlist. Show the complete two-dimensional Map instrument before Galaxy adds depth or Routes.

Galaxy View

In the Galaxy view, each star uses five metric channels: X, Y, Z/depth, size, and colour. Switching from Map to Galaxy continues the current reading. It preserves the item type, scope, X, Y, size, colour, and selected point, then adds a depth metric.

Opacity is not a separately selectable sixth channel. The selected Depth metric drives Z position and a coupled prominence treatment: values sent backward become smaller and more transparent while remaining plotted. The Size metric still determines each star's base size. Bring forward chooses whether high or low Depth values remain brighter and in front. Rotating the chart changes the camera, not that semantic direction.

In package mode, Routes overlay real dependencies between plotted packages that also sit near each other in X, Y, and depth. Blue leaves the active package, gold enters it, and pink means traffic runs both ways. Routes are capped and pruned for legibility, so a missing line does not prove there is no dependency. Class mode has no package dependency routes.

The trade routes are not decoration. They show whether a hotspot stands alone or travels with company.

Screenshot: Galaxy continuing the same Coupling Map population with Depth, Bring forward, selected star, five channel labels, and visible Routes

The Map question gains architectural reach. Keep the item, scope, X, Y, size, colour, and selection identical to the Map shot so Depth and Routes are the only new evidence.

Named Galaxy reframes

Risk horizon, Maintenance abyss, Coupling galaxy, and Complexity frontier are not visual skins. Choosing one deliberately replaces all five metric channels and asks a fresh question; it does not pretend to continue the Map preset you were reading.

Screenshot: Risk horizon with all five channel labels and High values forward

Stability and reach. Instability × Fan-in; CC Max sets base size, Distance sets colour, and Fan-out controls depth.

Screenshot: Maintenance abyss with all five channel labels and Low values forward

Large, difficult, weakly covered code. LOC × CC Max; Fan-in sets base size, Distance sets colour, and line coverage controls depth.

Screenshot: Coupling galaxy with all five channel labels and Low values forward

Incoming and outgoing reach. Fan-out × Fan-in; Distance sets base size, Instability sets colour, and Abstractness controls depth.

Screenshot: Complexity frontier with all five channel labels and High values forward

Two forms of complexity. CC Max × CogC Max; Fan-in sets base size, Distance sets colour, and LOC controls depth.

Package vs Class Mode

Double-click a package bubble or star to drill into that package, making it the Current Focus across lenses. Switch to Classes when you want points to represent classes inside that package; double-clicking a class opens its source file in the IDE. That class mode is a ranking and comparison tool, separate from the Topology Graph's contained package-internals layer. Package points also expose Reveal package in Project View from the context menu when you want IDE navigation without changing Current Focus.

Package mode answers "which package deserves attention?" Class mode answers "which class inside this package deserves attention?" Keep that distinction clear when using the chart for refactoring tickets: a risky package may need decomposition, while a risky class may need local simplification or characterization tests.

Screenshot: package-level Hotspots view with package names, Current Focus, ranked list, and package navigation affordance

Choose the architectural area. Points represent packages and can carry Galaxy Routes.

Screenshot: class-level Hotspots view inside the selected package with source-opening affordance and no Routes

Choose the implementation target. Points represent classes and double-click opens source.

Direct vs Recursive Scope

Direct scope plots the immediate children under the current focus. Recursive scope includes deeper descendants, which is better when a risk is buried under namespace ceremony. Direct scope is better for comparing sibling packages; recursive scope is better for finding the hidden outlier under a broad package root.

Switch scope before interpreting rank. A package that looks ordinary among direct siblings may contain a recursive class or subpackage that dominates the risk story.

Screenshot: Hotspots Direct scope showing immediate children under one Current Focus

Compare siblings. Keep the preset and encodings fixed so the direct candidate boundary is obvious.

Screenshot: same Hotspots question in Recursive scope with deeper descendants added

Find the buried outlier. The extra points come from deeper descendants, not from a changed metric question.

Cycles Only

When Cycles Only is active in package mode, Hotspots narrows the chart to cycle-participating packages. That lets you rank cycle members by complexity, coupling, size, coverage, or stability rather than treating every cycle node as equally urgent.

Cycles Only does not change the selected metrics. It changes which packages are eligible to be plotted.

Screenshot: package Hotspots with Cycles Only active, cycle-participating points retained, and the current metric encodings unchanged

Rank the cycle members. Include the active Cycles Only state and enough excluded context in the surrounding UI to make the eligibility change clear.

Native metric encodings

X, Y, size, and colour belong to the Hotspots question; Galaxy adds depth as a fifth channel. These are native metric encodings, not a Heatmap overlay. The active labels and legend define what colour means, so a red or central point has no universal interpretation outside that question.

For supported unbounded colour metrics, Metric Thresholds sets the value that reaches the strongest risk colour. Changing that ceiling immediately recalibrates compatible Hotspots colour encodings; it does not change the metric value, create a violation, define repository policy, or add a CI gate.

What carries into other lenses

Drilling into a package changes Current Focus across the shared investigation. Item type, Direct or Recursive scope, Map or Galaxy renderer, axes, preset, camera, and point selection remain Hotspots controls. A bare Map/Galaxy switch preserves the current item, scope, four Map encodings, and selection; a named Galaxy preset intentionally replaces the five metric channels with a fresh question.

Take the hotspot read with you

Snapshot as PNG preserves the active Map or Galaxy presentation, including Galaxy depth and visible Routes. Data as CSV exports the plotted metric table for independent sorting or filtering. Architecture Reports use deterministic Hotspots Map recipes instead of the interactive Galaxy camera.

When a hotspot read is unavailable

If Current Focus, item type, scope, filters, or Cycles Only leave no eligible points, AtlasArc names the narrowing so you can change it deliberately. If a preset or axis needs evidence the current analysis does not provide, that control is unavailable rather than approximated with another metric or plotted as zero. Switch to an available item type or question while keeping the rest of the investigation intact.