Spring Modulith Documentation

Spring Modulith introduces the concept of application modules to help align code structure with the domain.

By default, an application module consists of:

1. An API package: These are packages located directly under the application's main package (e.g., example.inventory and example.order). Types in these packages are considered part of the module's public interface.
2. Internal packages: These are nested sub-packages (e.g., example.order.internal). Types within these packages are considered internal and are inaccessible to code residing in other modules.

This allows you to use standard Java visibility modifiers for simple cases, but Spring Modulith provides the enforcement layer to prevent illegal access to nested internal packages that would otherwise be accessible in plain Java.

To maintain high decoupling between application modules, use Spring's ApplicationEventPublisher instead of direct bean dependencies. This prevents 'functional gravity' where a service attracts too many dependencies from other modules, making it harder to test and maintain.

Instead of injecting a service from another module, publish a domain event once the state transition in the primary aggregate is complete.

@Service
@RequiredArgsConstructor
public class OrderManagement {

  private final ApplicationEventPublisher events;
  private final OrderInternal dependency;

  @Transactional
  public void complete(Order order) {
    // State transition on the order aggregate go here
    events.publishEvent(new OrderCompleted(order.getId()));
  }
}

The externalization process follows this lifecycle:

1. Bootstrap: On application startup, the spring-modulith-events-kafka module registers an ApplicationModuleListener specifically for externalization.
2. Event Publication: When a business method publishes an event (e.g., OrderCompleted) that is annotated with @Externalized, the infrastructure detects it.
3. Registry Tracking: The Event Publication Registry creates a record to track the event's processing.
4. Asynchronous Externalization: An asynchronous task (e.g., task-1) is triggered to handle the externalization via the registered ApplicationModuleListener.
5. Kafka Dispatch: The listener invokes the Kafka operations to send the message.
6. Completion: Once the message is successfully sent, the Event Publication Registry marks the publication as completed.

The Documenter abstraction is used to generate documentation snippets from an ApplicationModules instance. It can produce several types of documentation for inclusion in Asciidoc files:

• C4 and UML component diagrams: Visual representations of relationships between application modules.
• Application Module Canvas: A tabular overview of a module's contents, including Spring beans, aggregate roots, published/listened events, and configuration properties.
• Aggregating Document: An all-docs.adoc file that links all existing diagrams and canvases together.

To use it, you typically pass an ApplicationModules instance (obtained via ApplicationModules.of(Application.class)) to the Documenter constructor.

ApplicationModules modules = ApplicationModules.of(Application.class);
new Documenter(modules).writeModulesAsPlantUml();

Spring Modulith (2.0+) supports executing module-specific Flyway migrations. Modules should define migrations for their own persistent data only, executed in the order of the module dependency tree.

To use this, activate the spring.modulith.runtime.flyway-enabled configuration property.

Migration Organization:

• Root Migrations: Place in db/migration/__root. These use the default version tracking table.
• Module Migrations: Place in db/migration/$moduleIdentifier. These use a specific tracking table named flyway_schema_history_$moduleIdentifier and are set to a baseline version of 0.
• Wildcards: Migration locations ending in a wildcard are not customized.

Important: Version numbers in migration scripts are scoped to the application module; do not use global ordering across modules.

Spring Modulith provides a mechanism for reliable domain events by ensuring that events published within a transaction are not lost if the application fails during the notification of @TransactionalEventListeners.

Instead of relying solely on Spring's in-memory ApplicationEventPublisher, this system uses a transactional datastore to record the publication of events. If an event listener fails or the application crashes before a listener completes, the event remains in the EventPublicationRegistry. These pending events can then be re-published upon application restart or via a scheduled process, ensuring eventual consistency.

The Event Publication Registry hooks into Spring's event mechanism to ensure reliability. When an event is published, the registry writes an entry into an event publication log as part of the original business transaction.

Transactional event listeners (including those annotated with @ApplicationModuleListener) are wrapped in an aspect that marks the log entry as COMPLETED upon successful execution. If the listener fails, the log entry remains, allowing for retry mechanisms.

By default, all listeners annotated with @TransactionalEventListener are tracked. You can customize this via the spring.modulith.events.registry-trigger-annotation property.

The @ApplicationModuleTest annotation allows you to control which modules are included in the Spring ApplicationContext during the test run using different bootstrap modes:

• STANDALONE (default): Runs only the current module.
• DIRECT_DEPENDENCIES: Runs the current module and all modules it directly depends on.
• ALL_DEPENDENCIES: Runs the current module and the entire tree of all depended-on modules.