---

name: spring-boot description: > Spring Boot with WebFlux, R2DBC, and reactive patterns for Kotlin. Trigger: When working with controllers, services, repositories, or Spring configuration. allowed-tools: Read, Edit, Write, Glob, Grep, Bash metadata: author: cvix version: "2.0"

Spring Boot Skill

Conventions for Spring Boot backend development with WebFlux, R2DBC, and Kotlin.

Architecture Note: This skill covers the Infrastructure Layer of our Hexagonal Architecture. For domain models, use cases, and overall feature organization, see the hexagonal-architecture skill.

Layer Context

When to Use

• Creating REST controllers (HTTP adapters)
• Implementing repository adapters (R2DBC implementations)
• Configuring Spring Security, CORS, caching
• Wiring application services as Spring beans
• Writing integration tests with Testcontainers

Quick Reference

Controllers & HTTP Layer

Thin HTTP adapters that delegate to application handlers. No business logic.

• Controllers - @RestController, routing, OpenAPI annotations
• Request/Response DTOs - Jakarta validation, Schema annotations
• Swagger Standard - OpenAPI documentation conventions

Application Layer Wiring

Application services are framework-agnostic; Spring wires them via @Configuration.

• CQRS Handlers - Command/Query handlers as @Service beans

Persistence Layer

Repository adapters implementing domain ports with R2DBC.

• Repositories - Domain ports, Spring Data interfaces, adapters
• Entities & Mappers - @Table entities, mapper components

Cross-Cutting Concerns

• Error Handling - @ControllerAdvice, ProblemDetail (RFC 7807)
• Configuration - @ConfigurationProperties, Security, R2DBC
• WebFlux & Coroutines - Reactive patterns, never block

HTTP Status Codes

Application Profiles

Anti-Patterns

See WebFlux & Coroutines for reactive anti-patterns.

Commands

Copy# Run application
./gradlew bootRun

# Run with profile
SPRING_PROFILES_ACTIVE=dev ./gradlew bootRun

# Run tests
./gradlew test

# Integration tests only
./gradlew test -PincludeTags=integration

# Build JAR
./gradlew bootJar

Resources

Internal References

• Controllers - HTTP adapter patterns
• CQRS Handlers - Command/Query handler wiring
• Repositories - R2DBC repository adapters
• Entities & Mappers - Persistence entities
• Configuration - Spring configuration patterns
• Error Handling - Exception handling with ProblemDetail
• WebFlux & Coroutines - Reactive patterns
• Request/Response DTOs - API contracts
• Swagger Standard - OpenAPI documentation

Related Skills

• hexagonal-architecture - Domain, Application layers & feature organization
• kotlin - Kotlin conventions for all layers

External Documentation

• Spring WebFlux
• Spring Data R2DBC
• Kotlin Coroutines with Spring
• Problem Details RFC 7807