Architecture Doctor

Find the structural problems that slow the team down, prove it with numbers, and fix them in steps small enough to merge on their own. A problem in code nobody changes costs nothing, so churn decides the order.

1. Measure

python3 scripts/arch_report.py .                                   # ranked problems + every table, last 180 days
python3 scripts/arch_report.py . --layers "ui,pages>services>db"   # left may import right, never the reverse
python3 scripts/arch_report.py src --days 90 --top 20 --json > /tmp/arch.json
python3 scripts/arch_report.py . --exclude 'src/generated/*' --exclude '*.pb.go'

It parses Python, JS/TS (tsconfig paths) and Go imports, leaves tests out (--include-tests keeps them) and works without git, skipping churn with a note. Thresholds: --god-lines 500 --god-fan-in 5 --hub-min 5 --hot-min 5, hidden coupling --min-shared 3 --min-ratio 0.5, commits touching more than --max-commit-files 30 files are ignored for co-change. Exit codes: 0 report written, problems or not · 2 not a directory, no source files, or a bad --layers.

Instability is I = Ce / (Ca + Ce), where Ca counts files outside that import it and Ce counts files outside it imports. Near 0 means many depend on it, so it should be stable and rarely change; a low-I file with high churn is where changes ripple. A hotspot is commits in the window times lines. The hidden-coupling ratio is shared commits divided by the average commit count of the pair. The score is weight times (1 + commits touching the files): use it to pick what to read, not as a verdict. In Go an import names a package, so every file in it gets the edge, which means Go fan-in is best read at module level.

Exclude generated code (ORM types, protobuf, API clients) first. It dominates god-file lists and nobody edits it by hand.

2. Read the top offenders

Open the top 5-8 problems and decide whether each one is real.

For a god file, ask how many unrelated reasons it changes for. Group its functions by caller; groups that never call each other can be split. Look for shallow modules too (Ousterhout): a wrapper whose interface is as large as what it hides adds a hop and no value, while a deep module hides a lot behind a small interface. Merge the shallow ones and keep the deep ones.

For a cycle, find the one import that points the wrong way. For module cycles the report already names the cheapest edge to cut. A layer violation is usually a type or helper that lives in the wrong layer.

3. Check which problems actually hurt

git log --since=180.days --format='%h %ad %s' --date=short -- path/to/file      # why does it keep changing?
git log --since=180.days --format='%h %s' -- a.py b.py | head -20               # what ties a co-changing pair together?

Read the commit messages. Repeated "fix" commits or one feature touching five layers is real cost. A hidden-coupling pair usually shares knowledge nobody wrote down: a duplicated constant, schema, enum or protocol. Drop problems that are old and stable, and say you dropped them.

4. Propose 3-5 refactors, highest payoff first

Patterns for each problem type are in references/refactor-patterns.md. For each refactor write:

### 1. Split billing/service.py by reason to change   (payoff: high · effort: M)
Evidence:     1,240 lines, imported by 18 files, 37 commits in 180 days (2nd hotspot); co-changes with
              api/invoices.py in 9 of 12 commits with no import between them.
Target shape: invoice building, tax rules and payment calls in three modules behind the current
              public functions, which stay as thin re-exports until callers move.
First step:   Move the tax functions to billing/tax.py and re-export them from service.py. No caller changes.
Verify:       Characterization tests on the public functions pass before and after. arch_report shows
              service.py under 800 lines and billing/tax.py with I near 0.

Payoff = churn and reach of the problem. Effort = files touched and test coverage around them. Then list what you looked at and chose not to fix.

5. Before anyone refactors

Put tests around the code first. If coverage is thin, the first step is characterization tests that pin current behaviour. Then make one move per commit (move, re-export, update callers, delete the re-export), with each commit building and passing tests. Re-run arch_report.py after each step and quote the number that improved.

What not to do

• No big-bang rewrites or "new architecture" proposals. Every step must be shippable on its own.
• No renames or folder reshuffles for taste. Moving files without cutting a dependency fixes nothing.
• No refactoring code that has no tests around it before adding them.
• Do not invent problems. If cycles are absent, nothing is a god file and churn is spread out, say the structure is healthy and stop.
• Do not treat lazy imports (inside functions, dynamic import()) as a fix for a cycle. They hide it.
• Do not edit code unless the user asks. The output is the ranked plan.