A modular monolith is better than microservices when your teams can still release together, your module boundaries are still being learned, and the cost of a network between modules would be higher than the cost of one shared deploy. It means one deployable application split into modules with enforced rules about who may depend on whom. Boundaries come first and the deployment unit comes second, because a service is only a module boundary that also costs you a network call.
I am Ash, a Staff engineer in Toronto. At a company I worked at, I led a team of 7 that restructured a tangled MVC codebase in place with domain-driven design, without splitting it into services. Today I lead a move from a monolith to services, sponsored by the CTO, that starts with one team, and I got that plan agreed across product, design, support and engineering leadership. So I have no side in this argument. This article is for staff engineers and engineering leaders who have to decide.
What a modular monolith is
A modular monolith is one codebase that you build and deploy as one unit, divided into modules around business capabilities. Each module has a public surface that other modules may call and an inside that they may not touch. Usually the modules share one database, but each owns its tables and is the only writer to them.
A monolith with folders named after features is still a plain monolith, because nothing stops one folder from reaching into another. Martin Fowler says that there is “no reason why you can’t make a single monolith with well defined module boundaries” and also that “in practice it seems too easy for module boundaries to be breached and monoliths to get tangled”. The rest of this article is about the second half.
The usual source of boundaries is domain-driven design. A bounded context is a central pattern in that approach, and Fowler explains it as a way to divide a large model, because total unification of the domain model of a large system “will not be feasible or cost-effective”. A module is how you give a context a home in code.
When one deployable is the better answer
Four situations favour the modular monolith.
The first is that you do not yet know where the boundaries are. Sam Newman writes that getting service boundaries wrong can be expensive and advises splitting only around boundaries that are clear at the start. Moving a boundary inside one codebase is a refactor. Moving a boundary between two services is usually a migration that involves two deploys and a data move. Early on, you want the cheap kind of mistake.
The second is that your teams can still ship together. Fowler and James Lewis describe microservices as services that are independently deployable, and that independence is what you pay for. If nobody is waiting on anybody else’s release, you are buying something you do not use. Fowler says in Monolith First that you shouldn’t start a new project with microservices, and in the Microservice Premium he says to avoid them unless the system is too complex to manage as a monolith.
The third is that your operations need strong consistency. Fowler’s Microservice Trade-Offs article says that maintaining strong consistency is extremely difficult for a distributed system, which means everyone has to manage eventual consistency. When one business action must change several things or none, a database transaction across modules is a well understood tool. A service boundary replaces it with a workflow you have to design and test.
The fourth is limited operations capacity. The same article says you need a mature operations team to manage lots of services that are redeployed regularly. In my experience a service is cheap to start and costly to keep.
When separate services are the better answer
The case for services is about people and release trains, not code style. Fowler’s trade-offs article says that microservices reinforce modular structure, which is particularly important for larger teams. It also says that firm module boundaries are possible inside a monolith, but it requires discipline, and that as a team grows it gets progressively harder to keep disciplined.
That gives you a test I find more useful than a headcount. Services start to win when one of these is true.
- Teams wait on each other’s releases, and the waiting is worse than the cost of running a service.
- One module needs its own scaling profile, runtime or security boundary.
- The module’s owners have a platform that makes a new service cheap, with a template, a pipeline and alerts in place.
Team size does not decide it. Fowler writes about systems that range from a team of 60 with 20 services to a team of 4 with 200 services. Pain you can name does decide it.
I now lead a move in this direction, so I take the case seriously. In my view the sound way into it is the one this article recommends, which is to find the boundaries first and extract along them.
Enforce the boundaries or you do not have modules
The Shopify engineering team wrote about keeping boundaries real in their post on the state of their Rails monolith. Their core monolith has over 2.8 million lines of Ruby code, and when they looked at the dependencies between its components they found a dense graph, and in their words, “We also had lots of circular dependencies.” They built a tool called Packwerk to hold the line, and the post says it was used on about a third of their components at the time. Even so, they describe the work as unfinished, which is worth knowing before you plan yours.
Packwerk is “a Ruby gem used to enforce boundaries and modularize Rails applications.” Its usage guide shows the mechanics worth copying in any language. Each package declares the packages it depends on. A reference to anything undeclared is a violation. Existing violations go into a to-do list that “should not be added to, but worked off over time”, and the guide says the dependency graph has to be acyclic.
Four rules do most of the work in any stack.
- Every module has a small public surface, and everything else in the module is private by default.
- The allowed dependencies between modules are written down, and a check in CI fails the build when a change breaks them.
- Each module owns its tables and is the only writer to them. Other modules ask through the public surface.
- There are no cycles. If two modules need each other, one of them is the wrong shape, or a third module is missing.
The Rails engines guide describes engines as miniature applications that provide functionality to a host application, and says they can be isolated from it. An engine gives a module a namespace and a place to live. It does not say which module may call which, so I would pair it with a dependency checker.
A database rule can be a boundary too. For regulated fintech clients I made tenant isolation a database guarantee with PostgreSQL row-level security, so one customer’s query cannot return another customer’s rows. I wrote up the Rails version in how to isolate tenants with row-level security. It is the same idea, which is to let the machine hold a boundary that people forget.
How to untangle a messy monolith without splitting it
If you already have a tangled codebase, you do not need services to fix it. In the team of 7 I led, I wrote the architecture documents and ran the design reviews. The result was a codebase that is easy to read and maintain, and we did not split it into services. What follows is the method as I would teach it, not a list of the steps we took.
- Name the contexts in the language the business uses, and write each one down in a short architecture document with its public surface and its owner.
- Move one area at a time. Fowler’s Bounded Context page says that you need a different model when the language changes, and that words such as “Customer” and “Product” mean different things in different parts of a business.
- Review each boundary in a design review before the code moves, which is cheaper than arguing about it after.
- Turn on a dependency check for the first module as soon as it exists, and let existing violations sit in a to-do list that only shrinks.
- Fix cycles by moving a responsibility or by adding a module, and never by letting both sides call each other.
The order matters. A rewrite as services does the hardest part, finding the boundaries, together with the most expensive part, running distributed systems. Doing the boundaries first lets you stop at any point with a better codebase.
What a modular monolith costs
You pay in discipline. The boundaries hold only if the checks are in CI and someone owns them. If the checks are skipped under deadline pressure, the to-do list grows and the codebase returns to a tangle with nicer folder names.
You share a release train. One deploy carries every team’s change, so a bad change in one module can block or roll back the others. That is the pain that can justify a service.
You share the blast radius. A runaway query or a memory leak in one module affects every module in the same process and database. Timeouts and query rules per module limit it, and nothing removes it.
I would reject two things at the start. One is splitting into services before the boundaries are stable. The other is a “modular” structure with no enforcement, which has the costs of a monolith and none of the promise.
Should you build one for a growing team?
Yes, in most cases, with three conditions. Your teams can release together and you are still learning the domain. You enforce the boundaries from the first module and not after the first mess. And you name the signal that would make you extract a service, so fashion does not make the decision later. A growing team alone is not that signal. It is a reason to tighten module ownership and CI checks.
How do you know it is working? Four things are worth counting. The number of boundary violations in the to-do list goes down. The number of dependency cycles goes down. A typical change touches one module and one owner. And a new engineer can say which module a feature belongs in. These are my own measures and not a standard.
A plan for the first week
- List candidate modules from the business’s own vocabulary, with one owner each.
- Count how tangled you are with a dependency checker for your language.
- Put a dependency check around the module that changes most often.
- Write the trigger for extracting a service, in terms of release waiting, scaling or security.
- Review the list every quarter and extract only what meets a trigger. If you are leading a larger move across teams, my article on leading a technical initiative across several teams covers getting it agreed.
A modular monolith is not a stage you must grow out of, and a service is not a prize. Both hold a boundary, and the better one is the one you can afford to keep.
Frequently asked questions
What is the difference between a modular monolith and a monolith?
Both deploy as one unit. A modular monolith has modules with a public surface, written dependency rules and data ownership that a check enforces. A plain monolith has no such rules, so any code can reach any other code.
Should I start with a modular monolith or microservices?
Start with a modular monolith if your teams can release together and you are still learning the domain. Fowler says in Monolith First that you shouldn’t start a new project with microservices.
How do I enforce module boundaries in one codebase?
Make the public surface small, write down the allowed dependencies and fail the build when a change breaks them. In Ruby, Packwerk does this for packages. Give each module its own tables and keep the graph free of cycles.
Can I untangle a messy monolith without a rewrite?
Yes. Name the contexts, write down their boundaries, move one area at a time and put a dependency check around each module. At a company I worked at, I led a team of 7 that restructured a tangled MVC codebase in place, and it was not split into services.