Spring Boot 4 Complete Guide · Lesson

Application Modules and Boundary Verification

Define and enforce module boundaries with Spring Modulith's structure verification and documentation.

Application Modules and Boundary Verification is a free Spring Boot 4 Complete Guide lesson on CoddyKit — lesson 1 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Spring Boot 4 Complete Guide learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Why Module Boundaries Matter

A Spring Boot monolith tends to rot: any class can @Autowired any other, and over time everything depends on everything. Spring Modulith brings discipline by treating top-level packages under your main application package as application modules.

Each direct sub-package of the main package is one module.
Code inside a module's root package and a special api sub-package is public.
All other nested packages are internal and may not be referenced from other modules.

This lets you keep a single deployable while enforcing the boundaries you would get from microservices.

A Modular Package Layout

Consider an e-commerce app with the main class in com.shop. Each business concern becomes a direct sub-package. Spring Modulith infers the modules order, inventory, and notification from this structure alone — no XML, no annotations required.

Classes directly in com.shop.order are the module's public API; classes in com.shop.order.internal are hidden from other modules.

com.shop
├── ShopApplication.java
├── order
│   ├── OrderService.java          // public API
│   └── internal
│       └── OrderRepository.java   // internal
├── inventory
│   ├── InventoryService.java
│   └── internal
│       └── StockLevel.java
└── notification
    └── NotificationService.java

Adding the Modulith Dependency

Spring Modulith ships as a BOM plus a set of starters. For boundary verification and documentation you need spring-modulith-starter-core on the test classpath (and usually the test starter).

The BOM aligns all Modulith artifact versions with your Spring Boot version.
spring-modulith-starter-test brings the ApplicationModules verification API into the test scope.

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.springframework.modulith</groupId>
      <artifactId>spring-modulith-bom</artifactId>
      <version>1.4.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

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

Bootstrapping the Module Model

The entry point for everything is ApplicationModules.of(...). You pass it your main application class; Modulith scans the package structure and builds an in-memory model of every module and its allowed dependencies.

Calling verify() on that model fails fast if any module reaches into another module's internals or forms an illegal cyclic dependency.

import org.springframework.modulith.core.ApplicationModules;

class ModularityTests {

    static final ApplicationModules modules =
            ApplicationModules.of(ShopApplication.class);

    @org.junit.jupiter.api.Test
    void verifiesModularStructure() {
        modules.verify();
    }
}

What verify() Actually Checks

A single call to verify() enforces several structural rules at once:

No internal access: a module may only depend on another module's public types (root package or api package), never its internal sub-packages.
No cycles: module dependencies must form a directed acyclic graph; A→B→A fails the build.
Declared dependencies only: if a module restricts its allowed dependencies with @ApplicationModule(allowedDependencies = ...), any undeclared dependency is rejected.

Run it as a normal JUnit test so violations break CI before they ever ship.

Restricting Allowed Dependencies

By default a module may depend on any other module's public API. To tighten that, place a package-info.java in the module's root package and annotate it with @ApplicationModule.

Here the order module is allowed to use only inventory. If someone later wires NotificationService into the order module, verify() fails immediately.

@org.springframework.modulith.ApplicationModule(
    allowedDependencies = { "inventory" }
)
package com.shop.order;

import org.springframework.modulith.ApplicationModule;

Named Interfaces for Selective Exposure

Sometimes a module needs to expose a second public surface beyond its root package. A named interface marks an extra package as public and lets other modules target it explicitly.

Annotate the package with @NamedInterface("spi"); then a consumer can declare a dependency on order :: spi rather than the whole module.

// com/shop/order/spi/package-info.java
@org.springframework.modulith.NamedInterface("spi")
package com.shop.order.spi;

import org.springframework.modulith.NamedInterface;

// Consumer module restricts itself to that named interface
@org.springframework.modulith.ApplicationModule(
    allowedDependencies = { "order :: spi" }
)
package com.shop.billing;

Decoupling with Application Events

The cleanest way to keep modules independent is to avoid direct service calls altogether. Instead of injecting InventoryService into the order module, publish a Spring ApplicationEventPublisher event and let inventory listen.

This inverts the dependency: order no longer needs to know inventory exists, which keeps the verified dependency graph small and acyclic.

@org.springframework.stereotype.Service
class OrderService {

    private final org.springframework.context.ApplicationEventPublisher events;

    OrderService(org.springframework.context.ApplicationEventPublisher events) {
        this.events = events;
    }

