# Modular Monolith

A single deployable application organized into strongly bounded business modules with explicit interfaces and controlled dependencies.

- Type: framework
- Domain: Engineering & architecture
- Level: Intermediate
- Last reviewed: 2026-09-22
- Original: [Soroush’s Product Wiki](<https://wiki.soroush.uk/topic/modular-monolith/>)

## What it means

A modular monolith runs and deploys as one application while dividing its code into cohesive modules. Each module represents a business capability, hides its internal model and implementation, and exposes a deliberate interface to other modules. Unlike an unstructured monolith, dependency rules are part of the architecture and can be checked by tests or tooling.

## Why it matters

A single process avoids much of the networking, deployment, tracing, and consistency complexity of distributed services. Strong modules still reduce accidental coupling, clarify ownership, and allow teams to reason about portions of the system. The architecture can provide a practical foundation for product learning and may later support selective service extraction where evidence demands it.

## When to use it

Use a modular monolith for a new or moderately complex product when one deployment unit is operationally sufficient but maintainable boundaries matter. It is especially useful for small-to-medium teams and domains still being learned. Choose distribution only when independent scaling, isolation, technology, or release needs outweigh its costs.

## How it works

1. Discover modules around cohesive domain capabilities, not presentation, business, and database technical layers.
2. Give each module a public interface and keep implementation types, tables, and invariants private where practical.
3. Allow dependencies in deliberate directions and prohibit cycles or bypasses with automated architecture checks.
4. Use direct calls for simple interactions and internal events when looser timing or fan-out adds real value.
5. Test modules in isolation as well as through integrated application and end-to-end scenarios.
6. Observe cross-module coupling and extract a service only when measurable operational or organizational needs justify it.

## A practical example

A subscription product deploys billing, catalog, accounts, and notifications together. Billing exposes commands and queries but owns its tables and pricing rules; other modules cannot reach its repositories directly. Architecture tests reject forbidden imports. When notification traffic later needs separate scaling, its clean boundary makes extraction manageable rather than mandatory.

## Where it breaks

A modular monolith still shares a process and release, so one failure or resource spike may affect the whole application. Boundaries can erode through convenient internal access unless actively enforced. Large organizations may face coordination limits, and extracting a module is not automatic when transactions, data, or assumptions cross its supposed boundary.

## Common mistakes

- Calling packages or folders modules while allowing unrestricted cross-module access.
- Organizing modules by technical layer instead of cohesive business responsibility.
- Building distributed messaging inside one process for every interaction without a clear need.
- Treating future microservice extraction as guaranteed rather than preserving it as an option.

## Visualization

[View the visualization on the website](<https://wiki.soroush.uk/topic/modular-monolith/#visualization-modular-monolith>)

## Sources

1. [Spring Modulith Reference Documentation](<https://docs.spring.io/spring-modulith/reference/>) — Spring · Framework documentation
2. [Spring Modulith](<https://spring.io/projects/spring-modulith/>) — Spring · Institutional project overview
3. [Introducing Spring Modulith](<https://spring.io/blog/2022/10/21/introducing-spring-modulith/>) — Spring · Technical practice article

## Related topics

- [Microservices Architecture](<https://wiki.soroush.uk/topic/microservices-architecture/>)
- [Domain-Driven Design](<https://wiki.soroush.uk/topic/domain-driven-design/>)
- [Evolutionary Architecture](<https://wiki.soroush.uk/topic/evolutionary-architecture/>)
