Skip to main content
skill CX Codex

spring-boot-modulith — Claude Code skill: modules and setup

spring-boot-modulith is a Claude Code skill that structures Spring Boot apps as bounded modules connected through events. It supports modular monolith design and module boundary checks.

MIT 1 installs ★ 23 updated 2026-10-16

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add joaquimscosta/arkhe-claude-plugins --skill spring-boot-modulith -a claude-code
Open on GitHub

What spring-boot-modulith does

The skill maps DDD bounded contexts to application packages. Types in a module's base package form its public API; placing implementation classes under internal keeps them out of other modules. Its guidance targets Spring Boot 4 with Spring Modulith 2.0. Package layout defines the boundaries.

For cross-module communication, it recommends events handled with @ApplicationModuleListener instead of injecting another module's beans. The material covers @ApplicationModule configuration, event publishing, ApplicationModules.verify() boundary checks, and sending events to Kafka or AMQP with @Externalized. A JDBC event log provides at-least-once delivery.

Included patterns cover Java and Kotlin event handlers, module verification with PlantUML generation, and Scenario API tests. Direct bean injection across modules cuts across the intended boundaries; use events or a module's exposed API instead.

What it helps with

  • map DDD contexts to application packages
  • keep implementation types private to each module
  • connect modules with @ApplicationModuleListener
  • check module boundaries with ApplicationModules.verify()
  • externalize events to Kafka or AMQP

Example prompts for the agent

  • Organize this Spring Boot app into modules that match its DDD bounded contexts.
  • Show how to handle an event from another module with @ApplicationModuleListener.
  • Add a test that checks module boundaries using ApplicationModules.verify().

How to install spring-boot-modulith

1Skills CLI (Vercel)

npx skills add joaquimscosta/arkhe-claude-plugins --skill spring-boot-modulith -a claude-code

2Manually: put the files in place

~/.claude/skills/spring-boot-modulith/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/spring-boot-modulith/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about spring-boot-modulith

How do I install spring-boot-modulith in Claude Code?

Run npx skills add joaquimscosta/arkhe-claude-plugins --skill spring-boot-modulith -a claude-code. The skill file is placed at ~/.claude/skills/spring-boot-modulith/SKILL.md.

What does spring-boot-modulith do?

It guides you through organizing a Spring Boot 4 modular monolith, defining package-based boundaries, communicating through events, and checking module dependencies.

How should modules communicate with this skill?

Use events with @ApplicationModuleListener or expose a module API. Directly injecting beans across module boundaries is listed as an anti-pattern.

Source text

SKILL.md · MIT
---
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, externalizing events to Kafka/AMQP, building a modular monolith, defining module dependencies, managing inter-module events, or organizing DDD modules as packages. Covers package-based module boundaries, named interfaces, event publication, and Scenario API testing. For architecture decisions, see domain-driven-design skill.
spring-boot-version: "4.0"
---

# 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](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

- **Examples**: See [EXAMPLES.md](EXAMPLES.md) for complete working code examples
- **Troubleshooting**: See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for common issues and Boot 4 migration
- **Workflow**: See [WORKFLOW.md](WORKFLOW.md) for detailed step-by-step Modulith setup
- **Module Structure**: See [references/MODULE-STRUCTURE.md](references/MODULE-STRUCTURE.md) for package conventions, named interfaces, dependency rules
- **Event Patterns**: See [references/EVENTS.md](references/EVENTS.md) for publishing, handling, externalization, testing with Scenario API

## Related Skills

| Need | Skill |
|------|-------|
| DDD concepts | `domain-driven-design` |
| Data layer per module | `spring-boot-data-ddd` |
| Module event testing | `spring-boot-testing` |
| REST APIs for modules | `spring-boot-web-api` |

## 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

1. **One module = one bounded context** — Mirror DDD boundaries
2. **Events are the integration mechanism** — Not direct method calls
3. **Verify in CI** — `ApplicationModules.verify()` catches boundary violations
4. **Reference by ID** — Never direct object references across modules
5. **Transaction per module** — `@ApplicationModuleListener` ensures isolation

© joaquimscosta · MIT · joaquimscosta/arkhe-claude-plugins

Similar skills

All skills for Backend and APIs →
305-frameworks-spring-boot-modulith Juan Antonio Breña Moral 305-frameworks-spring-boot-modulith guides Spring Modulith work in Spring Boot modular monoliths, from module boundaries to events and tests. Use it when reviewing or reshaping the architecture. CX Codex +1 245installs spring-boot-event-driven-patterns giuseppe-trisciuoglio spring-boot-event-driven-patterns is a Claude Code skill for Spring Boot 3.x that replaces synchronous service calls with events using domain events, Kafka and the transactional outbox. CX Codex +1 4,000installs spring-boot-crud-patterns giuseppe-trisciuoglio spring-boot-crud-patterns — a skill that builds the whole CRUD layer for Spring Boot 3 services: aggregates, JPA repositories, DTOs and REST controllers in a feature-based layout. CX Codex +1 4,100installs create-spring-boot-java-project official github create-spring-boot-java-project scaffolds a Spring Boot Java application via start.spring.io with preset defaults for databases, testing, and Docker. Triggers when asked to bootstrap a new Java service. CX Codex +1 9,516installs spring-boot-engineer https://github.com/Jeffallan spring-boot-engineer generates Spring Boot 3.x code, JPA repositories, REST controllers, and Spring Security 6 configurations. Useful when writing Java microservices and reactive endpoints. CX Codex +1 8,900installs spring-boot-testing official github This skill chooses a Spring Boot testing approach, from JUnit and test slices to Testcontainers integration. It accounts for differences between Spring Boot 3 and 4. CX Codex +1 2,000installs

From the same set2

Project sponsors

Companies that keep this analytics open