Skip to content
System Design Lab
Microservice Patterns

Modular Monolith

One deployable with strong internal module boundaries: the simplicity and speed of a monolith, structured so modules can be extracted into services later — when a real need appears.

Intermediate 4 min read· Updated 2026-11-18

What you will learn

  • Explain what makes a monolith modular: enforced boundaries and owned data.
  • Compare in-process module calls with network calls between services.
  • See the shared-fate risk of one process and how extraction isolates it.
  • Enforce module boundaries in code.

Before you start

Overview

A house with separate rooms is still one building: one roof, one front door, short walks between rooms. Good walls keep the kitchen smell out of the bedroom. If you ever need a granny flat, a well-separated room is easy to turn into one.

A modular monolith is deployed as one application, but internally divided into modules along business boundaries (orders, customers, pricing). Each module exposes a small public API, hides its internals and owns its tables. Calls between modules are plain function calls — fast and reliable — while the boundaries keep the code changeable and make later extraction possible.

Run it

A checkout touches five modules. Compare A (in-process) with B (the same modules as services), then C and D, where finance starts running heavy reports at t = 10 s: inside the monolith (C) and as an extracted service (D). Watch the median (p50).

Loading simulation…

What makes it modular

  • Public API per module; everything else is package-private.
  • No shared tables: a module reads another module's data through its API (or events), never by joining its tables.
  • Dependencies point one way and are checked by tests, not by discipline.
  • Events between modules for reactions ("order placed → reserve stock"), so modules do not call each other in circles.

Enforcing boundaries with Spring Modulith

Modules are top-level packages; a test fails on illegal dependencies
// com.shop.orders   — public: OrderService, OrderPlaced; internal: orders.internal.*
// com.shop.inventory — listens to OrderPlaced, never imports orders.internal

@ApplicationModuleListener               // runs after the order transaction commits
void on(OrderPlaced event) {
    stock.reserve(event.orderId(), event.lines());
}

class ModularityTests {
    @Test
    void modulesRespectTheirBoundaries() {
        ApplicationModules.of(ShopApplication.class).verify();   // fails the build on a forbidden dependency
    }
}

Trade-offs

BenefitsCosts
SimplicityOne build, one deploy, one database transaction when needed.Every change ships the whole application.
PerformanceIn-process calls: no network latency or partial failure.Modules share CPU, memory and connection pools — one hot module hurts all.
EvolutionClear boundaries make later extraction cheap.Boundaries erode unless enforced by tooling.

Production considerations

  • Give heavy work (reports, exports) its own thread pool or a separate deployment of the same code.
  • Keep a schema per module so moving its data out later is a migration, not an archaeology project.
  • Track inter-module dependencies in CI; a growing cycle is the first sign of a big ball of mud.
  • Observe per module (metrics tags, log fields) so you know which one to extract if needed.

Further reading

Related topics