Spring Modulith

Everything so far - feature modules, enforced boundaries, API-and-event communication - can be done by hand with package conventions and ArchUnit. Spring Modulith is a Spring project that makes all of it first-class and Spring-native: it defines what a module is by convention, verifies the boundaries in a one-line test, gives you reliable module events, and even generates documentation. It's the framework encoding of this entire module.

Application modules by convention

Spring Modulith treats each direct sub-package of your main application package as an application module, with a simple visibility rule: the module's top-level types are its public API, and anything in sub-packages is internal:

com.ledger                    ← application package
├── LedgerApplication.java
├── billing/                  ← an application module
│   ├── BillingApi.java       ← top-level = PUBLIC (other modules may use)
│   ├── Invoice.java          ← top-level = PUBLIC
│   └── internal/             ← sub-package = INTERNAL (hidden from other modules)
│       └── InvoiceRepository.java
└── orders/                   ← another application module
    └── ...

No module-info.java, no manual ArchUnit rules for the basic case - the convention is the boundary: other modules may reference billing's top-level types but not anything under billing.internal. You can refine visibility with @ApplicationModule (e.g. declaring allowed dependencies or named interfaces).

Verifying boundaries in one test

The killer feature: a single test verifies the entire module structure - no cross-module access to internals, no cyclic dependencies between modules:

class ModularityTests {
    ApplicationModules modules = ApplicationModules.of(LedgerApplication.class);

    @Test
    void verifiesModularStructure() {
        modules.verify();   // fails if any module touches another's internals or a cycle exists
    }
}

That one line replaces a stack of hand-written ArchUnit rules and fails the build the moment someone violates a boundary. It's the enforcement mechanism from two lessons ago, built in.

Module events, made reliable

Spring Modulith builds on Spring's ApplicationEventPublisher but adds what production needs. @ApplicationModuleListener marks a listener that runs asynchronously and transactionally (in its own transaction, after the publisher's commits):

@Component
class Fulfillment {
    @ApplicationModuleListener                 // async + transactional module event handling
    void on(InvoicePaid event) { beginShipment(event.orderId()); }
}

Crucially, Modulith offers an event publication registry: it persists each event before delivery and marks it completed after the listener succeeds, so an event isn't lost if the app crashes mid-handling, and incomplete events can be republished on restart. That's the transactional outbox pattern (from the DDD domain-events lesson) provided out of the box - the reliability layer that turns fire-and-forget events into something you can trust between modules.

Documentation and observability for free

Because Modulith understands your modules, it can generate documentation from them: Documenter produces PlantUML/C4 component diagrams of your modules and their dependencies, plus per-module "canvas" summaries - always in sync with the code, not a stale wiki page. It also integrates with Micrometer/Actuator to observe module-to-module interactions. The architecture becomes visible and self-describing.