Every monolith starts with clean package boundaries and, eighteen months later, has a CustomerService that some OrderRepository imports directly because it was faster than going through the intended interface. Nothing enforced the boundary, so it eroded one convenient shortcut at a time. Spring Modulith exists specifically to take that erosion out of code review's hands and put it into a build step that fails.
Modules Are Just Packages, Until You Verify Them
Spring Modulith treats each top-level package under your main application package as a module, with public API defined by what's exposed at that top level and everything in nested packages treated as module-internal by default.
com.example.shop
├── order
│ ├── Order.java
│ ├── OrderService.java
│ └── internal
│ └── OrderRepository.java
├── customer
│ ├── Customer.java
│ ├── CustomerService.java
│ └── internal
│ └── CustomerRepository.javaAnything in order.internal is invisible to customer, and vice versa, by convention alone — until you add a test that actually checks it.
class ModularityTest {
ApplicationModules modules = ApplicationModules.of(ShopApplication.class);
@Test
void verifiesModuleStructure() {
modules.verify();
}
@Test
void documentsModules() {
new Documenter(modules)
.writeDocumentation()
.writeIndividualModulesAsPlantUml();
}
}modules.verify() fails the build the moment order reaches into customer.internal.CustomerRepository directly instead of going through CustomerService. That single test is what turns "we try to keep modules decoupled" into an actual, CI-enforced guarantee — the same kind of value a linter provides for code style, applied to architecture instead.
Cross-Module Communication Without Direct Coupling
Modulith doesn't forbid modules from interacting — it forbids them from reaching into each other's internals. The intended pattern for cross-module effects is the same Spring application events covered elsewhere: a module publishes an event, and other modules react without a compile-time dependency on each other's internal types.
public record OrderPlacedEvent(Long orderId, Long customerId) {}
@Service
public class OrderService {
private final ApplicationEventPublisher publisher;
public void placeOrder(OrderRequest request) {
Order order = save(request);
publisher.publishEvent(new OrderPlacedEvent(order.getId(), request.customerId()));
}
}@Component
class CustomerLoyaltyListener {
@ApplicationModuleListener
void on(OrderPlacedEvent event) {
loyaltyService.addPoints(event.customerId(), event.orderId());
}
}@ApplicationModuleListener is Modulith's own annotation, layered over @TransactionalEventListener and @Async, and it integrates with Modulith's event publication registry — an optional, JDBC-backed log of published events that guarantees at-least-once delivery even across an application restart between publish and handling. For cross-module side effects that genuinely can't be lost, that durability guarantee is worth the extra table.
When This Is Worth Adopting
Spring Modulith earns its place in a modular monolith specifically — a single deployable where the team wants microservice-style boundaries without microservice-style operational overhead. It's most valuable for a team of meaningful size (roughly five or more engineers touching the same codebase) where informal conventions about "don't reach into that package" have already started breaking down in practice. For a small team or a genuinely simple service, the enforcement is solving a coupling problem that hasn't materialized yet, and the module test failures will feel like friction rather than protection. The honest signal that it's time is a specific memory: someone recently found a cross-module import in review that shouldn't have existed, and everyone quietly agreed "we should catch that automatically" — Modulith is that automatic catch.
A worked example
Packages order, inventory, billing. Modulith verifies no order → billing internals. Public API is a package order.api. Application events for cross-module after commit. A CI test ApplicationModules.of(App.class).verify().
You document allowed cycles (none).
Failure modes
Dumping everything in service. Reflection and Spring beans bypassing package rules. Modulith tests disabled because of one violation. Shared util becoming a dumping ground. Events as a way to smuggle entities across modules.
Multi-module Maven that still imports impl jars.
When this is the wrong tool
A 6-class app. Modulith is not a mesh. If you already have real microservices, package rules in one repo are a different problem. Do not use it as a substitute for code review of API design. Hexagonal ports may overlap — pick a vocabulary. If the team ignores the failing ArchUnit/Modulith test, the tool is theater.
A worked failure mode
Modulith tests are skipped in CI; a cycle returns. Events are used but payloads include JPA entities that pull the graph across modules. The failure is a linter you do not run. Keep tests on, pass IDs not entities, and treat cycles as build breaks.
Modulith is the wrong tool for a 4-class app. It will not replace product thinking. Use it when the codebase is large enough to cheat boundaries.
A worked anti-pattern: the team ships the architecture, then staffs it like a toy. "Enforcing Module Boundaries in Spring Boot with Spring Modulith" needs boring operations—backups, timeouts, ownership, and a budget for the tax the idea always charges (compaction, replay, dual writes, extra latency, extra types). Unstaffed taxes come due at 2am. Put the tax in the design doc's cost section. If leadership wants the benefit without the tax, the honest answer is a smaller idea, not a heroic on-call rotation.
The wrong-tool test is easier with a concrete customer. If a user can lose money, lose access, or see someone else's data when "Enforcing Module Boundaries in Spring Boot with Spring Modulith" is slightly misapplied, do not let the pattern ride on defaults. Tighten the API, add an assertion in CI, and refuse silent fallbacks that look like success. Most production failures here are not exotic; they are a missing bound, a missing key, or a missing check that the original paper assumed a careful operator would have.