Java Backend Architect

Java Backend Architect

Overview

This skill provides knowledge, templates, and scripts for building production-grade Spring Boot backend systems following clean architecture principles. It covers project scaffolding, layered architecture, JWT authentication, REST API design, database integration, messaging, caching, containerization, and deployment.

When to Use This Skill

Use this skill when the user asks to:

• Scaffold or create a new Spring Boot microservice
• Design the architecture for a Java backend system
• Implement JWT authentication, REST APIs, or database access
• Set up Docker, Redis, Kafka, or production deployment
• Follow clean architecture / hexagonal architecture patterns

Quick Start

For rapid service scaffolding, use:

python scripts/scaffold_service.py <service-name> --package <base-package>

This generates a complete Spring Boot project with clean architecture layers, application.yml, Dockerfile, and docker-compose setup.

Core Capabilities

1. Clean Architecture & Project Structure

Follow the layered architecture defined in references/clean_architecture.md. The standard structure is:

<service-name>/
  src/main/java/<base-package>/
    domain/          # Enterprise business rules (entities, value objects, domain events)
    application/     # Application business rules (use cases, ports, DTOs)
    infrastructure/  # Adapters, persistence, messaging, external APIs
    interfaces/      # REST controllers, request/response models
    config/          # Spring configuration, security, beans
  src/main/resources/
    application.yml  # Base configuration
    db/migration/    # Flyway migration scripts
  Dockerfile
  docker-compose.yml
  pom.xml

Key principles:

• Domain layer has ZERO framework dependencies (no Spring annotations)
• Dependencies point INWARD (interfaces -> application -> domain)
• Infrastructure implements ports defined in the application layer

2. JWT Authentication

Implement JWT auth using Spring Security + spring-boot-starter-security + jjwt:

• config/SecurityConfig.java - Security filter chain configuration
• config/JwtAuthFilter.java - OncePerRequestFilter that validates JWT from Authorization header
• interfaces/AuthController.java - Login/register endpoints
• application/service/AuthService.java - Token generation and validation logic
• application/port/out/TokenRepository.java - Interface for token persistence (e.g., Redis-backed blacklist)

Token structure: Include sub (userId), roles, iat, exp. Use RSA key pair or HMAC secret from environment variables (never hardcoded).

3. REST API Design

Follow RESTful conventions:

• Plural nouns for resources: /api/v1/users, /api/v1/orders
• Standard HTTP methods: GET, POST, PUT, DELETE, PATCH
• Consistent error response envelope: { "status": int, "error": string, "message": string, "timestamp": instant }
• Pagination: ?page=0&size=20 with Sort parameter support
• Version prefix in URL path: /api/v1/...
• OpenAPI 3.0 documentation via springdoc-openapi

4. Database (MySQL + Flyway)

• Use Flyway for schema migrations in src/main/resources/db/migration/
• Naming: V{version}__{description}.sql (e.g., V1__create_users_table.sql)
• Use JPA/Hibernate or jOOQ for persistence
• Configure MySQL connection in application.yml with environment variables

5. Redis Integration

Use Spring Data Redis:

• Caching: @Cacheable, @CacheEvict with Redis-backed cache manager
• Session storage: spring.session.store-type=redis
• Token blacklisting: Store invalidated JWT tokens with TTL matching token expiry

6. Kafka Integration

Use Spring Kafka (spring-kafka):

• Define topics in config/KafkaTopicConfig.java
• Producers: KafkaTemplate<Key, Value> injected into application services
• Consumers: @KafkaListener in infrastructure layer
• Use Avro or JSON serialization with Schema Registry for production
• Configure retry, DLQ, and idempotent producer settings

7. Docker & Containerization

Each service includes:

• Dockerfile - Multi-stage build with Maven/Gradle, distroless JRE runtime
• docker-compose.yml - Service definition with MySQL, Redis, Kafka, and the application

Example Dockerfile approach:

FROM maven:3.9-eclipse-temurin-21 AS build
WORKDIR /app
COPY pom.xml .
RUN mvn dependency:go-offline
COPY src ./src
RUN mvn package -DskipTests

FROM eclipse-temurin:21-jre-alpine
WORKDIR /app
COPY --from=build /app/target/*.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]

8. Production Deployment

Refer to references/production_checklist.md for:

• Health checks and readiness probes
• Graceful shutdown configuration
• Centralized logging (ELK/Loki)
• Metrics with Micrometer + Prometheus
• Rate limiting and circuit breakers (Resilience4j)
• Secrets management (Vault or environment variables)
• Horizontal scaling considerations

Resources

scripts/scaffold_service.py

Python script that generates a complete Spring Boot microservice project skeleton with clean architecture. Run it to scaffold a new service.

references/clean_architecture.md

Detailed reference on the clean architecture package structure, dependency rules, and code examples for each layer.

references/production_checklist.md

Comprehensive checklist for taking a Spring Boot service to production: monitoring, security, resilience, and operations.