Modular Monolith - Learning Module

Loading content...

0/273

The Middle Ground

Beyond the Binary Choice

In architecture discussions, engineers often frame the choice as binary: monolith or microservices. This false dichotomy has led countless organizations down troubled paths—either struggling with an entangled monolith they can't evolve, or drowning in microservices complexity they weren't ready to handle.

But there's a compelling middle ground that combines the best of both worlds: the Modular Monolith. This architecture gives you the deployment simplicity of a single application while providing the organizational structure and future flexibility of a well-designed microservices system.

Pioneered by practitioners like Simon Brown and championed by companies like Shopify (which runs one of the world's largest modular monoliths), this pattern has proven itself at massive scale while avoiding the operational overhead of distributed systems.

What You Will Learn

By the end of this page, you will understand what a modular monolith is, why it represents a strategic sweet spot for many organizations, and how it positions you for future evolution—whether that's continued monolithic growth or strategic microservices extraction.

The Architecture Spectrum

Before we dive into modular monoliths, let's establish the full spectrum of architectural choices. Understanding where each option sits—and what tradeoffs it embodies—is essential for making informed decisions.

The Traditional Monolith:

A traditional monolith is a single deployable unit where all code lives together, typically without clear internal structure. Components are tightly coupled, database tables are shared freely, and the boundary between different business domains is often blurred or nonexistent.

Characteristics:

Single deployment unit
Shared database with coupled schema
No enforced boundaries between components
Direct function calls between any parts of the codebase
Changes in one area can unexpectedly break distant parts

The Big Ball of Mud:

The extreme form of the traditional monolith—code accumulated over years without structure, where dependencies form an incomprehensible web and changes require archaeology to understand impact. This is what monoliths become when not actively maintained.

The Architecture Spectrum
Architecture	Coupling	Deployment	Team Scalability	Operational Complexity
Big Ball of Mud	Extreme	Single unit	Very Poor	Low (but high change risk)
Traditional Monolith	High	Single unit	Limited	Low
Modular Monolith	Controlled	Single unit	Good	Low
Hybrid (Monolith + Services)	Medium	Few units	Good	Medium
Microservices	Loose	Many units	Excellent	High
Nano-services	Minimal	Very many units	Variable	Very High

Key Insight: Coupling and Deployment Are Orthogonal

A critical realization is that internal structure (coupling) and deployment model are separate concerns. You can have:

A poorly structured monolith (tightly coupled, single deployment)
A well-structured monolith (loosely coupled, single deployment) — this is the modular monolith
A poorly structured distributed system (tightly coupled services, multiple deployments) — the distributed monolith anti-pattern
A well-structured distributed system (loosely coupled services, multiple deployments)

The modular monolith chooses loose coupling with single deployment—gaining the benefits of structure without the costs of distribution.

The Distributed Monolith Trap

Many organizations rush to microservices without addressing coupling first. The result is a 'distributed monolith'—services that must be deployed together, share databases, and require coordinated changes. You get all the complexity of distribution with none of the benefits. The modular monolith explicitly avoids this trap by handling coupling before distribution.

What Makes a Monolith Modular

A modular monolith isn't just a monolith with folders. It's characterized by enforced boundaries, explicit contracts, and controlled coupling. The key word is enforced—the structure must be actively maintained, not just documented.

The Four Pillars of Modularity:

Defining Characteristics

•Explicit Module Boundaries — Each module owns a clearly defined slice of the domain. Cross-module dependencies are intentional and minimized. The boundary is visible in code structure, package organization, and build configuration.
•Encapsulated Data — Each module owns its data and exposes it only through defined interfaces. No module directly queries another module's database tables. Data sharing happens through APIs or events, not SQL joins.
•Published Interfaces — Modules expose explicit public APIs that other modules can depend on. Internal implementation details remain private. Changes to internals don't break consumers. This mirrors the service boundary concept from microservices.
•Enforced Dependencies — The build system, linter, or architecture tests actively prevent violations. If module A shouldn't call module B's internals, the code won't compile or the CI pipeline will fail. Rules aren't just documented—they're automated.

Modular Monolith Project Structure

Project Layout

my-modular-monolith/
├── modules/
│   ├── user/
│   │   ├── internal/           # Private implementation
│   │   │   ├── repository/
│   │   │   ├── domain/
│   │   │   └── services/
│   │   ├── api/                # Public interface
│   │   │   ├── UserService.ts
│   │   │   ├── types.ts        # Public DTOs
│   │   │   └── events.ts       # Domain events
│   │   └── index.ts            # Single export point
│   │
│   ├── order/
│   │   ├── internal/
│   │   │   ├── repository/
│   │   │   ├── domain/
│   │   │   └── services/
│   │   ├── api/
│   │   │   ├── OrderService.ts
│   │   │   ├── types.ts
│   │   │   └── events.ts
│   │   └── index.ts
│   │
│   ├── inventory/
│   │   ├── internal/
│   │   ├── api/
│   │   └── index.ts
│   │
│   └── payment/
│       ├── internal/
│       ├── api/
│       └── index.ts
│
├── shared/                     # Shared kernel (minimal)
│   ├── types/
│   ├── events/
│   └── utils/
│
├── infrastructure/             # Cross-cutting concerns
│   ├── database/
│   ├── messaging/
│   └── http/
│
└── main.ts                     # Application entry point

Critical: The Boundary Isn't Just a Folder

The folder structure above is necessary but not sufficient. What makes it a modular monolith is the enforcement layer:

Architecture Rules (ArchUnit Example)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
// Java with ArchUnit - Enforced at build time
@ArchTest
static final ArchRule modules_should_not_access_internals_of_other_modules =
    noClasses()
        .that().resideInAPackage("..order.internal..")
        .should().accessClassesThat()
        .resideInAPackage("..user.internal..")
        .orShould().accessClassesThat()
        .resideInAPackage("..inventory.internal..")
        .orShould().accessClassesThat()
        .resideInAPackage("..payment.internal..");
 
@ArchTest
static final ArchRule modules_can_only_access_public_apis =
    classes()
        .that().resideInAPackage("..order..")
        .should().onlyAccessClassesThat()
        .resideInAnyPackage(
            "..order..",           // Own module
            "..user.api..",        // Other modules' public APIs only
            "..inventory.api..",
            "..shared..",          // Shared kernel
            "java..",              // Standard library
            "org.springframework.." // Framework
        );

Enforcement Is Non-Negotiable

Without automated enforcement, module boundaries erode within months. Documentation is forgotten, 'quick fixes' bypass the rules, and the modular structure collapses into a traditional monolith. The investment in enforcement tooling is what preserves the architecture's value.

Why Choose the Middle Ground

The modular monolith occupies a strategic position that maximizes benefits while minimizing costs. Understanding the specific advantages helps you articulate the case for this architecture.

Operational Simplicity:

A modular monolith is still a single deployment. This means:

One artifact to build, test, and deploy
No network calls between modules (function calls are faster, free, and don't fail)
No distributed transactions or eventual consistency between modules
Simpler debugging—full stack traces, single log stream, one process to inspect
Straightforward local development—run one service, not a dozen containers

Organizational Scalability:

Despite being a single deployment, teams can work independently:

Clear module ownership means clear team ownership
Module APIs serve as team contracts
Changes within a module don't require coordination with other modules
Code review boundaries align with module boundaries
Merge conflicts are isolated to module interfaces

Advantages Over Traditional Monolith

•Clear ownership and responsibility
•Reduced cognitive load per team
•Independent evolution of modules
•Enforced encapsulation prevents coupling creep
•Explicit public interfaces enable parallel development
•Easier to reason about change impact
•Foundation for future microservices extraction
•Better testability through module isolation

Advantages Over Microservices

•No network latency between modules
•No distributed system complexity
•ACID transactions across modules are trivial
•Single deployment pipeline to manage
•No service discovery or load balancing
•Simpler monitoring and debugging
•Lower infrastructure costs
•Faster development iteration

The Optionality Value:

Perhaps the most underappreciated benefit is optionality. A modular monolith preserves flexibility:

You can stay as a monolith indefinitely — If the modular structure serves your needs and team size, there's no requirement to move to microservices. Many successful companies run modular monoliths at scale.
You can extract services surgically — Because modules have explicit boundaries and interfaces, extracting a module into a service is a well-defined, low-risk operation. You're not untangling a web—you're relocating a pre-packaged unit.
You can experiment — Run one module as a separate service while keeping others in the monolith. This hybrid approach lets you learn distributed systems incrementally.
You maintain velocity — While others are debugging network partitions, you're shipping features. The time saved on operational complexity can be redirected to product development.

Shopify's Modular Monolith

Shopify's main application is one of the world's largest modular monoliths—millions of lines of Ruby serving enormous traffic. Rather than rushing to microservices, they invested heavily in modular structure, automated enforcement, and intentional boundaries. The result: team autonomy without distributed system overhead. Their experience demonstrates that modular monoliths scale far further than conventional wisdom suggests.

When Modular Monolith Shines

The modular monolith isn't universally correct—no architecture is. But there are situations where it represents the optimal choice, balancing current needs against future flexibility.

Optimal Scenarios:

Strong Fit For

•Early-stage startups — When speed matters more than scale, and team size doesn't yet warrant the overhead of distributed systems. The modular structure positions you for later growth without slowing current development.
•Teams with < 50 engineers — Below this threshold, the coordination overhead of microservices often exceeds the benefits. A modular monolith gives team autonomy without operational burden.
•Domains with tight coupling — Some domains genuinely require strong consistency and frequent cross-domain transactions. Forcing these into separate services creates artificial complexity.
•Evolving from a legacy monolith — When modernizing a big ball of mud, the modular monolith is a safe intermediate step. Establish boundaries first, extract services later (if ever).
•Limited DevOps maturity — If your team doesn't have Kubernetes expertise, observability infrastructure, or distributed debugging skills, microservices will be painful. The modular monolith lets you build product while skills develop.
•Uncertain domain boundaries — In new problem spaces, you don't yet know where service boundaries should be. Modules are cheaper to refactor than services. Learn the domain as a monolith, split when boundaries become clear.

When to Reconsider:

The modular monolith isn't always the answer. Consider alternatives when:

Scale requires independent deployment — If one module needs to scale 100x while others stay constant, separate services may be warranted
Technology diversity is required — Different modules may need different languages, runtimes, or databases
Team size exceeds operational capacity — At hundreds of engineers, deployment coordination becomes a bottleneck
Regulatory isolation is mandated — Certain data may need physical separation for compliance
You genuinely need independent failure domains — Some modules may need to survive when others fail

The Right Question

Instead of asking 'Should we use microservices?', ask 'What problem would microservices solve that a modular monolith can't?' If you can't articulate a specific, pressing problem, the modular monolith is likely the better choice.

The Mindset Shift

Adopting a modular monolith requires a mental shift. You're not building microservices, but you're also not building a traditional monolith. The discipline falls somewhere in between.

Think Like You'll Extract, But Don't Optimize For It:

Design modules as if they could become services—clear boundaries, encapsulated data, explicit interfaces. But don't add complexity for extraction you may never do:

Don't use HTTP between modules (use function calls)
Don't add message queues for in-process communication
Don't duplicate data in anticipation of future separation

The goal is extraction-ready, not extraction-optimized.

Treat Module Boundaries as Team Contracts:

Even though you're in one codebase, treat module interfaces with the same care you'd treat service APIs:

Version interfaces when making breaking changes
Document public APIs as if external teams would consume them
Review interface changes more carefully than internal changes
Consider backward compatibility within the monolith

Signs You've Adopted the Modular Mindset

•You ask 'which module owns this?' before writing code
•You feel resistance to adding cross-module dependencies
•You design module APIs before implementation
•You think about module consumers, not just callers
•You enforce boundaries automatically, not through code review alone
•You consider 'could this module be extracted?' as a design smell check—if it couldn't be, the boundaries may be wrong

The Discipline Advantage

The discipline required for a modular monolith is the same discipline required for successful microservices. Organizations that can't maintain module boundaries won't maintain service boundaries either. The modular monolith is a proving ground for architectural maturity.

Visualizing the Middle Ground

Let's visualize the different architectural approaches to understand where the modular monolith fits:

Converting Mermaid diagram...

Key Visual Insights:

Traditional Monolith: Everything connects to everything. Any change can impact any other part. The database is a single shared resource with no logical boundaries.
Modular Monolith: Clear boundaries exist between modules. Communication flows through public APIs. Internal implementation is hidden. The database may be shared but access is logically partitioned.
Microservices: Physical separation enforces boundaries. Network calls replace function calls. Each service has its own database. But this comes with significant operational overhead.

The modular monolith achieves the structural clarity of microservices without the network boundary. It's a logical separation rather than a physical one.

Summary: The Strategic Middle Ground

We've established the modular monolith as a strategic architectural choice—not a compromise, but an intentional optimization for specific tradeoffs. Let's consolidate the key insights:

Key Takeaways

•The modular monolith is a deliberate architecture — Not a monolith that happens to have folders, but a structured system with enforced boundaries, explicit interfaces, and controlled coupling.
•Coupling and deployment are orthogonal — You can have loose coupling with single deployment (modular monolith) or tight coupling with multiple deployments (distributed monolith anti-pattern).
•Enforcement is what makes it work — Architecture rules must be automated through build tools, linters, and tests. Documentation alone isn't enough.
•It provides operational simplicity — Single deployment, no network failures, simple debugging, straightforward local development.
•It enables organizational scalability — Clear module ownership allows teams to work independently within a single codebase.
•It preserves optionality — You can stay as a monolith, extract services surgically, or run a hybrid—the choice remains open.
•It's a maturity proving ground — The discipline for modular monoliths is the same discipline required for microservices success.

What's Next:

Now that we understand what a modular monolith is and why it's valuable, the next page explores Module Boundaries—how to identify, define, and enforce the boundaries between modules. We'll examine Domain-Driven Design principles, dependency analysis techniques, and practical strategies for drawing lines that will serve your system for years to come.

Page Complete

You now understand the modular monolith as a strategic middle ground between traditional monoliths and microservices. It offers the simplicity of single deployment with the organizational benefits of clear boundaries. Next, we'll learn how to design those boundaries effectively.