Decomposition

Modularity is not about reuse. It is about isolating change — so that being wrong about one thing costs one thing.

Every boundary is a bet that what is on either side will change at different rates, for different reasons. A good cut means a mistake stays local and can be deleted. A bad cut means a mistake is load-bearing, spread across nine call sites, and the fix is a migration.

Ask of any boundary: when this turns out to be wrong, what does it cost to remove?

Cut by rate of change

The instinct is to group things that look alike. Look-alike grouping produces a utils module containing business logic, and a models directory whose contents change for six unrelated reasons.

Group what changes together, for the same reason. Volatile apart from stable. Policy apart from mechanism — the rule about what should happen apart from the machinery of making it happen. Hard problems isolated so the hardness has one address.

The clearest signal a boundary is wrong: a single feature request keeps requiring edits on both sides of it, every time.

Pull, transform, push

The useful unit is a process: acquire data, turn it into other data, emit it. The three phases have opposite natures and should not be mixed.