One import at the top of PlaceOrder
The first line of PlaceOrder.js, the use case that turns a shopper's basket into an order, reads import { SqlOrderRepository } from '../infrastructure/sql-order-repository.js'. Every test of PlaceOrder loads the SQL code with it, so the team introduces OrderRepository, an interface the use case can call instead, with SqlOrderRepository as its implementation. That leaves a question which sounds like housekeeping: which folder does the interface go in? The answer decides which parts of the code may import which, and a class diagram of loose boxes cannot even pose it, because on it any box may point at any other.
So group the types first. A Package is a named group of types, and a useful one holds types that change together. Here there are four: web holds the controller that turns an HTTP request into a call, application holds the use cases such as PlaceOrder, domain holds Order, OrderLine and Money, and infrastructure holds the code that talks to the database. Once every type has a package, an arrow between two packages states a dependency a reader can check against the imports: code in this package uses code in that one. A layered design adds the rule that no arrow runs back.
A package groups code; it says nothing about what runs where. The deployable applications and data stores of a system, and who uses them, are a different view, and a container in that view is not a package: The C4 model: context, containers, components, code covers it.
Four packages, and which way the arrows point
The domain package depends on nothing. That is the claim the diagram is making.
Each dashed line with an open arrowhead is a dependency: the package at the tail uses something in the package at the head, and may have to change when it changes. It is the same arrow that links two classes when one merely uses the other, the plain dependency of Association, aggregation, composition. Follow the arrows from any package and every path ends at domain, which points at nothing. So the order rules can be compiled and tested with no web framework and no database present, and a change to the SQL code does not require a change in them.
Now the folder question has an answer. PlaceOrder has to save orders, but importing the SQL implementation, as it does now, makes application depend on infrastructure: the arrow points outward and couples the use cases to the SQL code. A contract in application lets them depend on the abstraction instead, so the interface goes on the side that uses it: OrderRepository lives in application, in the use case's terms (save(order), get(orderId)), and SqlOrderRepository in infrastructure implements it. At run time, once start-up code has handed PlaceOrder a SqlOrderRepository, the call goes from PlaceOrder into the SQL code; in the source, the dependency points the other way, from the SQL code to the contract. That reversal is dependency inversion, one of the principles SOLID design principles explains.
Many designs put the contract one step further in, in domain beside the Order it stores, and Repository does. Either placement keeps it on the inner side of the boundary, so the arrow from infrastructure still points inward. The placement that breaks the design is the tempting one, in infrastructure next to its implementation, because then application must import infrastructure to reach it.
A note for the reason
The diagram shows the arrow from infrastructure to application but not why it points that way, so the next developer who finds it odd may turn it around; the reason goes in a Note, the box with the folded corner, the one stencil that attaches to anything — a class, a package, a state, even a lifeline. Use it for what the notation cannot express: an invariant, the reason for a surprising arrow, as the note in the example records the inversion, or a rule such as "nothing in domain imports a framework", which a reader would otherwise have to infer from arrows that are missing. If what you want to say can be an arrow with a label, draw the arrow instead.
Six weeks later, an arrow points back
A developer wants an order to save itself and adds Order.place(), which calls OrderRepository.save(this). It compiles. It also draws a new arrow, from domain to application, where the interface lives, and application already depends on domain.
With both arrows drawn, domain and application form a cycle: each now depends on something in the other, against the dependency direction the layers were meant to keep.
OrderRepository contract from application. The diagram shows it as soon as both arrows are on the page; in the code it is one import among hundreds.There are two ways out. If the call does not belong where it was put, move it: the use case saves the order, as PlaceOrder already did, and the arrow from domain disappears. If the inner package really does need something from the outer one, invert again, putting a contract in the inner package and letting the outer one implement it. Which way is right is a design decision; the diagram makes the cycle visible so that somebody takes it.
A cycle can also run through three packages or more, domain to pricing to catalog and back, where no single pair looks wrong and only following the arrows all the way round shows the loop. Package Boundaries asks for a package graph free of cycles of any length for that reason.
Mistakes that undo the direction
- Packaging by technical role (
controllers,services,models) with no rule about which may depend on which — layers only earn their keep when every arrow between them points one way, as in the example. - Putting a class inside two packages. A type has one home; if two packages need it, one depends on the package that owns it, as
infrastructuredoes onapplicationforOrderRepository, or, when neither should own it, it moves to a third that both depend on.
Prove the layering on Layered Dependencies
Layered Dependencies asks for the domain, application and infrastructure packages, with every dependency pointing toward the domain. Put the repository contract on the inner side, as application::OrderRepository, and its implementation in infrastructure, connected to it with a «realize» label. Attach a Note that names the inversion. Then follow the arrows out of every package: if any path leaves domain, or any arrow runs from application to infrastructure, the layering is aspirational.
application::OrderRepository, application::PlaceOrder — let each connection run from the package that depends to the one it depends on, and label an implementation of a contract «realize».