Skip to main content
Home
HexagonalGuru

The Modular Monolith: The Sensible Architecture Nobody Sells

HexagonalGuru's avatar

HexagonalGuru

The Modular Monolith: The Sensible Architecture Nobody Sells

In the microservices article we dropped the advice: "modular monolith first, distribution when it hurts". It's the line that's generated the most questions, so it's time to develop it. Because the modular monolith isn't a monolith with good intentions — it's an architecture with concrete rules, and the difference between having one and not having one shows the day you need to change something big.

Let's get into the detail: what it is, how it's structured, how you stop it degrading into the usual big ball of mud, and how it becomes your insurance for the future, whether you ever distribute or not.

What It Is (and What It Isn't)

A modular monolith is a system deployed as a single unit — one process, one database, one deployment — but whose interior is divided into modules with explicit boundaries. Each module owns a domain: its business rules, its data and its internal public API. Other modules can only talk to it through that API.

What it isn't:

  • A monolith with tidy folders. Having src/Invoicing/ and src/Catalog/ isn't modularity if anyone can import anything from anyone. The boundary only exists when it's enforced.
  • A cheap microservice. There's no network, no independent deployments, no per-part scaling. It's a monolith: its grace is that its internal boundaries are as clean as the ones a distributed system would demand.
  • An inferior stage to grow out of. Many systems should stay here forever. Modularity is an end in itself; distribution is optional and sometimes never comes.

The Three Rules That Define It

Tangled monolith versus modular monolith: on the left cross-calls between all modules, on the right modules that only talk to each other through their internal public APIs

The whole modular monolith comes down to three rules, and all three can be verified:

  1. Each module has a public API, and it's the only door. If the catalogue module needs to know whether an invoice exists, it calls InvoicingApi, not the invoice repository. Anything not in the public API is private: entities, repositories, internals.
  2. Data has an owner. Every table belongs to one module. Nobody else touches it: if you need someone else's data, you ask for it through the API or receive it through internal events. The JOIN that crosses modules is the beginning of the big ball of mud.
  3. Dependencies point in one direction. Catalogue can depend on nothing; invoicing can depend on catalogue; never the other way round. An acyclic dependency graph between modules is what lets you extract them tomorrow without spilling anything.

Notice what's important: none of the rules mentions frameworks or technology. They're structural rules, and they work the same in Symfony, in Spring or in a Node monolith.

How to Enforce It (Because Good Intentions Aren't Enough)

This is where most attempts die: the boundaries get drawn on a wiki and six months later everyone has crossed them "because it was just a silly method". The solution is making boundary violations a build error, not a code review discussion:

  • Architecture tests. Tools like ArchUnit (JVM), Deptrac (PHP) or dependency-cruiser (JS) let you assert in a test: "nobody outside Invoicing can import Invoicing\Repository", "Catalog cannot depend on Invoicing". CI fails when someone crosses the line. Without this, boundaries are fiction.
  • The explicit public API. An Api/ directory per module with the public interfaces, everything else marked internal. If your language doesn't force it, the architecture test does.
  • Internal events for what doesn't fit. When invoicing needs to react to "order confirmed" without depending on orders, the internal event breaks the dependency. It's the first step of the ladder we covered in CQRS and event-driven — and tomorrow, if needed, that event goes out to a broker without touching the domain.

The Insurance for the Future

The return on the modular monolith arrives through three channels, and only one of them is distribution:

  1. Change stops being scary. With clear boundaries, you know what each change touches and what it can't break. It's the structural answer to "any change breaks something far away".
  2. The team can split up. As the team grows, each person or pair can own a module without stepping on the others. The autonomy microservices promise, without the network.
  3. Extraction is cheap if the day comes. If tomorrow the image processor needs to scale separately, extraction means changing the transport: the boundary, the API and the data were already separated. What was a function call becomes HTTP — and that's when you start paying the distributed toll, knowingly.

And a silent advantage: hexagonal architecture and the modular monolith reinforce each other. Ports and adapters keep each module's domain free of infrastructure; the boundaries between modules keep domains free of each other. It's the combination that makes a system age slowly.

Common Mistakes

  1. Modularising by technical layers. "Controllers module, services module, repositories module" isn't modularity: it's the big ball of mud with shelving. Modules are cut by domain — invoicing, catalogue, orders — never by artefact type.
  2. The "Common" module. A shared drawer where everyone drops utilities ends up being the module everyone depends on and everyone fears touching. What's shared must be small, stable and domain-neutral (dates, money), not a dumping ground.
  3. Boundaries without enforcement. Already said, but it's the most common mistake: documented boundaries nobody verifies. If the build doesn't fail, the rule doesn't exist.
  4. The database as the exception. "Just one JOIN, it's faster". Every JOIN between modules is a weld between them: the day you want to split, you'll be cutting with an angle grinder. If performance demands reading someone else's data, a read-only projection beats touching their tables.
  5. Modularising everything at once. No big-bang needed: start with the module that hurts most, draw its boundary, protect it with architecture tests, move on to the next. The boy scout rule applied to structure.

In Short

The modular monolith is a single deployment with serious boundaries: each module has its public API, its data and its dependency direction, and architecture tests guarantee it in CI. It's not a poor microservice nor a mandatory transition stage: it's the structure that makes a monolith age well and that, if distribution is ever needed, turns extraction into changing the transport rather than rewriting the system. Boundaries today, network only if it hurts tomorrow.

If your monolith is turning into a big ball of mud and you want a plan to modularise it without stopping the business, we can draw it with you: which modules, in which order and with which protection tests. Let's talk →

Keep reading: What is hexagonal architecture: a practical guide with a real example.

  • #hexagonal-architecture
  • #modular-monolith

Related articles

Shall we start?

Ready to build something that grows with your business?

Tell us your goals and together we will map the design, development and technology route that takes you from vision to measurable results.