"Can't the controller just call the database?"
The public library's loans web app lets members borrow, renew and return books. A pull request adds a page that lists a member's current loans, and a reviewer leaves this comment: "To run one SELECT, the controller calls ListMyLoans, which calls Loans.forMember, which calls LoanTable.selectByMember. The two in the middle add nothing. Why can't the controller call LoanTable itself?"
It is a fair question, and the answer is not about those two methods. It is about the rule the whole codebase was built around, a rule the reviewer is asking to break.
Four layers, one direction
The app follows a layered architecture: its code is grouped into horizontal layers, each with one kind of technical job, stacked so that every dependency points one way, down. A layer may call the layers beneath it and must never call the ones above. This is the most common starting structure, and the library's version has four layers:
- Presentation turns HTTP requests into calls and results into pages:
LoansController. - Application holds one class per thing a member does, such as
RenewLoanorListMyLoans, and decides where a transaction starts and ends. - Domain holds the library's rules: a loan can be renewed at most twice, and not while another member has a hold waiting on the book.
Loan,LoanPolicyandLoanslive here. - Infrastructure talks to the outside world: the SQL for the
loansandholdstables, and the e-mail that confirms a renewal.
Renewing a loan, layer by layer. Every call goes down; no layer calls the one above it.
What the one-way rule buys is containment. When the library changes only how its pages look, the change stays in Presentation, because nothing below imports a page. The renewal rule can be read without reading any controller, and compiled and tested with no web framework present.
A lower layer that reaches back up to call a higher one collapses the one-way dependency the structure exists to enforce. If Loan.renew() formats "Renewed until 28 November" with Presentation's date helper, a change to how dates are displayed can break the build of the renewal rule; the domain should return the date and let Presentation format it.
Strict or relaxed: what the reviewer is really asking
Layered designs come in two flavours. In strict layering, a layer may use only the layer directly beneath it, so every call passes through every layer on the way down. In relaxed layering, a layer may use any layer beneath it. The same idea is often described per layer: a closed layer must not be skipped, an open one may be.
The library's code is strict, and the loans page shows the downside. ListMyLoans and Loans.forMember are pass-through methods: they forward a call without adding anything. One or two are harmless. When most requests cross a layer untouched, that layer is costing code in every feature and, unless it guards a boundary the team still needs, buying nothing; teams in that spot often start skipping it anyway, without saying so. A rule nobody writes down is worse than either flavour, because each developer then decides on their own which layers may be skipped.
So the team answers the reviewer with a decision, written down where the next pull request will find it. Domain becomes open for reads: ListMyLoans may read from Infrastructure directly, because a list of loans has no rule to apply. Application stays closed: the controller still calls ListMyLoans, because the next requirement, hiding the loans of a suspended account, needs a home that is not a controller. The two pass-throughs shrink to one, and the reason is on record.
The arrow at the bottom of the stack
Six months later the stack is followed to the letter, and the most important code in the app is in the most awkward place. LoanPolicy decides whether a loan may be renewed, and to know about waiting holds it imports HoldTable from Infrastructure. The arrow points down. No rule is broken. Three things still go wrong:
- The test for "a third renewal is refused" needs a database, or a stand-in for a SQL class, because the rule cannot be loaded without the code it imports.
- The library joins a regional consortium and holds move to the consortium's shared catalogue, reached over HTTP. The renewal rule has not changed, yet the domain files change, because they named the SQL class.
- The domain starts to take the database's shape.
Loancomes to mirror theloansrow column for column, and rules get written around what is easy to query.
The rules, the code the library cares most about and changes least, depend on the code that changes most. The cure is to turn that one arrow around, which is the next article worth reading: Hexagonal (Ports & Adapters) inverts the bottom dependency so the domain depends on nothing external, applying the dependency inversion principle from SOLID design principles.
One more limit: layers split code by technical job, so a feature such as renewals is spread across every layer. Splitting one deployable into modules by business capability first, with layers inside a module if needed, is what Modular Monolith does.
Draw the library on Layered Dependencies
The Layered Dependencies Challenge asks for a layered stack with that bottom arrow already inverted, the way Hexagonal explains it. Draw the library's domain, application and infrastructure packages with a type in each, named with its package, such as application::RenewLoan and domain::LoanPolicy, and put the contract for reading holds on the domain's side. Packages, notes and dependency direction explains how packages and notes are drawn on a Challenge Grid. When the diagram is done, answer the reviewer's kind of question on it: if holds move to the consortium's catalogue, which packages change? The answer the inversion was for: domain and application stay as they are, as long as the consortium can answer the same holds contract, and only the adapter and the start-up code that picks it change.