akathecoder Codebase Design
Design deep modules: substantial behavior behind a small interface, placed at a clean seam and tested through that interface. The aim is leverage for callers, locality for maintainers, and testability for everyone.
Vocabulary
Use these terms exactly. Do not substitute component, service, API, boundary, or unit when one of these terms applies.
- Module: anything with an interface and implementation, regardless of scale.
- Interface: everything a caller must know to use a module correctly: types, invariants, ordering, errors, configuration, and performance characteristics.
- Implementation: the code inside a module. Use adapter when discussing a concrete thing that fills a seam.
- Depth: leverage at the interface. A deep module hides substantial behavior behind a small interface; a shallow module exposes an interface nearly as complex as its implementation.
- Seam: where behavior can change without editing that location; the location of a module interface.
- Adapter: a concrete implementation of an interface at a seam.
- Leverage: capability callers gain per unit of interface they learn.
- Locality: the concentration of change, bugs, knowledge, and verification in one place rather than across callers.
Principles
- Depth is a property of the interface, not implementation size.
- Apply the deletion test: if deleting a module makes complexity reappear across its callers, it earns its keep.
- The interface is the test surface. Tests and callers cross the same seam.
- One adapter is a hypothetical seam; two adapters make it real.
When deepening a cluster with dependencies, read DEEPENING.md for dependency
categories, seam discipline, and replace-not-layer testing. When the user wants to
compare alternative interfaces, read DESIGN-IT-TWICE.md for the parallel design
process.