What is a 'modular monolith,' and how does it try to capture the team-autonomy benefits of microservices while avoiding the distributed-system costs of splitting services over the network?

## What a modular monolith is A modular monolith is an **architectural middle ground**: the deployment topology of a classic monolith — one build artifact, one running process (or horizontally scaled copies of that same process), typically one database — combined with the internal discipline of microservices, where the codebase is partitioned into modules with explicit, enforced boundaries. Concretely, each module (say, billing, inventory, notifications): - lives in its own package or Gradle/Maven module - exposes only a small public interface that other modules are allowed to call - keeps its internal classes, and critically its own database tables, private Tooling enforces this at build time: in the JVM world, **Spring Modulith** or **ArchUnit** rules fail the build if module `inventory` imports an internal class from `billing` instead of going through billing's published API; in other ecosystems, module linters or internal/package-private visibility modifiers do the same job. ## Why the pattern exists The reason this pattern exists is that the two headline benefits people reach for microservices for — **team autonomy** and **enforced separation of concerns** — don't actually require crossing a process boundary. A network call between two microservices and a compiler-enforced call between two in-process modules both prevent module A from reaching into module B's internals; the difference is that the in-process call is synchronous, type-checked, participates in the same transaction, and fails in exactly the ways a normal function call fails (an exception), not in the many new ways a network call can fail (timeout, partial success, duplicate delivery, version skew between independently-deployed callers). A modular monolith captures the organizational discipline without incurring the operational cost of distribution. ## The trade-offs The trade-offs run in both directions. **What you keep, relative to an unstructured monolith:** - clear ownership boundaries that make onboarding and code review tractable - the option to extract any module into a real microservice later with comparatively little pain (since its public API is already the seam) - dramatically simpler local development — one process to run, one debugger to attach **What you give up, relative to real microservices:** - you cannot deploy the billing module's bug fix without redeploying and re-testing the whole application - you cannot scale inventory independently if it's the CPU-hungry module — the whole process scales as a unit - because modules commonly still share one physical database, a careless migration or an accidentally-shared table can silently reintroduce coupling that the code-level boundary was supposed to prevent, unless the team also enforces schema-level separation ## Failure modes The failure modes of a modular monolith in production are mostly failures of discipline rather than of the pattern itself. 1. The most common is **"boundary erosion"**: under deadline pressure, an engineer adds a direct database query or a direct class reference across a module boundary because it's faster than going through the public API, and without automated enforcement that erosion compounds silently until the "modular" monolith is just a monolith with folders. 2. **A second failure mode** is treating the module split as a substitute for good domain design: mechanically drawing module lines around existing classes without a real bounded-context analysis just produces internal spaghetti with extra ceremony. 3. **A third is scaling limits** — if one module truly needs orders of magnitude more compute or a very different scaling profile, the shared-process constraint becomes a real ceiling that only extraction into a separate service can lift. ## Where it shows up A concrete real-world reference point is **Shopify's** well-documented move to a modular monolith for its core Ruby application: after early experiments extracting services, Shopify found that for its scale and team structure at the time, most services still needed to talk to the core commerce logic constantly, so they invested instead in enforcing module boundaries (via tooling akin to **Packwerk**) inside the Rails monolith rather than paying network overhead for calls that were conceptually still "the same request." The **Spring Modulith** project formalizes the same idea for the Java/Kotlin ecosystem, providing build-time verification of module boundaries plus optional event-based communication between modules, explicitly positioning itself as a stepping stone that keeps the option to extract a module into a real microservice open without forcing that decision before the domain boundaries are proven stable.