Zone of Pain

The problem

Maybe you know one like this: half the system leans on a package whose public types are concrete from top to bottom. Architecture conversations around it start with, "Careful, lots of things use that." The story may be perfectly reasonable. It may also mean a wide caller base has no smaller seam around the part it actually needs. The Zone Map shows you where to look.

Why it matters

The Zone of Pain combines incoming-dominated coupling with a mostly concrete public surface. A public-contract change can therefore reach a broad consumer set. That does not mean every internal edit breaks callers, and it does not make the package guilty on sight. It means the contract deserves inspection before the next cross-cutting change turns into a tour of its consumers.

Where to start

Begin with Hotspots with the Zone Map preset.

Step by step

1. Open the actual zone map.

   Start exploring clears the existing graph filters and opens Hotspots with the Zone Map preset in Packages, Recursive, Map. Your Current Focus still defines the part of the model being explored.

2. Read position before colour.

   Instability runs along X and Abstractness along Y. The lower-left contains packages where incoming coupling dominates and the public surface is mostly concrete. That position, not Distance alone, identifies the Zone of Pain.

3. Use Distance to see how far.

   Bubble size and colour both encode Distance from the main sequence. Larger, hotter bubbles sit farther from the stable-abstractions balance. Position still tells you whether the package is on the Zone-of-Pain or Zone-of-Uselessness side.

4. See which candidates carry real traffic together.

   Switch to Galaxy without choosing a named Galaxy preset. AtlasArc preserves the Zone Map reading, adds Fan-in as depth with high values brought forward, and enables Routes between nearby package candidates. Those routes show which lower-left surfaces are directly connected without changing what their Instability, Abstractness, and Distance coordinates mean.

5. Check the caller blast radius.

   Click a lower-left candidate and read its Instability, Abstractness, Distance, and raw Fan-in. Fan-in helps you rank how many consumers could be affected by a public-contract change.

6. Follow the contract behind the dot.

   Use Stable but too concrete when you need the incoming neighbours, concrete dependency evidence, and public types behind a candidate. Ask whether callers rely on a deliberately boring API or on implementation choices that deserve a smaller seam.

Interpreting results

Zone of Pain is a Martin-zone classification, not an automatic refactoring verdict. Low Abstractness says the public types are mostly concrete; it does not say the package exposes all its internals. That is a Relative Visibility question. Galaxy adds useful priority and dependency context, but Topology and concrete dependency evidence remain the place to prove what callers use. Keep and test a deliberate concrete contract. Otherwise narrow what is public, split implementation behind the contract, or introduce an interface where it creates a useful boundary. Do not add interfaces just to move a bubble.

Export & share

Export the Hotspots Zone Map as PNG to preserve the Instability, Abstractness, and Distance view. Export the Galaxy continuation when Fan-in depth and Routes help explain why one candidate deserves attention first. Pair either image with caller evidence from Stable but too concrete when an architecture review needs the reason behind a lower-left point.