Designing Event-Driven Architectures with Spring Modulith

In the ever-evolving landscape of software design, the event-driven architectural (EDA) pattern has cemented its place as a powerful model for building responsive, decoupled, and scalable systems. Traditionally, implementing clean EDA within a monolithic application—especially a Spring Boot one—has been fraught with challenges. We often ended up with a tangle of @EventListener annotations, hidden side-effects, unclear module boundaries, and integration testing nightmares. Enter Spring Modulith, a relatively new experimental project from the Spring team that promises to bring order to this chaos. It offers a structured way to design and test modular monoliths, with first-class support for event-driven interactions.

The Monolith’s Dilemma: Chaos in Cohesion

Spring Boot excels at getting applications off the ground quickly. Its convention-over-configuration approach and rich ecosystem allow developers to focus on business logic. However, as the application grows, the lack of enforced structure often leads to the infamous “big ball of mud.” Components from different business domains become tightly coupled through direct method calls and shared database tables. Introducing events with Spring’s ApplicationEventPublisher help, but the flow of events becomes opaque. Which component listens to what event? What is the order of execution? How do you test a single business transaction in isolation? These questions become increasingly difficult to answer.

This is where the concept of the modular monolith shines. It’s an architectural style where the application is developed as a single deployment unit (a monolith) but is logically composed of well-defined, loosely coupled modules, each representing a specific business domain. The goal is to achieve high cohesion within modules and low coupling between them, making the codebase more understandable, maintainable, and eventually easier to split into microservices if needed. Spring Modulith is the toolkit to realize this pattern effectively.

Spring Modulith: A Primer

Spring Modulith is not a new framework but a set of conventions and utilities built on top of Spring Boot. It provides:

1. Explicit Module Boundaries: It encourages (and can verify) the physical packaging of your code into well-defined modules, typically represented as top-level packages (e.g., com.example.order, com.example.inventory, com.example.notification).
2. Structured Events: It formalizes the publication and consumption of events between these modules, making dependencies visible and manageable.
3. Improved Testability: It offers dedicated testing support to verify module boundaries and to write integration tests for event-based interactions.

At its core, Spring Modulith introduces the concept of Application Module Events. Unlike the generic ApplicationEvent, these events are strongly typed, clearly named, and their publication and consumption are tied directly to the module interfaces.

Designing Event-Driven Flows with Spring Modulith

Let’s design a classic e-commerce scenario: an Order module, an Inventory module, and a Notification module. When an order is completed, we need to reserve stock and send a confirmation email.

1. Defining Modules and APIs:
First, we structure our packages as explicit modules.

src/main/java/com/example/
├── order/
│   ├── Order.java
│   ├── OrderService.java
│   └── internal/ (private implementation details)
├── inventory/
│   ├── InventoryService.java
│   └── internal/
└── notification/
    ├── NotificationService.java
    └── internal/

Each module exposes a public API (classes outside its internal package) that other modules can interact with, preferably through interfaces.

2. Publishing Events from a Module:
In the Order module, after an order is completed, we want to publish an event. With Spring Modulith, we use the ApplicationModulePublisher (injected instead of the generic ApplicationEventPublisher).

package com.example.order;

import org.springframework.modulith.events.ApplicationModulePublisher;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

@Service
@Transactional
public class OrderService {
    private final ApplicationModulePublisher events;
    private final OrderRepository repository;

    public OrderService(ApplicationModulePublisher events, OrderRepository repository) {
        this.events = events;
        this.repository = repository;
    }

    public Order completeOrder(UUID orderId) {
        Order order = repository.findById(orderId).orElseThrow();
        order.complete();
        repository.save(order);

        // Publish a domain-specific event
        events.publish(new OrderCompleted(order.getId(), order.getCustomerId(), order.getTotalAmount()));
        return order;
    }
}

// The Event Record
package com.example.order;

public record OrderCompleted(UUID orderId, UUID customerId, BigDecimal amount) { }

3. Listening to Events in Another Module:
The Inventory The module needs to react to OrderCompleted. We create an event listener bean in the inventory package. Spring Modulith automatically routes the event to listeners in other modules.

package com.example.inventory;

