codebase-design

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

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

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

Write tests at the deepened module's interface, since the interface is the test surface. Delete old unit tests on the shallow modules, and assert on observable outcomes so tests survive internal refactors.

Treat true external services like Stripe or Twilio as injected ports. The deepened module owns the logic, production uses the real client as an adapter, and tests provide a mock adapter.

Avoid deepening when it only adds indirection, such as introducing a seam with a single adapter. Use the deletion test: if deleting the module makes complexity vanish rather than reappear across callers, it was a pass-through.