codebase-design: an app as a hierarchy of deep modules

From a voice note (2026-10-31): > Every application can be made of a hierarchy of deep modules, each of which contains other deep modules inside it. If you enforce those boundaries, you end up with an app that's easy to navigate, made of a handful of very large deep modules, and healthy overall. ## The idea `codebase-design` treats a module as one level: an interface over an implementation. It doesn't yet say that an implementation can itself be made of deep modules. The claim here is that this nesting is how a whole application should be shaped: ```text app ├── module A # deep: small interface, large implementation │ ├── module A1 # deep in its own right, private to A │ └── module A2 └── module B └── module B1 ``` - Each module is imported only through its interface. Nothing reaches into another module's internals. - Those boundaries are enforced by tooling, not left to convention. - An agent or a human finds their way top-down: they read the interfaces at one level and only open a module when they need to. ## Prior art - #95 suggested "fractal tree" file structures, where each node is a deep module whose subfolder holds its private sub-modules, with no barrel files. - Matt's personal-wiki already enforces one level of this: packages in `src/packages/` are imported only through their root files, and `pnpm lint:boundaries` checks it. ## Open questions - Should this go into `codebase-design` as vocabulary (e.g. a nested-module term next to **Module** / **Implementation**), or into `DEEPENING.md` as a design move? - Should the skill recommend a way to enforce boundaries (a lint rule), or stay tool-agnostic? 🤖 Generated with [Claude Code](https://claude.com/claude-code)