Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Monolith

Pattern

A reusable solution you can apply to your work.

Context

When people talk about system architecture, the first question is often: one thing or many things? A monolith is the answer “one thing,” a system built, deployed, and evolved as a single, tightly unified unit. It operates at the architectural scale and is neither inherently good nor inherently bad. It’s a structural choice with real tradeoffs.

A monolith isn’t the same as a mess. A well-structured monolith has clear internal modules, strong boundaries, and good separation of concerns. It’s simply deployed as one artifact rather than many.

Problem

When is it right to keep everything together, and when does that unity become a trap?

Forces

  • A single deployable unit is simpler to build, test, and operate. There’s no network between parts, no distributed state to manage.
  • As a system grows, a monolith can become hard to understand because everything is reachable from everything else.
  • Deployment is all-or-nothing: a small change to one corner forces a full redeploy.
  • Teams working on different parts of a monolith can step on each other if internal boundaries are not respected.

Solution

Start with a monolith unless you have a strong reason not to. For most projects, especially new ones, the simplicity of a single deployable unit outweighs the flexibility of a distributed architecture. The key is to maintain internal structure even though deployment boundaries don’t force you to.

A “modular monolith” is the sweet spot for many teams: one deployable unit, but with clear internal modules, explicit interfaces between them, and disciplined coupling. If you later need to extract a module into a separate service, the internal boundary gives you a seam to cut along.

The danger isn’t the monolith itself. It’s the big ball of mud, where internal structure has eroded and every part depends on every other part. That happens when boundaries aren’t enforced, when convenience overrides design, and when “just this once” becomes the norm.

In agentic coding, a well-structured monolith can actually be easier for an AI agent to work with than a distributed system. The agent can search and read the entire codebase in one place, run all tests with one command, and trace call chains without crossing network boundaries. Problems arise when the monolith lacks internal structure; then the agent’s context window fills with undifferentiated code.

How It Plays Out

A startup builds its product as a monolith. For the first two years, this is a clear win: one repository, one deployment pipeline, one place to debug. The team moves fast. As the team grows to twenty engineers, they start stepping on each other. Rather than splitting into microservices immediately, they invest in internal module boundaries — making the monolith modular. This gives them the benefits of clear structure without the operational complexity of distributed systems.

An AI agent is asked to trace a bug from the API endpoint to the database query. In a monolith, the agent can follow the call chain through function calls and imports, all in one codebase. In a distributed system, the agent would need to follow network calls across services, parse configuration files to find service addresses, and piece together logs from multiple sources. For this task, the monolith is friendlier.

Note

“Monolith” is often used as a pejorative, but that reflects confusion between structure and deployment. A monolith with good internal structure is a respectable architecture. A distributed system with no internal structure is just a distributed mess.

Example Prompt

“Trace the bug from the API endpoint to the database query. Follow the call chain through function calls and imports — everything is in this single codebase, so you shouldn’t need to look at any external services.”

Consequences

A monolith reduces operational complexity: one thing to build, test, deploy, and monitor. It avoids the “distributed systems tax” of network failures, serialization overhead, and coordination protocols.

The cost appears at scale. Deployment coupling means a bug in one area can block releases of unrelated changes. Build times grow. Test suites slow down. If internal boundaries aren’t maintained, the codebase becomes increasingly difficult for anyone, human or agent, to work with.

The real question isn’t “monolith or not?” but “is our monolith well-structured?” A modular monolith that can be split later is nearly always a better starting point than premature decomposition.

  • Is an: Architecture choice — one of the fundamental architectural styles.
  • Contrasts with: Decomposition — decomposition breaks the monolith into parts.
  • Improved by: Module, Boundary, Separation of Concerns — internal structure keeps a monolith healthy.
  • Threatens: Cohesion — without discipline, monoliths drift toward low cohesion and high coupling.
  • Often confused with: Big Ball of Mud – a monolith is a deployment choice; mud is a structural failure.