codebase-design

A deep module puts a large amount of behavior behind a small interface. Reduce the number of methods, simplify parameters, and hide complexity inside the implementation so callers get more capability per unit of interface they must learn.

A seam is the location where a module's interface lives and where behavior can be altered without editing that place. The interface is everything a caller must know to use the module, including invariants, ordering, and error modes.

Introduce a port only when at least two adapters are justified, typically a production adapter and a test adapter. A single-adapter seam is just indirection; one adapter means a hypothetical seam, two adapters mean a real one.

Write tests at the deepened module's interface and delete old unit tests on the shallow modules it absorbed. Tests should assert observable outcomes through the interface and survive internal refactors, since the interface is the test surface.

Treat true external services like Stripe or Twilio as injected ports, with tests providing a mock adapter. For remote services you own, define a port with an HTTP adapter for production and an in-memory adapter for tests.

Avoid deepening when it only creates pass-through indirection. Apply the deletion test: if deleting the module makes complexity vanish rather than reappear across callers, it was not earning its keep.