Modular Monolith

1Definition

A modular monolith is a single deployable process (like a plain monolith) whose internal code is organized into strictly bounded modules that communicate through explicit, narrow interfaces — as if they were separate services, except the "network call" between them is still an in-process function call. It deliberately sits between a tangled monolith (any module can reach into any other module's internals) and microservices (every module is a separately deployed process).

┌───────────────────────────────────────────────────┐
│                  1 process, 1 deploy                 │
│  ┌───────────┐    ┌───────────┐    ┌───────────┐    │
│  │  orders    │    │ inventory  │    │ payments   │    │
│  │  module    │    │  module    │    │  module    │    │
│  │ ┌────────┐ │    │ ┌────────┐ │    │ ┌────────┐ │    │
│  │ │internal│ │    │ │internal│ │    │ │internal│ │    │
│  │ │ (priv) │ │    │ │ (priv) │ │    │ │ (priv) │ │    │
│  │ └────────┘ │    │ └────────┘ │    │ └────────┘ │    │
│  │  public API│    │  public API│    │  public API│    │
│  └─────┬──────┘    └─────┬──────┘    └─────┬──────┘    │
│        └──────only through public APIs──────┘           │
└───────────────────────────────────────────────────┘

The defining rule: module internals are private; only the module's declared public interface is callable from outside it — enforced the same way a service's network boundary is enforced, just without the network.

2Why This Sits Between the Two Extremes

The modular monolith gets almost all of the design discipline benefit of microservices (clear ownership, no accidental coupling, one team can't silently break another's invariants) while keeping the operational simplicity of a single deploy (one process to run, one transaction model, no network between modules that don't need one).

3What "Enforced" Actually Requires

Saying "just don't reach into other modules" is not enforcement — it's a promise nobody keeps under deadline pressure. A real modular monolith enforces the boundary at one of these levels, from weakest to strongest:

1. Convention + code review — weakest; relies entirely on humans catching violations. Breaks down as the team grows.
2. Lint rule (e.g. eslint-plugin-boundaries, dependency-cruiser import rules) — a CI check fails the build if orders/ imports a file from inventory/internal/. Strong, automated, but only as good as the rule's coverage and can be disabled with a comment.
3. Language-level module privacy — Java's module system (JPMS), or simply putting non-exported code in an internal/ package (Go enforces this at the compiler level: nothing outside a package can import an internal/ subpackage two directories up). This is enforced by the compiler, not a linter — cannot be bypassed without literally moving the file.
4. Physical package separation within a monorepo — each module is its own publishable package (@bright/orders, @bright/inventory) with its own package.json/exports field declaring the public surface; other modules can only import what's listed in exports. Combines well with option 3.

The stronger the enforcement mechanism, the closer a later extraction to a real microservice becomes a matter of deployment, not redesign.

4The Strangler Fig Path to Microservices

A modular monolith is also the standard staging ground for extracting a real microservice later, using the strangler fig pattern: gradually route traffic for one capability to a new external service while the old in-process module still exists, until the module can be deleted entirely.

Step 1: orders module calls inventory module directly (in-process)
Step 2: inventory module's public API is reimplemented as a thin client
        that calls a NEW external inventory-service over HTTP —
        orders module's call site doesn't change at all
Step 3: once the new service is proven correct in production,
        delete the old in-process inventory module entirely

Because callers only ever depended on the module's public interface (never its internals), swapping the implementation behind that interface from "in-process code" to "HTTP client calling a new service" requires touching exactly one module, not every caller.

5When a Modular Monolith Is the Wrong Choice

• The team is already organized as multiple fully independent teams that need to deploy on their own schedules — a modular monolith still ships as one artifact, so one team's broken build blocks everyone's deploy.
• Different modules have wildly different scaling needs today, not hypothetically (e.g., one module needs GPU instances, another needs to scale to 1000 replicas under bursty load) — a single process can't scale its parts independently.
• Regulatory/compliance boundaries require genuine process and data isolation (e.g., PCI scope reduction), not just code-level separation.

orders/
  public.go          // package orders — exported functions
  internal/
    validation.go     // package internal — NOT exported outside orders/
inventory/
  public.go

// dependency-cruiser rule, conceptually:
{
  "from": { "path": "^src/orders" },
  "to": { "path": "^src/inventory/internal" },
  "severity": "error"
}

⚠️ Common Pitfalls

1. Calling it "modular" with no enforcement mechanism — without a compiler check or a CI-gated lint rule, module boundaries erode within a few sprints under deadline pressure; this is just a tangled monolith with extra folders.
2. Sharing database tables directly across module boundaries — even with clean code-level boundaries, two modules reading/writing the same table are coupled exactly as tightly as if they shared code; each module should own its own tables (or schema) even while sharing one physical database/process.
3. Leaking domain types across the public API — if orders's public function returns inventory's internal ORM entity instead of a small DTO, the "boundary" is cosmetic; a real change to inventory's internals still breaks orders' compiled code.
4. Treating the module split as permanent and never revisiting it — module boundaries should be reconsidered as the domain is better understood; that's cheap in a modular monolith and expensive after a premature microservices extraction.
5. Skipping this stage entirely "because microservices are the goal anyway" — most systems never actually need the operational cost of microservices; a well-enforced modular monolith is a legitimate permanent end state, not just a stepping stone.

// orders calls inventory's public API…
const item: InventoryOrmEntity = inventory.getItem(sku);
item.reservedQty += 1;   // …and mutates its internals

const ok: boolean = inventory.reserve({ sku, qty: 1 });
// inventory decides how; orders can't touch its tables

📋 Quick Reference

Modular monolith = 1 deploy unit + enforced module boundaries + in-process calls
Enforcement strength: convention < CI lint rule < compiler-level privacy (e.g. Go internal/)
Cross-module calls: still function calls (µs, ACID transactions available)
Extraction path: strangler fig — swap a module's implementation behind its public API,
                 callers never change because they only ever depended on that API
Choose modular monolith when: 1 deploy is fine operationally, but code discipline isn't

🎤 Interview Q&A

🛠️ Practice exercises

Each exercise is a file in this topic folder. Code exercises are self-checking: run them and make the checks pass.

✅ Check yourself

Source: dist_modular_monolith_theory.md · generated by tools/build_lessons.py