    void placeOrder(String sku, int qty) {
        // ... persist order ...
        events.publishEvent(new OrderPlaced(sku, qty));
    }
}

record OrderPlaced(String sku, int qty) {}

Listening Across Modules

The inventory module consumes the event without any compile-time link back to order — it only depends on the published event type. Spring Modulith encourages @ApplicationModuleListener, which combines @Async, @Transactional(propagation = REQUIRES_NEW), and @TransactionalEventListener so the listener runs in its own transaction after the publisher commits.

@org.springframework.stereotype.Component
class InventoryEventHandler {

    @org.springframework.modulith.events.ApplicationModuleListener
    void on(OrderPlaced event) {
        // runs async, in a fresh transaction, after commit
        decrementStock(event.sku(), event.qty());
    }

    private void decrementStock(String sku, int qty) { /* ... */ }
}

Generating Living Documentation

The same module model can render documentation. Documenter produces C4-style component diagrams (PlantUML) and an Asciidoctor module canvas describing each module's dependencies, exposed types, and events.

Because the diagrams are derived from real code during the test run, they never drift out of date — regenerating is just re-running the test.

import org.springframework.modulith.docs.Documenter;

@org.junit.jupiter.api.Test
void writeDocumentation() {
    var modules = ApplicationModules.of(ShopApplication.class);
    new Documenter(modules)
            .writeModulesAsPlantUml()      // overview diagram
            .writeIndividualModulesAsPlantUml()
            .writeModuleCanvases();        // target/modulith-docs
}

A Standalone Cycle Check

The boundary idea — reject dependency cycles — is simple enough to model in plain Java. This runnable program builds a tiny module graph and reports whether a cycle exists, mirroring what verify() does for real modules.

import java.util.*;

public class CycleCheck {
    static Map<String, List<String>> graph = new HashMap<>();

    static void dependsOn(String a, String b) {
        graph.computeIfAbsent(a, k -> new ArrayList<>()).add(b);
    }

    static boolean hasCycle(String node, Set<String> stack, Set<String> seen) {
        if (stack.contains(node)) return true;
        if (seen.contains(node)) return false;
        seen.add(node);
        stack.add(node);
        for (String next : graph.getOrDefault(node, List.of()))
            if (hasCycle(next, stack, seen)) return true;
        stack.remove(node);
        return false;
    }

    public static void main(String[] args) {
        dependsOn("order", "inventory");
        dependsOn("inventory", "order"); // illegal cycle
        boolean cyclic = false;
        for (String m : graph.keySet())
            cyclic |= hasCycle(m, new HashSet<>(), new HashSet<>());
        System.out.println("Cycle detected: " + cyclic);
    }
}

Quick Check

You annotate the order module with @ApplicationModule(allowedDependencies = { "inventory" }). A new commit injects NotificationService (from the notification module) into a bean inside order. What happens?

Recap

You learned how Spring Modulith turns a Spring Boot monolith into a set of verified modules:

Modules are the direct sub-packages of your main application package; root and api/named-interface packages are public, the rest internal.
ApplicationModules.of(App.class).verify() enforces no internal access, no cycles, and declared-only dependencies as a JUnit test.
@ApplicationModule(allowedDependencies = ...) tightens the graph; @NamedInterface exposes extra public surfaces selectively.
Prefer application events with @ApplicationModuleListener to decouple modules instead of direct service calls.
Documenter generates always-current PlantUML diagrams and module canvases from the same model.

Frequently asked questions

Is the “Application Modules and Boundary Verification” lesson free?

Yes — the full text of “Application Modules and Boundary Verification” is free to read here on the web, and the Spring Boot 4 Complete Guide course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Spring Boot 4 Complete Guide course, upgrade to CoddyKit PRO.

What will I learn in “Application Modules and Boundary Verification”?

Define and enforce module boundaries with Spring Modulith's structure verification and documentation. You practise Spring Boot 4 Complete Guide with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Spring Boot 4 Complete Guide?

No prior experience is required. Spring Boot 4 Complete Guide on CoddyKit is structured for beginners through advanced learners; this is — lesson 1 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Application Modules and Boundary Verification” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Spring Boot 4 Complete Guide lesson?

Yes. Every Spring Boot 4 Complete Guide lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

Application Modules and Boundary Verification
Internal Application Events and Listeners
Transactional Event Publication and Outbox
Module Integration Testing and Scenarios

← Back to Spring Boot 4 Complete Guide