System Design HLD-14.01
Monolith and modular monolith
What a monolith is, why it is often the right start, and how a modular monolith keeps strict internal boundaries without the cost of services.
The big idea
A monolithAn application built and deployed as a single unit that contains all of its features, typically with one codebase and one database. is one application that contains every feature: catalog, cart, checkout, accounts and admin, built from one codebase and deployed as one unit. "Monolith" is often used as an insult, but most successful products started as one and many still are. Calls between features are ordinary function calls, measured in nanoseconds, that cannot time out. A transaction can update the order and the inventory together. There is one thing to deploy, one thing to monitor, one place to debug.
What actually goes wrong in large monoliths is usually not the single deployable; it is the lack of boundaries inside it. Any code can call any other code and read any table, so after a few years every change risks breaking something unrelated. A modular monolithA single deployable application divided into modules with explicit public interfaces and enforced dependency rules, so each module can be owned and changed independently. fixes that: one deployable, but split into modules with clear public interfaces, rules about which module may depend on which, and ideally separate data ownership. You get much of the organizational benefit of services without paying for a network between them.
Think of an apartment building. One structure, one foundation, one front door, but each apartment has walls and a locked door. Neighbors cooperate through the hallway, not by walking through each other's kitchens.
How it works
Step 1: Why monoliths are a good default
For a small or medium team, a monolith has real advantages:
- Simplicity: one repository, one build, one deploy, one set of dashboards.
- Speed of change: a feature that touches three areas is one pull request and one deploy, not three coordinated releases.
- Performance and correctness: in-process calls are fast and cannot partially fail; database transactions ( Transactions and ACID ) keep data consistent without sagas.
- Easy refactoring: moving a boundary is an IDE refactor, not a migration between services.
It scales further than people expect: run many identical copies behind a load balancer ( Stateless vs stateful services ), add caches and read replicas, and a monolith can serve very large traffic.
Step 2: Where monoliths hurt
The pain grows with the number of people, not the number of requests:
- Coupling: without enforced boundaries, every module reaches into every other one, and changes ripple unpredictably.
- Coordination: hundreds of engineers share one deploy pipeline; one broken test blocks everyone, and releases become big and risky.
- Uniform scaling and technology: everything scales together and uses the same language and runtime, even if one part needs very different resources.
- Shared failure: a memory leak in one feature takes down the whole process.
Step 3: Make it modular
A modular monolith keeps the single deployable but adds structure:
- Each module has a small public API; everything else is private.
- Dependency rules say which modules may use which, with no cycles, and are checked automatically.
- Each module owns its tables; other modules go through its API instead of querying its data directly.
# A modular monolith: one deployable, but modules may only use each other's public API,
# and only along allowed dependency edges. A check like this runs in CI.
ALLOWED = { # module -> modules it may depend on
"checkout": {"catalog", "payments", "accounts"},
"payments": {"accounts"},
"catalog": set(),
"accounts": set(),
}
imports = [ # what the code actually imports (from a scan)
("checkout", "payments.api"),
("checkout", "catalog.api"),
("payments", "accounts.api"),
("catalog", "checkout.api"), # catalog reaching up into checkout: a cycle
("checkout", "payments.internal.ledger"), # bypassing the public api
]
problems = []
for src, target in imports:
module, *rest = target.split(".")
if module not in ALLOWED[src]:
problems.append(f"{src} may not depend on {module}")
elif rest[0] != "api":
problems.append(f"{src} uses {target}: only {module}.api is public")
print("\n".join(problems) or "boundaries ok")Output
catalog may not depend on checkout
checkout uses payments.internal.ledger: only payments.api is public A check like this in continuous integration catches the two classic boundary violations: a dependency in the wrong direction, and code reaching past a module's public API into its internals. Tools exist for many languages to enforce exactly these rules. With boundaries in place, extracting a module into a separate service later, if it is ever needed, becomes a well-defined job ( Migrating architectures: the strangler fig ).
Trade-offs
| Option | Wins when | Loses when |
|---|---|---|
| Monolith without boundaries | Prototypes and very small teams | Grows into tangled coupling as the team grows |
| Modular monolith | Most teams up to a few dozen engineers, and many larger ones | One deploy pipeline and shared runtime; boundaries need enforcement |
| Microservices | Many teams that need to deploy and scale independently | Network failures, distributed data and much more infrastructure |
Common mistakes
- Starting with microservices before the domain and team size justify them.
- Letting any module query any table, which makes later extraction nearly impossible.
- Believing a monolith cannot scale, when horizontal copies and caching go a long way.
- Boundaries documented but not enforced by tooling.
- Huge, infrequent releases instead of small, frequent deploys of the monolith.
In the wild
Segment
Goodbye microservices (opens in a new tab)Segment split its event delivery into a separate service and queue per destination after head-of-line blocking in a single shared queue let one slow destination delay all of them. As it grew to over 140 services, shared library versions diverged, each service needed its own scaling tuning, and three full-time engineers spent most of their time keeping the system alive. The team consolidated the services into a single service in one repository, with recorded test traffic so tests no longer depended on live endpoints, and reports making 46 improvements to its shared libraries in the following year, compared with 32 while on microservices.
Check yourself
-
What is the main difference between a monolith and a modular monolith?
Show answer
B. The modular monolith enforces internal module boundaries and public APIs within one deployable Both are one deployable; modularity adds enforced structure inside it.
-
Which is a real strength of a monolith?
Show answer
B. Calls between features are in-process and transactions can span features No network between modules means fast calls, no partial failures and simple transactions.
-
Module A reads module B's database tables directly. What problem does this cause?
Show answer
B. A is coupled to B's internal schema, so B cannot change or be extracted safely Data ownership through APIs keeps modules independently changeable.
-
What usually makes a monolith painful at scale?
Show answer
B. Many engineers sharing tangled code and one release process The problems are mostly organizational coupling, not throughput.
Recap
- A monolith is one deployable with all features: simple, fast in-process calls and real transactions.
- It scales horizontally further than its reputation suggests.
- Its pain grows with team size through coupling and shared release processes.
- A modular monolith adds public APIs, dependency rules and data ownership per module, enforced by tooling.
- Good module boundaries make a later extraction into services straightforward if it is ever needed.