Project architecture health review
The problem
Someone asks whether the codebase is getting better or worse. One score will not answer that honestly, and a tour through every chart will not help either. You need a repeatable way to orient yourself, follow the strongest signals into concrete evidence, decide what deserves action, and bring those decisions into the next review.
Why it matters
Architecture changes through hundreds of local decisions. A useful review reconnects those decisions to the shape of the whole project. It gives you enough breadth to notice new pressure and enough depth to explain it, without pretending that a metric can judge the codebase for you. Run the same loop again later and yesterday's findings become today's starting points.
Where to start
Begin with Composition, Subsystems, Hotspots, Topology, Matrix, and Architecture Reports.
Step by step
- Keep the comparison basis honest.
Use the same Analysis Source and repository scope when you want to compare reviews. Load current JaCoCo XML or LCOV if coverage belongs in this review. If coverage is not available, note that input and carry on. Missing coverage should not block the rest of the workflow.
- Orient yourself before chasing signals.
Open Composition as a neutral Sunburst measured by LOC, then use Treemap for proportional comparison. Look for shifts in package hierarchy, depth, and code-mass concentration. If this view is unfamiliar, run Inspect subsystem composition first.
- Survey subsystem pressure.
In Subsystems, move through Boundary Risk, Complexity Load, and Internal Tangles. Read incoming and outgoing pressure against each subsystem's actual job. A shared library, an application module, and an adapter are supposed to have different coupling shapes. For Java or Kotlin, Visibility Surface adds the JVM-public surface to that review.
- Follow concentrations to their contributors.
Use Hotspots for complexity and size concentrations. Load line or branch coverage in Topology when you want to put test gaps beside architectural importance. Open package details, class details, or Package Internals so the decision rests on concrete contributors rather than bubble position or colour alone.
- Inspect boundaries and cycles exactly.
Use Topology for dependency shape and Matrix for exact crossings. Open cycle groups instead of treating every cycle-coloured edge as the same problem. Red architectural, orange aggregation, and yellow nested cycles describe different shapes. Safe Havens are a broad, remembered local way to declutter a view. Intentional and Debt decisions are precise cycle records that stay searchable in the governance dialog, whether you keep them local or share them with the team.
- Make and record the next decision.
Decide whether each finding should be preserved, investigated, refactored, or governed. Record why, who needs the evidence, and what would make you revisit the decision. A review is useful when it changes the next action, not when it merely produces more charts.
- Capture the review after the live inspection.
Generate an Architecture Report with Global architecture model selected. Add Subject audit for a module or package subtree that needs focused evidence. Use the HTML report for browsing and the Printable Version for a PDF or meeting packet. The report captures the review; it does not replace the live inspection that produced the decisions.
- Feed the result into the next pass.
Compare the same project against the same analysis basis over time. NCCD is a same-project shape signal that grows with system size, not a cross-project grade or a universal threshold. ARV and GRV add JVM visibility trends for Java or Kotlin. Let meaningful changes reopen the relevant Composition, Subsystems, Hotspots, Topology, or Matrix investigation.
Interpreting results
There is no magic architecture-health score. The outcome is an evidence-backed shortlist of what to preserve, what to investigate, and what to change, plus enough recorded context to make the next review sharper. Trends tell you where to look. The package's role, concrete dependency edges, source contributors, coverage input, and governance history tell you what the trend means.
Export & share
The Architecture Report is the final capture for this workflow. Date-stamp the exported folder and store it with the decisions it supports. Compare later reports only when Analysis Source and repository scope are equivalent, and record any changed coverage or governance inputs alongside the comparison.