| name | spring-boot-modulith |
| description | Spring Modulith 2.0 implementation for bounded contexts in Spring Boot 4. Use when structuring application modules, implementing @ApplicationModuleListener for event-driven communication, testing with Scenario API, enforcing module boundaries, or externalizing events to Kafka/AMQP. For modular monolith architecture decisions, see the domain-driven-design skill. |
Spring Modulith for Bounded Contexts
Implements DDD bounded contexts as application modules with enforced boundaries and event-driven communication.
Core Concepts
| Concept | Description |
|---|
| Application Module | Package-based boundary = bounded context |
| Module API | Types in base package (public) |
| Internal | Types in sub-packages (encapsulated) |
| Events | Cross-module communication mechanism |
Module Structure
src/main/java/
├── com.example/
│ └── Application.java ← @SpringBootApplication
├── com.example.order/ ← Module: order
│ ├── OrderService.java ← Public API
│ ├── OrderCreated.java ← Public event
│ ├── package-info.java ← @ApplicationModule config
│ └── internal/ ← Encapsulated
│ ├── OrderRepository.java
│ └── OrderEntity.java
├── com.example.inventory/ ← Module: inventory
│ ├── InventoryService.java
│ └── internal/
└── com.example.shipping/ ← Module: shipping
Types in com.example.order = public API
Types in com.example.order.internal = hidden from other modules
Quick Patterns
See EXAMPLES.md for complete working examples including:
- Module Configuration with @ApplicationModule
- Event Publishing with domain event records
- Event Handling with @ApplicationModuleListener (Java + Kotlin)
- Module Verification Test with PlantUML generation
- Event Externalization for Kafka/AMQP
Spring Boot 4 / Modulith 2.0 Specifics
- @ApplicationModuleListener combines
@Async + @Transactional(REQUIRES_NEW) + @TransactionalEventListener(AFTER_COMMIT)
- Event Externalization with
@Externalized annotation for Kafka/AMQP
- JDBC event log ensures at-least-once delivery
Detailed References
Anti-Pattern Checklist
| Anti-Pattern | Fix |
|---|
| Direct bean injection across modules | Use events or expose API |
| Synchronous cross-module calls | Use @ApplicationModuleListener |
| Module dependencies not declared | Add allowedDependencies in @ApplicationModule |
| Missing verification test | Add ApplicationModules.verify() test |
| Internal types in public API | Move to .internal sub-package |
| Events without data | Include all data handlers need |
Critical Reminders
- One module = one bounded context — Mirror DDD boundaries
- Events are the integration mechanism — Not direct method calls
- Verify in CI —
ApplicationModules.verify() catches boundary violations
- Reference by ID — Never direct object references across modules
- Transaction per module —
@ApplicationModuleListener ensures isolation
