a-pavithraa Creating Spring Boot Projects
Purpose
Use this skill to create new Spring Boot 4 projects or define their structure before implementation. The skill adds value when the user needs an architecture decision, Spring Boot 4 feature selection, or the bundled templates in assets/.
Critical rules
- Never jump straight to implementation before assessing project complexity.
- Default to the simplest architecture that fits the domain.
- Treat Spring Boot 4 as the target. Default new projects to Java 25 (current LTS). Boot 4's official baseline is Java 17 — accept Java 21 (previous LTS) or Java 17 when the user asks for them. Java 26 is the newest feature release (GA 2026-03-17) but is non-LTS; only pick it if the project tracks non-LTS Java.
- Read the reference files before choosing a higher-complexity architecture or optional framework feature.
- Reuse the templates in
assets/instead of rewriting the same scaffolding from scratch.
Workflow
Step 1: Assess project shape
Collect the project constraints first:
- Domain complexity: simple CRUD, moderate workflow, or rich domain rules.
- Team size: 1-3, 3-10, or 10+.
- Expected lifespan: months, 1-2 years, or 5+ years.
- Type-safety needs: basic validation or strong value-object-heavy modeling.
- Bounded contexts: single domain or multiple feature areas.
- Persistence and infrastructure needs: database choice, migration tool, local development setup.
Step 2: Choose the architecture
Use this matrix as the default decision aid. If the choice is not obvious, read references/architecture-guide.md before proceeding.
| Pattern | Use when | Complexity |
|---|---|---|
layered |
CRUD services, prototypes, MVPs | Low |
package-by-module |
3-5 distinct features with moderate growth | Low-Medium |
modular-monolith |
Module boundaries matter and Spring Modulith is justified | Medium |
tomato |
Rich domain modeling, value objects, stronger type safety | Medium-High |
ddd-hexagonal |
Complex domains, CQRS, strong infrastructure isolation | High |
tomatois a value-object-heavy modular monolith: JPA entities embed VOs, validation lives in VO constructors, and Spring converters bind VOs at the request boundary. Seereferences/architecture-guide.mdfor the full definition.
Step 3: Define the initial Boot 4 setup
Use Spring Initializr and capture the baseline:
- Project: Maven or Gradle
- Language: Java
- Spring Boot: 4.1.x
- Java: 25 (recommended — current LTS). Boot 4's minimum is Java 17; use 21 for the previous LTS, or 17 for stricter compatibility. Java 26 (GA 2026-03-17) is the latest feature release but is non-LTS.
Baseline dependencies for most projects:
- Spring Web MVC
- Validation
- Spring Data JPA if persistence is required
- Flyway or Liquibase
- database driver
- Spring Boot Actuator
- Testcontainers for integration tests
Optional dependencies based on architecture or features:
- Spring Modulith for modular monolith or tomato designs
- ArchUnit for stronger architecture enforcement
- Additional Spring Boot 4 features only when the use case needs them
Read references/spring-boot-4-features.md before selecting:
- RestTestClient
- HTTP Service Clients
- API versioning
- JSpecify null-safety
- resilience features
Step 4: Apply the matching assets
Use the bundled templates from assets/ and replace placeholders only after the package and module names are settled.
Placeholder convention
Every template uses {{TOKEN}} placeholders. Resolve all of them before applying — templates do not compile until every placeholder is replaced. The full set used across assets/:
| Placeholder | Replace with | Example |
|---|---|---|
{{PACKAGE}} |
Base Java package | com.acme.shop |
{{MODULE}} |
Feature/module name (lowercase) | orders |
{{NAME}} |
Domain type name (PascalCase) | Order, ProductSKU |
{{TYPE}} |
Wrapped scalar type inside a value object | String, Long, BigDecimal |
{{FIELD}} |
Record field name (camelCase) | code, amount |
{{TABLE_NAME}} |
Database table name (used in JPA @Table) |
orders |
{{TABLE}} |
Same meaning as {{TABLE_NAME}} — legacy variant kept only in flyway-migration.sql |
orders |
{{PROJECT_NAME}} |
Project artifactId / docker prefix (used only in docker-compose.yml) |
shop-api |
{{name}} |
HTTP service group identifier — not a lowercase variant of {{NAME}}. Appears only in commented @ImportHttpServices(group = "...") examples. |
orders |
If a template uses a placeholder not listed here, treat it as a typo and confirm the intended value before applying.
Core project templates:
assets/controller.javaassets/repository.javaassets/base-entity.javaassets/rich-entity.javaassets/value-object.javaassets/spring-converter.javaassets/service-cqrs.javaassets/exception-handler.javaassets/flyway-migration.sqlassets/docker-compose.yml
Boot 4 and modularity templates:
assets/http-service-client.javaassets/api-versioning-config.javaassets/resttestclient-test.javaassets/package-info-jspecify.javaassets/modularity-test.javaassets/resilience-service.javaassets/pom-additions.xmlassets/testcontainers-test.java
Step 5: Fill in architecture-specific pieces
Read references/architecture-guide.md for package structure and apply the matching templates:
layered: keep modules simple and avoid premature DDD abstractionspackage-by-module: group by feature and keep shared code minimalmodular-monolith: add Modulith verification and explicit module APIstomato: add value objects and rich domain entities where they protect important invariantsddd-hexagonal: separate application, domain, and infrastructure explicitly
Step 6: Hand off specialized concerns when needed
- Use
spring-data-jpawhen the user needs deeper query, projection, repository, or relationship decisions. - Use
springboot-migrationfor upgrades of existing applications rather than new-project setup.
Reference loading guide
- Package structures, anti-patterns, and upgrade paths:
references/architecture-guide.md - Spring Boot 4 feature-specific guidance:
references/spring-boot-4-features.md
Output format
When the user asks for a plan or scaffold recommendation, return:
## Recommended architecture
- Pattern:
- Why:
## Initial setup
- Build tool:
- Java version:
- Spring Boot version:
- Core dependencies:
## Assets to apply
- `assets/...`
## Next implementation steps
1. ...
2. ...
3. ...
When not to use this skill
- Migrating an existing Boot project
- Deep repository and query tuning without broader project-creation work
- Generic Spring Boot feature Q&A with no need for the bundled templates