Project Structure

"Make the change easy, then make the easy change." — Kent Beck

Part V ended by drawing a boundary: business logic must not see req or res. This Part is about everything on the far side of it, and it starts with where the files go.

That sounds like the least consequential decision in a codebase and is one of the more consequential ones, for a reason Beck's line names. Structure exists to make changes local. A well-organised project is not one that looks tidy in a file tree; it is one where a typical change — add a field, add an endpoint, change a rule — touches a small number of adjacent files. A badly organised one is where the same change touches six directories, none of which are near each other, and every pull request conflicts with every other.

There are two dominant layouts, they optimise for different things, and the choice matters more as a team grows. Beyond that there are three properties worth enforcing rather than hoping for: dependencies pointing one way, no import cycles, and a single place where everything is wired together.

None of this is Node-specific, and all of it is more urgent in Node than in most ecosystems — because the module system will happily let a cycle resolve to a half-initialised object rather than telling you, which Part I ch4 measured.

Two layouts, and what each optimises

The measurement first, because the argument is usually made on taste.

Three things that measurement settles, and one it does not.

Both layouts hold the same number of files. The difference is adjacency, not size. Nobody is eliminating a concern by moving it.

Feature folders localise change, which is the operation teams perform constantly. A pull request becomes one directory, reviewable as a unit, and two people working on different features do not touch the same directories.

Layer-by-type localises kind. It is genuinely better if your common task is "audit every repository" or "apply a change to all controllers" — which happens, but rarely, and usually as a one-off that a search handles.

What the measurement does not settle is small projects, where either works and the feature layout's ceremony is not yet earned. A service with three endpoints does not need directories at all. This is the Metz warning from Part V ch3 applied to layout: the structure should arrive when the pain does.

The dependency rule

Layout says where files are. The dependency rule says which of them may know about which, and it is the property that keeps a codebase from becoming a single tangled unit.

The rule is one line of code and buys three properties.

The domain is testable in isolation. It imports nothing that needs a connection, a port or a fixture, so its tests are functions calling functions.

Adapters are replaceable. Swapping Postgres for something else touches the adapter and nothing else, because nothing inward knows the adapter exists. This is the payoff people are usually promised and rarely get, and it is a direct consequence of the arrow direction.

Dependencies are inverted where they need to be. application/ports is the trick: the application declares the interface it needs — "something that can save an order" — and the adapter implements it. The arrow from adapters/db to application/ports points inward, so the application depends on its own abstraction rather than on a driver.

This is the file-layout expression of the factory pattern from Part V. There, dependencies were injected as arguments; here, the type of thing being injected is declared by the layer that needs it rather than by the layer that provides it.

Cycles, and the barrel that creates them

Import cycles are the failure mode Node handles worst, and one common convention manufactures them.

Three consequences worth being precise about.

A cycle does not throw. Part I measured it: CommonJS returns a partially-populated exports object, so a function is undefined at call time rather than at import time. ES modules are stricter — a temporal dead zone error — but only for values, and function declarations are hoisted, so many cycles work until one does not.

Barrel files convert a tree into a hub. Every module importing from index gains an edge to a node that has edges to everything, so two modules that would never have referenced each other become mutually reachable. They are convenient for a package's public surface and a liability inside it.

The failure is order-dependent. Which module loads first decides which one sees a partial object, and that order can change when an unrelated file is renamed — which is why these bugs appear to come from nowhere.

The practical rules: import directly rather than through a barrel inside a project, keep barrels for the boundary of a published package, and run a cycle check in CI. The check above is thirty lines and madge --circular is a one-line alternative.

The composition root

Dependency injection needs one place where the injecting happens, and its properties are worth stating.

Four properties, and the fourth is the one people miss.

Construction happens once, at startup. Nothing constructs its own dependencies at call time, so there is no hidden state and no surprise about when a connection is opened.

The wiring is readable. One file answers "what does this service consist of", in dependency order, which is the same question §4 of Part V ch3 asked of routes.

Tests replace exactly what they need. Overriding the database and the clock leaves the mailer real. That is finer-grained than module mocking and requires no framework.

The composition root is the only place allowed to know everything. It sits outside the dependency rule — it imports from every layer by design, because somebody has to. Recognising it as a deliberate exception is what stops people concluding the rule is unworkable.

Enforcing it

A convention that is not checked becomes a convention that is violated, and all three properties above are checkable in a few lines.

Three notes on making a check like this survive contact with a team.

Allow the exception explicitly. The composition root imports outward by design. A rule with no escape hatch gets disabled entirely the first time it is inconvenient, so name the exception rather than weakening the rule.

Report every problem at once. The same argument as configuration validation in Part V ch5 — one problem per run is one failed build per problem.

Introduce it with a baseline. An existing codebase will have violations. Record the current set, fail on new ones, and shrink the baseline over time. A check that fails on day one gets deleted on day one.

In practice, eslint-plugin-import and dependency-cruiser do all of this with configuration rather than code, and madge --circular covers cycles alone. Writing it yourself is a good way to understand what they check; using them is the right call afterwards.

Common Mistakes

1. Layer-by-type in a project that changes by feature. A one-field change touches six directories, measured.

2. Applying layered structure to a small service. Four endpoints do not need ports and adapters; the structure should arrive with the pain.

3. A domain module importing a database client. It is then untestable without a connection and unreusable from anything else.

4. No inward-facing port. The application depending on a driver rather than on its own interface makes the driver unswappable.

5. Barrel files inside a project. They turn a tree into a hub and put any two modules one step from a cycle.

6. Assuming a cycle will error. CommonJS gives you a half-filled exports object silently; the failure is order-dependent.

7. Constructing dependencies at import time. Importing a module for any reason then opens a connection.

8. Scattering construction. With no composition root there is no single answer to what the service consists of.

9. A rule with no exception for the composition root. It gets disabled entirely the first time it is inconvenient.

10. Introducing a structural check without a baseline. It fails on day one on legacy violations and is deleted on day one.

Interview Corner

Hands-on

Summary

• Structure exists to make changes local, and the measurement is how many directories a typical change touches — six for layer-by-type, one for feature folders.
• Layer-by-type localises kind; feature folders localise change. Work is almost always changing a feature.
• Small services need neither. The structure should arrive with the pain, not before it.
• Dependencies point inward: adapters know the application, the application knows the domain, nothing imports outward.
• The application declares its own ports, so it depends on its abstraction rather than on a driver — which is what makes adapters replaceable.
• Import cycles do not throw. CommonJS hands over a half-filled exports object, and which module gets it depends on load order.
• Barrel files turn a tree into a hub and put any two modules that use them one step from a cycle.
• One composition root, constructing everything at startup, is the only place allowed to import from every layer.
• Tests override exactly what they need at the composition root — no mocking framework, and the rest stays real.
• Enforce the rules in CI with a baseline. A check that fails on day one is deleted on day one.

Structure decides where code lives. The next chapter is about the values that flow through it: configuration and secrets in earnest — how a service learns its database password without that password being in the repository, in a log line, in an error message, or in a container image layer. It is the least glamorous chapter in this Part and the one most likely to matter on a bad day.