Java Service Architecture and Failure Diagnosis
Design and debug Spring Boot Java services with concrete fixes for reactive stalls, JPA queries, JWT security, and async work.
Before & after
Same prompt, same agent — the only difference is the skill.
Spring Boot is pretty flexible, so there are a few ways you could approach this. WebFlux gives you reactive programming, which is good for handling a lot of concurrent connections. For OAuth2, you'll want to use Spring Security. JWT is commonly used for stateless authentication. You'd need to set up a SecurityFilterChain or WebSecurityConfig class to handle the JWT validation. For the WebFlux endpoint, you'd create a RestController and use Mono or Flux for the response types, depending on whether you're returning a single item or a stream. You'll probably want to use Spring Data R2DBC if you need database access with WebFlux. Testing is important — make sure you test both the authentication and the business logic. There are examples in the Spring Boot documentation, and there are a few different libraries you could use for JWT handling.
SPRING BOOT 3.x WEBFLUX + OAUTH2/JWT ENDPOINT
SECURITY CONFIG (SecurityConfig.java)
→ @Configuration class with @EnableReactiveMethodSecurity
→ SecurityWebFilterChain bean: permit OPTIONS + /login; require JWT on all others
→ JwtDecoder bean: Decode RS256 tokens from issuer (Auth0, Okta, etc.)
→ ReactiveAuthenticationManager: Extract issuer claim ("iss") + scope validation
JWT VALIDATION FILTER
→ Extract Bearer token from Authorization header
→ Decode + verify signature + check expiration
→ Build SecurityContext with authorities (scopes as roles)
→ Return Mono<Void> or error if invalid
RESTFUL ENDPOINT (ApiController.java)
@PostMapping("/api/data")
public Mono<ResponseEntity<DataResponse>> createData(
@RequestBody DataRequest req,
@AuthenticationPrincipal Mono<JwtAuthenticationToken> auth
) {
return auth
.switchIfEmpty(Mono.error(new UnauthorizedException()))
.flatMap(token -> validateScope(token, "write:data"))
.flatMap(token -> repository.save(req).map(ResponseEntity::ok))
.onErrorResume(InvalidTokenException.class, e -> Mono.just(ResponseEntity.status(401).build()));
}
TESTING (WebTestClient)
→ Test 1: Missing token → 401 Unauthorized
→ Test 2: Invalid signature → 401 Unauthorized
→ Test 3: Expired token → 401 Unauthorized
→ Test 4: Valid token + correct scope → 200 + response body
→ Test 5: Valid token + insufficient scope → 403 Forbidden
DEPLOYMENT NOTES
→ Token secret/JWK URL set via environment (not hardcoded)
→ CORS headers configured (if frontend is cross-origin)
→ Actuator endpoints secured (only /health + /ready exposed)
COMMON TRAP: Using Mono.fromCallable() on blocking JWT library → kills reactive benefits. Use reactive-native JWT decoder instead.About this skill
Your reactive endpoint hangs under load, a small JPA response executes hundreds of queries, or JWT authentication works while authorization fails. This skill traces those failures across Java execution, transaction, and security boundaries, then produces a focused fix with verification steps.
What it does
- Chooses between Spring MVC, WebFlux, and bounded blocking bridges using the actual workload and dependencies.
- Diagnoses reactive stalls by tracing subscription, blocking calls, scheduler placement, cancellation, and resource saturation.
- Fixes JPA query amplification without breaking pagination, transaction boundaries, or response serialization.
- Reviews Spring Security filter chains, JWT issuer and audience validation, and authority mapping.
- Designs async and service-to-service flows around deadlines, capacity, idempotency, and failure recovery.
- Turns architecture proposals into concrete boundaries, tradeoffs, implementation changes, and focused checks.
What you get
A diagnosis or architecture decision sized to your request, with an actionable patch or implementation plan. Each recommendation identifies the mechanism it fixes, its tradeoff, and the evidence needed to verify it.
Best for
Java backend developers maintaining Spring Boot 3.x services, especially applications combining JPA, WebFlux, OAuth2 resource servers, and asynchronous processing.
SKILL.md preview
---
name: java-service-architecture-and-failure-diagnosis
description: Design and debug enterprise Java services, especially Spring Boot 3.x applications, by tracing execution, transaction, persistence, and security boundaries before proposing concrete changes and verification. Use when the user says "my WebFlux endpoint keeps hanging", "fix these N+1 queries", "review our Java service architecture", "JWT works locally but returns 401 in production", "our async job loses updates", "should this service be reactive", or "debug this Spring Boot service".
---
# Java Service Architecture and Failure Diagnosis
… (sign up to view the full skill)More development skills
View all Development skills →SQL Query Optimization and Schema Review
Get SQL rewrites, evidence-based index recommendations, schema reviews, and dialect migrations with validation steps.
C# API and Blazor Implementation
Build and fix C# APIs and Blazor components with safe EF Core queries, cancellation, and focused tests.
Rust Code Implementation and Debugging
Get Rust code and targeted fixes for ownership, lifetimes, traits, Tokio concurrency, errors, and unsafe boundaries.
Type-Safe PHP Applications and APIs
Build and repair typed PHP applications with Laravel or Symfony, safe database changes, and targeted tests.