Spring Modulith — The Modular Monolith

Get the simplicity of a monolith with the clean boundaries of microservices — decompose later when you actually need to, not because of hype.

%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '13px', 'fontFamily': 'Inter, -apple-system, sans-serif'}, 'flowchart': {'nodeSpacing': 30, 'rankSpacing': 50, 'padding': 12, 'curve': 'basis'}, 'sequence': {'actorMargin': 60, 'messageMargin': 40}, 'class': {'padding': 12}}}%%
flowchart TD
    subgraph Monolith["Monolithic Application (One Deployment)"]
        subgraph Order["📦 Order Module"]
            OA["OrderService (public)"]
            OI["OrderRepository (internal)"]
        end
        subgraph Payment["💳 Payment Module"]
            PA["PaymentService (public)"]
            PI["PaymentGateway (internal)"]
        end
        subgraph Inventory["📋 Inventory Module"]
            IA["InventoryService (public)"]
            II["StockCalculator (internal)"]
        end
    end

    OA -->|"allowed ✅"| PA
    OA -->|"allowed ✅"| IA
    OA -.->|"❌ BLOCKED"| PI
    OA -.->|"❌ BLOCKED"| II

    style Order fill:#EFF6FF,stroke:#DBEAFE,color:#1E40AF
    style Payment fill:#ECFDF5,stroke:#6EE7B7,color:#1E40AF
    style Inventory fill:#FEF3C7,stroke:#FCD34D,color:#1E40AF

Why Modular Monolith?

The Microservices Trap

Modular Monolith Advantages

Getting Started

Dependencies

<dependency>
    <groupId>org.springframework.modulith</groupId>
    <artifactId>spring-modulith-starter-core</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.modulith</groupId>
    <artifactId>spring-modulith-starter-test</artifactId>
    <scope>test</scope>
</dependency>

Package Structure = Module Structure

com.example.shop/
├── ShopApplication.java                  ← main class
├── order/                                ← 📦 Order Module
│   ├── OrderService.java                 ← PUBLIC (accessible by other modules)
│   ├── OrderController.java              ← PUBLIC
│   ├── Order.java                        ← PUBLIC (shared type)
│   └── internal/                         ← INTERNAL (only this module can access)
│       ├── OrderRepository.java
│       ├── OrderValidator.java
│       └── OrderMapper.java
├── payment/                              ← 💳 Payment Module
│   ├── PaymentService.java              ← PUBLIC
│   └── internal/
│       ├── StripeGateway.java
│       └── PaymentRepository.java
├── inventory/                            ← 📋 Inventory Module
│   ├── InventoryService.java            ← PUBLIC
│   └── internal/
│       ├── StockCalculator.java
│       └── WarehouseClient.java
└── shared/                               ← 🔗 Shared kernel (used by all)
    ├── Money.java
    └── DomainEvent.java

Architecture Verification

Module Boundary Tests

@SpringBootTest
class ModularityTests {

    @Test
    void verifyModuleStructure() {
        ApplicationModules modules = ApplicationModules.of(ShopApplication.class);
        modules.verify();  // 💥 FAILS if any module accesses another's internals!
    }

    @Test
    void documentModules() {
        ApplicationModules modules = ApplicationModules.of(ShopApplication.class);
        // Generates docs/modulith-components.puml (architecture diagram!)
        new Documenter(modules)
            .writeModulesAsPlantUml()
            .writeIndividualModulesAsPlantUml();
    }
}

If OrderService tries to import payment.internal.StripeGateway, the test FAILS:

Module 'order' depends on non-exposed type 
  payment.internal.StripeGateway 
in module 'payment'!

Event-Based Module Communication

Instead of direct method calls between modules (which creates coupling), use application events:

// Order module publishes an event
@Service
@RequiredArgsConstructor
public class OrderService {

    private final ApplicationEventPublisher events;
    private final OrderRepository orderRepository;

    @Transactional
    public Order placeOrder(OrderRequest request) {
        Order order = orderRepository.save(new Order(request));

        // Publish event — decoupled from payment/inventory!
        events.publishEvent(new OrderPlaced(
            order.getId(), order.getCustomerId(), order.getTotal()
        ));

        return order;
    }
}

// The event (in order module's public API)
public record OrderPlaced(String orderId, String customerId, Money total) {}

// Payment module listens (no import of order internals!)
@Service
public class PaymentEventHandler {

    @ApplicationModuleListener  // Spring Modulith's enhanced listener
    public void onOrderPlaced(OrderPlaced event) {
        paymentService.processPayment(event.orderId(), event.total());
    }
}

// Inventory module also listens
@Service
public class InventoryEventHandler {

    @ApplicationModuleListener
    public void onOrderPlaced(OrderPlaced event) {
        inventoryService.reserveStock(event.orderId());
    }
}

%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '13px', 'fontFamily': 'Inter, -apple-system, sans-serif'}, 'flowchart': {'nodeSpacing': 30, 'rankSpacing': 50, 'padding': 12, 'curve': 'basis'}, 'sequence': {'actorMargin': 60, 'messageMargin': 40}, 'class': {'padding': 12}}}%%
flowchart LR
    O["Order Module<br/>(publishes OrderPlaced)"] -->|"event"| EB(("Event Bus<br/>(ApplicationEventPublisher)"))
    EB -->|"listens"| P["Payment Module"]
    EB -->|"listens"| I["Inventory Module"]
    EB -->|"listens"| N["Notification Module"]

    style EB fill:#FEF3C7,stroke:#FCD34D,color:#1E40AF

Event Externalization (Bridge to Microservices)

When you're ready to extract a module into a separate service, Spring Modulith can externalize events to Kafka/RabbitMQ without changing your code:

// Same code as before — just add @Externalized
@Externalized("orders.placed")  // published to Kafka topic "orders.placed"
public record OrderPlaced(String orderId, String customerId, Money total) {}

spring:
  modulith:
    events:
      externalization:
        enabled: true
    kafka:
      topic-prefix: shop

Now OrderPlaced is published both locally (for in-process listeners) AND to Kafka (for external services). This is the smooth migration path:

1. Start with in-process events
2. Extract a module into a separate service
3. The external service listens on Kafka
4. Remove the in-process listener
5. No event schema changes needed

Module Testing (Isolation)

// Test a single module in isolation (fast, focused)
@ApplicationModuleTest
class OrderModuleTest {

    @Autowired
    private OrderService orderService;

    @Test
    void shouldCreateOrder(Scenario scenario) {
        // Given/When
        OrderRequest request = new OrderRequest("cust-1", List.of(item));

        // Execute and verify the published event
        scenario.stimulate(() -> orderService.placeOrder(request))
            .andWaitForEventOfType(OrderPlaced.class)
            .matchingMappedValue(OrderPlaced::customerId, "cust-1")
            .toArrive();
    }
}

When to Extract to Microservice

Interview Questions