What is a modular monolith, and what concretely distinguishes it from a monolith whose packages happen to be organized by feature but have no enforced boundaries?

## What a modular monolith is A modular monolith ships as a **single deployable unit** and runs as a **single process**, exactly like a plain monolith, but its codebase is decomposed into modules that behave like miniature, in-process services. Each module typically maps to one bounded context — orders, billing, catalog, notifications — and is organized as its own top-level package. Inside that package, the module keeps a small, deliberate public surface: - **Interfaces, request/response DTOs, and event classes** that other modules are allowed to depend on. - **Everything else** — JPA entities, repositories, internal helper services, mapping code — lives in a sub-package (often literally named `internal`) that is package-private or otherwise marked non-exported. ## How the boundary is checked A verification tool then walks the compiled classpath or source graph and checks that no class outside a module's public sub-package is referenced from another module. - **Spring Modulith** does this with `ApplicationModules.of(Application.class).verify()`, usually wired into a JUnit test that runs on every build. - **By hand**, a similar effect can be achieved with ArchUnit rules such as 'classes in package `..orders.internal..` may only be accessed by classes in `..orders..`'. The moment a developer imports `orders.internal.OrderRepository` from the `billing` module, the build goes red, not months later during a painful refactor. ## Why the enforcement is the entire point This enforcement is the entire point, because the alternative failure mode is extremely common and well documented: a codebase organized into feature packages 'because it looks clean' but with no verification degrades under delivery pressure. 1. A developer needing one field from another module's entity takes the **five-minute path** of importing the repository directly instead of the **twenty-minute path** of adding a proper API method. 2. A year later ten such shortcuts exist, the module graph is a cycle, and nobody can deploy or even test one module in isolation anymore. 3. Teams call this a 'big ball of mud' or, when it happens after a botched microservices split, a 'distributed monolith'. A modular monolith is a deliberate answer to that decay: keep the operational simplicity of one deployable — one build, one deploy pipeline, one process to run locally, ACID transactions available within a module — while getting the design discipline usually associated with microservices, namely that a module cannot be bypassed, only asked. ## The trade-off The trade-off is real on both sides. Building and maintaining the enforcement costs something: - The verification test has to actually run in CI (not just exist). - The team needs a convention for where a module's public API lives. - Discipline is needed about what belongs in the DTO/API layer versus the entity layer, because leaking a JPA entity as if it were a DTO defeats the boundary even when the visibility rule technically passes. In exchange, you get compile/test-time protection instead of relying on people remembering the rules, and you retain a much lower operational bill than a real microservice split: no service discovery, no per-module deployment pipeline, no network calls (with their retries, timeouts, and partial failures) between modules that are really just business capabilities of the same product. What you give up compared to true microservices is independent scaling and deployment — all modules ride in the same JVM and go down together — and, unless the team is careful, an easy route to accidentally share a single database schema across modules in a way the code-level boundary can't see or stop. ## Failure modes in production 1. **Database coupling.** That last point is also the most common production failure mode: two modules whose code never imports each other directly nonetheless read and write the same database tables, or one module's migration silently depends on a column another module owns. The build stays green because the enforcement tool only understands Java/Kotlin visibility, not SQL, so the coupling is invisible until a schema change in one module breaks another module's queries at runtime. 2. **The god module.** A second common failure is a single module — often called a 'god module' like `common` or `core` — becoming the dumping ground for anything nobody wants to own, which slowly reintroduces the everything-depends-on-everything problem the whole structure was meant to prevent. 3. **Resource-level coupling.** A third is resource-level coupling: because all modules share one JVM, a memory leak, an unbounded thread pool, or a blocking call inside one module can degrade or take down every other module's endpoints even though their code was never coupled. ## The concrete example on the JVM Spring Modulith is the concrete, named example of this pattern for the Spring/JVM ecosystem. It: - derives modules from the top-level packages under the main application package; - offers `@ApplicationModuleTest` to boot only one module (plus the modules it declares as dependencies) for fast integration tests; - supports declaring allowed dependencies explicitly between modules; - provides an in-process event publication mechanism so modules can react to each other's domain events (e.g., a `billing` listener reacting to an `OrderPlaced` event published by `orders`) without calling each other synchronously at all.