Module & Package Structure

Grouping by feature or by layer, what each does to change locality, and why cycles are a reasoning problem before they are a build problem.

Package Design

A package is a claim about what changes together. Grouping by domain, feature or capability makes that claim; grouping only by technical type makes no claim at all.

Q · What should decide which folder a file goes in?
Package by Layer

controllers / services / repositories. It is genuinely good at cross-cutting technical change and at being guessable, and it scatters every feature across every folder.

Q · What does a layer-first layout actually buy, and what does it charge?
Package by Feature

orders / payments / users, each with its own layers inside. Requirement-shaped change becomes local, and shared concepts lose their obvious home.

Q · If I group by capability instead of by technical role, what actually gets cheaper — and what gets worse?
Vertical Slices

One folder per use case, containing everything that use case needs. Change locality is close to maximal, and shared concepts have nowhere obvious to live.

Q · If grouping by capability is good, is grouping by individual use case better?
Circular Dependencies

A depends on B depends on C depends on A. What breaks is reasoning first, then initialisation order, then testability, and only last the build.

Q · My build tolerates cycles, so why does a dependency cycle matter?
Breaking Cycles
▶ lab

Move the shared concept, invert a dependency, introduce an interface — or merge two modules that were never really separate. The last one is the most under-used fix.

Q · I have a dependency cycle. Which of the available fixes is the right one here?
Stable Dependencies

Depend toward the things that change less often than you do. It is a statement about rates of change, not about which folder sits lower in a diagram.

Q · Which way should this dependency point, and what makes the other direction wrong?
Module Granularity
▶ lab

How big should a module be? Big enough that a likely change fits inside it, small enough that one person can hold it. "As small as possible" is not an answer to either question.

Q · How do I know whether this module is the right size?