Creating Spring Boot Projects

Critical Rules

NEVER jump to implementation. ALWAYS assess complexity first.

MANDATORY versions: Java 25 + Spring Boot 4.0.x (latest stable) Platform baseline: Spring Framework 7, Jakarta EE 11 (Servlet 6.1); Java 17+ required.

Workflow

Step 1: Assess Complexity

Ask user:

1. •Domain Complexity - Simple CRUD or complex business rules?
2. •Team Size - 1-3, 3-10, or 10+?
3. •Lifespan - Months, 1-2 years, or 5+ years?
4. •Type Safety - Basic validation or strong typing needed?
5. •Bounded Contexts - Single domain or multiple subdomains?

Step 2: Choose Architecture

For detailed criteria, package structures, and naming conventions: See architecture-guide.md

Step 3: Create Project

Use Spring Initializr: https://start.spring.io

Required configuration:

• •Project: Maven or Gradle (Gradle 9 supported)
• •Language: Java
• •Spring Boot: 4.0.x (latest stable)
• •Java: 25

Core dependencies:

• •Spring Web MVC (spring-boot-starter-webmvc)
• •Spring Data JPA
• •Validation
• •Flyway (spring-boot-starter-flyway) or Liquibase (spring-boot-starter-liquibase)
• •PostgreSQL/MySQL Driver
• •Testcontainers
• •Spring Boot Actuator

Starter conventions (Spring Boot 4 modularization):

• •Prefer spring-boot-starter-<technology> and matching spring-boot-starter-<technology>-test
• •Avoid raw third-party deps when a Boot starter exists (for example Flyway/Liquibase)

Additional dependencies:

• •Spring Modulith - for Modular Monolith/Tomato
• •ArchUnit - for DDD+Hexagonal

Spring Boot 4 features: RestTestClient, HTTP Service Clients, API Versioning, modularization, JSpecify null-safety improvements, OpenTelemetry starter, Kotlin serialization, JmsClient, TaskDecorator composition

For detailed Spring Boot 4 feature documentation: See spring-boot-4-features.md

Step 4: Implement Pattern

Use templates from assets/ directory. All templates use placeholders:

• •{{PACKAGE}} → com.example
• •{{MODULE}} → products
• •{{NAME}} → Product

Core templates:

• •value-object.java - Type-safe Value Objects
• •rich-entity.java - Entities with behavior
• •repository.java - @Query examples
• •service-cqrs.java - Write/read services
• •controller.java - REST controllers
• •spring-converter.java - @PathVariable binding
• •modularity-test.java - Spring Modulith tests
• •flyway-migration.sql - Database migrations
• •exception-handler.java - ProblemDetail errors

Spring Boot 4 templates:

• •http-service-client.java - @HttpExchange clients
• •api-versioning-config.java - API versioning
• •resttestclient-test.java - Modern testing
• •package-info-jspecify.java - Null-safety
• •resilience-service.java - Resiliency example (external reference)

Data access: For complex queries, DTO projections, performance optimization, use the spring-data-jpa skill.

Step 5: Infrastructure Setup

Always include:

• •Flyway/Liquibase migrations
• •Testcontainers integration tests
• •Docker Compose for local development
• •Swagger/OpenAPI documentation
• •ProblemDetail error handling
• •JSpecify null-safety

Optional (based on requirements):

• •API versioning
• •HTTP Service Clients
• •OpenAPI documentation (third-party, e.g., Springdoc)

For detailed infrastructure patterns: See pom-additions.xml in assets/

Quick Reference

Package structures: architecture-guide.md Naming conventions: architecture-guide.md Anti-patterns: architecture-guide.md Upgrade paths: architecture-guide.md Spring Boot 4 features: spring-boot-4-features.md

Key Principle

Start simple. Upgrade when complexity demands it.

External References (Non-Official)

• •https://github.com/sivaprasadreddy/spring-boot-4-features
• •https://github.com/sivaprasadreddy/spring-modular-monolith