improve-codebase-architecture

To find shallow modules during an architecture review, scan your repository for architectural friction where understanding a concept requires bouncing between many small modules, then consolidate behavior into deeper modules with better locality and leverage.

The best way to refactor code for testability and AI-navigability is to identify shallow modules and architectural seams, then propose deepening refactors that tighten those seams and consolidate scattered behavior into cohesive, deep modules.

Use ADRs and a project glossary to guide architecture refactoring by reading existing domain vocabulary and architectural decisions first, ensuring proposed deepening opportunities respect established language and preserve locality within the codebase.

Yes, you can generate an architecture report by scanning the repository for architectural friction, which produces a structured HTML output containing refactoring candidates, diagrams, and a top recommendation for module deepening.

Deep modules consolidate behavior to provide high leverage and strong locality, reducing the architectural friction caused when understanding a feature requires bouncing between many small, shallow modules across the codebase.

Yes, but without existing ADRs or a project glossary, the architecture review lacks domain-aware guidance, meaning proposed deepening opportunities may not fully respect prior architectural decisions or established domain vocabulary.