Understand subsystem coupling

The problem

At some point in every growing project, the package graph stops being readable. Two hundred nodes, edges everywhere. Zooming in only gives you a denser version of the same question. You need to know where architectural pressure concentrates, which boundary contains it, and whether the coarse area looks different from the packages visible inside it.

Why it matters

Boundaries determine how independently parts of the codebase can evolve. Heavy incoming pressure makes an area load-bearing. Heavy outgoing pressure makes it sensitive to many external seams. Pressure that disappears at the parent boundary but reappears among its children tells you the coarse area contains the coupling rather than exporting it. Subsystems makes those differences visible before a boundary change turns into a much larger refactor.

Where to start

Begin with Subsystems.

Step by step

1. Open the Subsystems view.

   Switch to the Subsystems lens. It maps the package or source-folder boundaries currently visible in Topology and Matrix. Every bubble uses subtree rollup metrics, while terminal packages remain valid one-unit boundaries.

2. Inspect cross-subsystem flow.

   Select "Boundary Risk" to plot outgoing boundary dependencies on X and incoming boundary dependencies on Y. Bubbles in the upper-right carry substantial pressure in both directions. Hover to see the exact values and size context.

3. Compare the other subsystem questions.

   Switch to "Visibility Surface" when the current analysis supplies visibility metrics to find broad or abstract public surfaces. Then use "Internal Tangles" to compare package-cycle groups fully contained by each boundary. These are separate readings of the same boundary map, not extra evidence folded into Boundary Risk.

4. Read coarse and fine boundaries together.

   A dashed ring marks an expanded parent whose visible descendants are also plotted. The parent tells you how the whole boundary behaves. Its descendants show where pressure sits inside it. They are different perimeter readings, not duplicate or unrelated peers.

5. Change the level when you need to.

   Expand or collapse packages in Topology or Matrix to change the shared boundary map. Double-click a non-terminal Subsystems bubble to make it Current Focus. Selecting a terminal bubble opens its package details instead.

6. Verify the concrete dependencies.

   Open Boundary Matrix from a suspicious boundary when you need exact package-to-package crossings. If the concern is a class or source-file tangle inside a terminal package, open Package Internals in Topology.

Interpreting results

A boundary with substantial incoming and outgoing pressure is the strongest coupling seam in the current map and deserves concrete inspection. High incoming pressure often marks a shared or load-bearing area. High outgoing pressure often marks orchestration, integration, or an area spread across many seams. Neither role is automatically wrong.

Compare the dashed-ring parent with its visible descendants. If child-to-child traffic disappears at the parent perimeter, the coarse boundary is containing that coupling. If the parent remains highly exposed, the pressure crosses the larger boundary too. That distinction tells you whether to improve the internal partition or reconsider the wider boundary.

Export & share

Export the current view as PNG for architecture review sessions. The Subsystems CSV contains the plotted rollup metrics and each boundary's role, so expanded aggregate parents, collapsed subtrees, and terminal one-unit boundaries remain distinguishable outside the chart.