Audit a module boundary

The problem

You own a module and someone asks for an architecture health report. Not "how is it going." An actual report. How many packages? How many internal cycles? What is the boundary instability? Is cohesion growing or declining? You want numbers, not impressions, and you want to be able to repeat the same check in three months to see whether things changed.

Why it matters

Module boundaries are the architectural commitments a team makes about what belongs together and how it interacts with the outside. Without periodic audits, those boundaries quietly erode: internal packages grow external callers, internal cycles accumulate, and the balance between incoming and outgoing coupling shifts in ways nobody intended. Auditing on a regular cadence gives the team a feedback loop and a set of numbers to point to when making decisions about what to refactor next.

Where to start

Begin with Topology and its Subsystem Metrics.

Step by step

1. Set the module as Root.

   Right-click the first-class module root in Topology and choose Set as Root. For a package-only subsystem, choose its folder package instead.

2. Open Subsystem Metrics.

   Select the focused module root or folder, then open Metrics → Subsystem Metrics. These measurements cover the full subtree regardless of how much of it is expanded on the canvas.

3. Expand only this module when package detail matters.

   Choose Expand completely on the focused module if the audit needs every package visible. Only that module opens; the other modules stay as they are.

4. Read both sides of the boundary.

   Exits (Ce) count dependencies the module takes on; Entrances (Ca) count outside dependents that rely on it. Read both before judging whether the module mostly provides, consumes, or coordinates.

5. Read Instability and Cohesion together.

   Instability near 0 means incoming coupling dominates; near 1 means outgoing coupling dominates. Cohesion near 1 means the internal packages are strongly self-contained, while a low value suggests a looser collection that may deserve a split. Interpret both in light of the module's job.

6. Check the cycle banner.

   Any internal cycle groups in the focused subsystem mean there is a tangle inside the boundary. Open the relevant group when the audit needs the concrete dependencies, rather than treating the aggregate count as the diagnosis.

7. Compare peer modules.

   Clear Root from the breadcrumb, choose Collapse All, and switch the heatmap to Subsystem / Instability. This closes the audit with the focused module placed beside its peers under the same reading.

Interpreting results

There is no universal healthy direction for module coupling. A shared library may have far more Entrances than Exits, while an application or orchestration module may depend heavily outward by design. Ask whether that balance fits the module's job, then read it alongside cohesion and the internal cycle evidence. The peer-module pass shows whether the focused boundary is an outlier without replacing that architectural judgement.

Export & share

Generate a Current investigation Architecture Report while the module is focused when the active audit posture belongs in the handoff. Include Global architecture model when the same packet should retain the whole-project baseline and peer context.