Spring Modulith Verifier Skill
Use a domain-driven, modular layout: organize packages by business modules, not by technical layers.
Recommended Example Package Structure
dev.sivalabs.projectname/
├── Application # Main Spring Boot entrypoint class
├── shared/ # Cross-cutting concerns
│ ├── package-info.java
├── users/ # Users module (bounded context)
│ ├── config/ # Users module-specific config
│ ├── domain/ # Domain logic
│ │ ├── models/ # Domain models
│ │ │ ├── package-info.java
│ │ ├── exceptions/ # Domain custom Exception classes
│ │ │ ├── package-info.java
│ │ ├── {entities, repositories, mappers, services}
│ ├── api/ # REST API layer
│ │ ├── {controllers, DTOs} # REST controllers, Request, Response payload DTOs
│ └── UsersAPI.java # Module's public API (facade)
│
├── catalog/ # Catalog module
├── orders/ # Orders module
└── config/ # Global Configuration
└── WebMvcConfig.java
└── SecurityConfig.java
└── WebSecurityConfig.java
└── GlobalExceptionHandler.java
Explanation of the above package structure:
Application.java: The main Spring Boot entry point class annotated with @SpringBootApplication. Contains the main() method that bootstraps the application.
shared/: Contains cross-cutting concerns and utilities shared across multiple modules (e.g., common utilities, shared DTOs, base classes, custom annotations).
{module}/ (e.g., users/, catalog/, orders/): Each business module represents a bounded context and contains:
config/: Module-specific configuration classes annotated with @Configuration for beans, properties, or third-party integrations relevant only to this module.
domain/: Core business logic layer containing:
- models/: Domain model classes (Command, Query objects, Enums, Value Objects, Result objects, etc) representing business concepts (not JPA entities). These are pure Java objects that encapsulate business rules.
- exceptions/: Domain specific custom Exception classes.
- entities: JPA entity classes annotated with
@Entity that map to database tables. These should not be public to prevent direct instantiation and ensure encapsulation.
- repositories: Spring Data JPA repository interfaces extending
JpaRepository or CrudRepository for data access. These should not be public.
- mappers: Mapper classes/interfaces (e.g., MapStruct mappers) for converting between entities, domain models, and DTOs. These should not be
public.
- services: Service classes annotated with
@Service containing business logic, converting beans using mappers, transaction management, and orchestration of repository calls.
api/: REST API layer containing:
- controllers: REST controller classes annotated with
@RestController that handle HTTP requests, validate input, and delegate to services.
- DTOs: Data Transfer Objects including request payloads (data coming from clients) and response payloads (data sent to clients).
{Module}API.java: A facade class that serves as the module's public API, delegating calls to services, exposing only what other modules should access while hiding internal implementation details.
config/: Global application-wide configuration classes including:
- WebMvcConfig.java: MVC configuration (CORS, interceptors, formatters).
- SecurityConfig.java: Spring Security configuration for authentication and authorization.
- GlobalExceptionHandler.java: Centralized exception handling using
@RestControllerAdvice for consistent error responses.
Visibility Modifiers
Default to minimum necessary visibility. Only expose what other modules or layers genuinely need.
| Component |
Class |
Constructor |
Methods |
| Controller |
package-private |
package-private |
package-private |
| Service |
public |
package-private |
public |
| Repository |
package-private (interface) |
— |
— |
| Entity |
package-private |
protected |
public |
| DTO / record |
public or package-private |
— |
— |
| Module API facade |
public |
package-private |
public |
| Request/Response records |
package-private |
— |
— |
| Config/Exception handler |
package-private |
— |
— |
Naming Conventions
| Type |
Convention |
Example |
| Entities |
*Entity |
UserEntity, AddressEntity |
| Value Objects |
Domain name (record) |
Email, UserCode, UserId |
| Commands |
*Cmd |
CreateUserCmd, UpdateAddressCmd |
| Command Response |
*Result |
LoginResult, RegistrationResult |
| DTOs |
*Dto |
UserDto, AddressDto |
| HTTP Request |
*Request |
CreateUserRequest, CreateAddressRequest |
| HTTP Response |
*Response |
CreateUserResponse, CreateAddressResponse |
| Repositories |
*Repository |
UserRepository, AddressBookRepository |
| Services |
*Service |
UserService, AddressBookService |
| Domain Exceptions |
*Exception |
InvalidUserCreationException, UserCancellationException |
| Module API |
*API |
UsersAPI |
1---
2name: spring-modulith-verifier
3description: >
4 Verifies whether code follows Spring Modulith code structure or not.
5 Show list of violations along with recommendations on how to fix them.
6 Use this skill:
7 * When reviewing Spring Boot applications which uses Spring Modulith
8 * When verifying whether Spring Boot application code follows Spring Modulith package structure
9metadata:
10 source: https://skillmd.com/skills/gabrielmoreira/spring-modulith-verifier
11---
12
13# Spring Modulith Verifier Skill
14
15Use a **domain-driven, modular layout**: organize packages by **business modules**, not by technical layers.
16
17### Recommended Example Package Structure
18
19```
20dev.sivalabs.projectname/
21├── Application # Main Spring Boot entrypoint class
22├── shared/ # Cross-cutting concerns
23│ ├── package-info.java
24├── users/ # Users module (bounded context)
25│ ├── config/ # Users module-specific config
26│ ├── domain/ # Domain logic
27│ │ ├── models/ # Domain models
28│ │ │ ├── package-info.java
29│ │ ├── exceptions/ # Domain custom Exception classes
30│ │ │ ├── package-info.java
31│ │ ├── {entities, repositories, mappers, services}
32│ ├── api/ # REST API layer
33│ │ ├── {controllers, DTOs} # REST controllers, Request, Response payload DTOs
34│ └── UsersAPI.java # Module's public API (facade)
35│
36├── catalog/ # Catalog module
37├── orders/ # Orders module
38└── config/ # Global Configuration
39 └── WebMvcConfig.java
40 └── SecurityConfig.java
41 └── WebSecurityConfig.java
42 └── GlobalExceptionHandler.java
43```
44
45Explanation of the above package structure:
46
47- **Application.java**: The main Spring Boot entry point class annotated with `@SpringBootApplication`. Contains the `main()` method that bootstraps the application.
48
49- **shared/**: Contains cross-cutting concerns and utilities shared across multiple modules (e.g., common utilities, shared DTOs, base classes, custom annotations).
50
51- **{module}/** (e.g., users/, catalog/, orders/): Each business module represents a bounded context and contains:
52
53 - **config/**: Module-specific configuration classes annotated with `@Configuration` for beans, properties, or third-party integrations relevant only to this module.
54
55 - **domain/**: Core business logic layer containing:
56 - **models/**: Domain model classes (Command, Query objects, Enums, Value Objects, Result objects, etc) representing business concepts (not JPA entities). These are pure Java objects that encapsulate business rules.
57 - **exceptions/**: Domain specific custom Exception classes.
58 - **entities**: JPA entity classes annotated with `@Entity` that map to database tables. These should not be `public` to prevent direct instantiation and ensure encapsulation.
59 - **repositories**: Spring Data JPA repository interfaces extending `JpaRepository` or `CrudRepository` for data access. These should not be `public`.
60 - **mappers**: Mapper classes/interfaces (e.g., MapStruct mappers) for converting between entities, domain models, and DTOs. These should not be `public`.
61 - **services**: Service classes annotated with `@Service` containing business logic, converting beans using mappers, transaction management, and orchestration of repository calls.
62
63 - **api/**: REST API layer containing:
64 - **controllers**: REST controller classes annotated with `@RestController` that handle HTTP requests, validate input, and delegate to services.
65 - **DTOs**: Data Transfer Objects including request payloads (data coming from clients) and response payloads (data sent to clients).
66
67 - **{Module}API.java**: A facade class that serves as the module's public API, delegating calls to services, exposing only what other modules should access while hiding internal implementation details.
68
69- **config/**: Global application-wide configuration classes including:
70 - **WebMvcConfig.java**: MVC configuration (CORS, interceptors, formatters).
71 - **SecurityConfig.java**: Spring Security configuration for authentication and authorization.
72 - **GlobalExceptionHandler.java**: Centralized exception handling using `@RestControllerAdvice` for consistent error responses.
73
74### Visibility Modifiers
75
76Default to **minimum necessary visibility**. Only expose what other modules or layers genuinely need.
77
78| Component | Class | Constructor | Methods |
79|--------------------------|-----------------------------|-----------------|-----------------|
80| Controller | package-private | package-private | package-private |
81| Service | `public` | package-private | `public` |
82| Repository | package-private (interface) | — | — |
83| Entity | package-private | protected | `public` |
84| DTO / record | `public` or package-private | — | — |
85| Module API facade | `public` | package-private | `public` |
86| Request/Response records | package-private | — | — |
87| Config/Exception handler | package-private | — | — |
88
89
90### Naming Conventions
91
92| Type | Convention | Example |
93|-----------------------|----------------------|-------------------------------------------------------------|
94| **Entities** | `*Entity` | `UserEntity`, `AddressEntity` |
95| **Value Objects** | Domain name (record) | `Email`, `UserCode`, `UserId` |
96| **Commands** | `*Cmd` | `CreateUserCmd`, `UpdateAddressCmd` |
97| **Command Response** | `*Result` | `LoginResult`, `RegistrationResult` |
98| **DTOs** | `*Dto` | `UserDto`, `AddressDto` |
99| **HTTP Request** | `*Request` | `CreateUserRequest`, `CreateAddressRequest` |
100| **HTTP Response** | `*Response` | `CreateUserResponse`, `CreateAddressResponse` |
101| **Repositories** | `*Repository` | `UserRepository`, `AddressBookRepository` |
102| **Services** | `*Service` | `UserService`, `AddressBookService` |
103| **Domain Exceptions** | `*Exception` | `InvalidUserCreationException`, `UserCancellationException` |
104| **Module API** | `*API` | `UsersAPI` |