import com.example.order.OrderCompleted;
import org.springframework.modulith.events.ApplicationModuleListener;
import org.springframework.stereotype.Service;

@Service
public class InventoryService {
    @ApplicationModuleListener
    public void onOrderCompleted(OrderCompleted event) {
        // Business logic to reserve stock for event.orderId()
        System.out.println("Reserving stock for order: " + event.orderId());
    }
}

The @ApplicationModuleListener annotation is a drop-in replacement for @EventListener that makes the inter-module dependency explicit. Spring Modulith’s documentation and runtime analysis will now recognize this contract between the Order and Inventory modules.

4. Managing Transactional Boundaries:
A critical aspect of EDA is transaction management. Does the listener run in the same transaction as the publisher? What happens if the listener fails? Spring Modulith integrates with Spring’s transaction management and provides an event publication registry. By default, events are published immediately upon transaction commit of the publishing method (@Transactional). This ensures that an event is only published if the business transaction was successful, preventing phantom events from side-effects that were rolled back. For asynchronous processing, you can annotate the listener with @Async.

The Superpower: Testing and Verification

This is where Spring Modulith truly shines. It provides two powerful testing tools:

A. Module Structure Verification:
You can write a simple test to ensure your package conventions and module dependencies are respected, preventing accidental coupling.

import org.springframework.modulith.core.ApplicationModules;
import org.springframework.modulith.docs.Documenter;
import org.junit.jupiter.api.Test;

class ModuleStructureTests {
    ApplicationModules modules = ApplicationModules.of(Application.class);

    @Test
    void verifiesModularStructure() {
        modules.verify(); // Fails if any illegal dependencies between modules are found.
    }

    @Test
    void createModuleDocumentation() {
        new Documenter(modules)
            .writeDocumentation(); // Generates AsciiDoc diagrams of your modules and event flows.
    }
}

B. Scenario-based Integration Testing:
You can test complete, event-driven business scenarios in a slice of your application, mocking only external systems.

import org.springframework.modulith.events.test.Scenario;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.junit.jupiter.api.Test;

@SpringBootTest
public class OrderIntegrationTests {
    @Autowired Scenario scenario;

    @Test
    void completesOrderAndReservesStock() {
        scenario.stimulate(() -> orderService.completeOrder(orderId))
                .andWaitForEventOfType(OrderCompleted.class)
                .matchingMappedValue(OrderCompleted::orderId, orderId)
                .toArriveAndVerify(inventoryService::stockReservedForOrder);
    }
}

This test clearly describes: “When I stimulate the completion of an order, I expect an OrderCompleted event to be published, and upon its arrival, the inventory service should have reserved stock.” It tests the integration through events without making direct service calls.

Benefits and Considerations

Benefits:

• Explicitness & Documentation: Module and event dependencies become part of the code structure, self-documenting the architecture.
• Improved Maintainability: The enforced boundaries prevent architectural decay. Changes are more localized.
• Evolutionary Path: A well-structured modular monolith is the perfect precursor to microservices. Each module has a clear API and domain, making splitting a mechanical rather than a mythical task.
• Simplified Testing: The scenario testing API is a game-changer for integration testing event flows.

Considerations:

• Experimental Status: As of this writing, Spring Modulith is marked as “experimental” in the Spring portfolio. Its API may evolve, though it’s stable and production-ready for many teams.
• Learning Curve: Teams must adopt the discipline of modular design. The tool enables it, but doesn’t automatically create a good design.
• Event Persistence: For guaranteed “at-least-once” delivery across application restarts, you need to pair it with a persistent event registry (JDBC or MongoDB implementations are provided).

Conclusion

Spring Modulith represents a significant step forward in architectural innovation within the Spring ecosystem. It addresses the very real problem of structural decay in growing applications by providing a pragmatic, code-first approach to building modular monoliths. Its first-class support for event-driven architecture turns what was often an implicit, hard-to-manage web of listeners into an explicit, verifiable, and testable contract between business domains. By adopting Spring Modulith, developers and architects can build systems that are not only responsive and decoupled but also fundamentally more understandable and maintainable—whether they remain a monolith or evolve into distributed services. It is a powerful testament to the idea that complexity is best managed not by jumping to distributed systems, but by first introducing rigorous clarity and structure at the code level.