improve-codebase-architecture

To refactor shallow modules into deeper, testable code, analyze your codebase for architectural friction and seam placement issues, then consolidate tightly coupled logic behind clear module interfaces using adapters for testing and production environments.

The ports-and-adapters pattern for testing strategy isolates core logic behind seams, allowing you to replace shallow tests with interface-level tests that leverage adapters to inject test data and verify production behavior.

You identify architectural friction in a codebase by scanning for modules that are hard to understand, hard to test through their interface, or tightly coupled, then mapping these shallow modules to prioritized deepening candidates.

Yes, this refactoring approach works with existing ADRs by exploring the project and Architecture Decision Records first to ensure proposed deepening candidates and seam placements align with your established design decisions.

The best way to define seams and adapters for testing is through a grilling loop that evaluates prioritized deepening candidates, explicitly defining the deepened module boundary and its appropriate adapters for both test and production environments.

You should not use deepening candidates for refactoring when your modules are already deep, easily testable through their interfaces, or when your current architecture exhibits no significant locality, leverage, or coupling issues.