Improve Codebase Architecture

Goal: identify high-leverage architecture changes and sequence them safely.

Use for:

• tangled dependencies, leaky boundaries, or scattered logic
• modules that are hard to change or test in isolation
• recurring bugs that trace back to structure, not code

Workflow:

1. Map the current modules, boundaries, and data flow.
2. Locate the pain: what change is consistently hard or risky.
3. Name the architectural cause, not the surface symptom.
4. Propose a target structure with clearer boundaries.
5. Sequence the move as small, independently shippable steps.
6. Define how each step is verified before the next.

Look for:

• deep modules with simple interfaces vs. shallow leaky ones
• cyclic dependencies and god objects
• business logic mixed with I/O or framework code
• duplicated knowledge across layers

Rules:

• justify each change by a concrete pain it removes
• prefer incremental migration over big-bang rewrite
• keep public behavior stable unless change is the goal
• do not add abstraction without a second real use