Architecture Review
Use gdhealth graph and policy together for a structural codebase review.
Architecture review with gdhealth follows a three-step pattern: discover what's coupled, encode what shouldn't be, and visualize what remains.
Step 1: Map your layers
Run gdhealth graph to get a first look at the dependency structure:
gdhealth graph --root . --format textRead the output to identify which directories represent logical layers (gameplay, server, net, ui, test, etc.). Use this to define your [groups] in gdhealth.toml.
Step 2: Run the health bundle
gdhealth health --root .Open reports/code-health/summary.txt and look at:
- cross-group dependencies — which groups are coupled, and in which direction
- cycles — files that mutually depend on each other
- top files by hotspot score — where complexity has accumulated
Step 3: Encode architectural rules
Once you've identified forbidden couplings, add them to gdhealth.toml:
[[policy.forbidden_dependencies]]
from = "server"
to = "gameplay"
severity = "critical"
[[policy.forbidden_dependencies]]
from = "net"
to = "server"
severity = "warning"Re-run gdhealth health --root . to see how many existing edges violate the rules. Work through findings from critical down to warning.
Step 4: Visualize with the browser viewer
For a visual overview of the dependency graph:
gdhealth graph --root . --format emerge-htmlOpen reports/code-health/browser/emerge.html in a browser. The viewer shows:
- the file dependency graph with cluster coloring (Louvain community detection)
- per-file metrics on hover (fan-in, fan-out, hotspot score)
- the inheritance graph and complete combined graph
This is useful for presenting architecture findings to the team.
Step 5: Export to DOT for existing tools
If your team already uses GraphViz or other graph tools:
gdhealth graph --root . --format dot --output reports/code-health/graph.dot
dot -Tsvg reports/code-health/graph.dot -o graph.svgRecommended review workflow
- Run
gdhealth health --root .on the target branch - Read
summary.txt— note cycle count, cross-group count, critical findings - Open
browser/emerge.html— identify visual clusters and isolated files - Add new
[[policy.forbidden_dependencies]]rules for any coupling you want to prohibit going forward - Run
gdhealth health --root . --fail-on critical— establish the baseline - Add the CI step to enforce the baseline on future changes
The goal is not to eliminate all findings immediately — it's to encode the rules that matter to your architecture, establish a passing baseline, and prevent regression.