codebase-design

Design **deep modules**: a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface. Use this language and these principles wherever code is being designed or restructured. The aim is leverage for callers, locality for maintainers, and testability for everyone. ## Glossary Use these terms exactly — don't substitute "component," "service," "API," or "boundary." Consistent language is the whole point. - **Module** — anything with an interface and an implementation. Scale-agnostic: a function, class, package, or tier-spanning slice. *Avoid*: unit, component, service. - **Interface** — everything a caller must know to use the module correctly: the type signature, plus invariants, ordering constraints, error modes, required configuration, and performance characteristics. *Avoid*: API, signature (too narrow — type-level only). - **Implementation** — what's inside a module, its body of code. Distinct from **Adapter**: a thing can be a small adapter with a large implementation (a Postgres repo) or a large adapter with a small implementation (an in-memory fake). Say "adapter" when the seam is the topic; "implementation" otherwise. - **Depth** — leverage at the interface: how much behaviour a caller (or test) can exercise per unit of interface they must learn. **Deep** = large behaviour behind a small interface. **Shallow** = interface nearly as complex as the implementation. - **Seam** *(Michael Feathers)* — a place where yo...