Tech Stack Configuration Skill

This skill provides comprehensive configuration context for the hello-spring-boot project. All new features should follow this established tech stack and architectural patterns.

---

Technology Stack

Core Framework:

• Spring Boot: 3.4.4 (current version)
• Java: 17 (LTS, required)
• Gradle: 8.13
• Build Tool: Gradle with Spring Boot plugin

Database Layer:

• Database: PostgreSQL 15 (Docker container on port 5432)
• Database Name: hello-spring-db
• Username: postgres
• Password: datpt
• Connection Pool: HikariCP (max 10 connections)
• ORM: Spring Data JPA with Hibernate
• Migration Tool: Flyway for database version control
• JDBC Driver: PostgreSQL 42.x

Testing:

• Framework: JUnit 5
• Mocking: Mockito
• Spring Test: @SpringBootTest, @WebMvcTest, @DataJpaTest
• Integration Testing: MockMvc for controller tests

Build & Utilities:

• Lombok: For boilerplate reduction (@Data, @RequiredArgsConstructor, @Slf4j, etc.)
• Config Format: application.properties (not YAML)

Containerization:

• Docker & Docker Compose: For PostgreSQL + pgAdmin setup
• pgAdmin 4: Port 5050 for database administration (email: admin@admin.com, password: admin)

---

Package Structure Pattern

Base Package: com.example.hellospringboot

Organization Style: Layer-based structure (NOT feature-based)

src/main/java/com/example/hellospringboot/
├── controller/                       # REST API controllers
├── service/                          # Business logic layer
├── repository/                       # Spring Data JPA repositories
├── entity/                           # JPA entities (@Entity)
├── dto/                             # Data Transfer Objects (request/response)
├── exception/                        # Custom exception classes
└── HelloSpringBootApplication.java   # Main application entry point

src/main/resources/
├── application.properties            # Configuration
└── db/migration/                     # Flyway migration scripts
    └── V{n}__{description}.sql

Important: The project uses a flat, layer-based package structure (NOT feature-based like com.example.app.student.controller).

---

Naming Conventions

Entity Naming

• Entities: Singular noun (e.g., Student.java, Program.java)
• Table names: Lowercase, singular (e.g., @Table(name="student"), @Table(name="program"))
• Field names: camelCase in Java (e.g., firstName, lastName)
• Column names: Lowercase in database, mapped via @Column(name="first_name")

Service Layer

• Interface: [Entity]Service.java (e.g., StudentService.java)
• Implementation: [Entity]ServiceImpl.java (e.g., StudentServiceImpl.java)
• Annotation: @Service
• Lombok: @Slf4j and @RequiredArgsConstructor for constructor injection

Repository Layer

• Class name: [Entity]Repository.java (e.g., StudentRepository.java)
• Extension: extends JpaRepository<[Entity], ID_Type>
• Annotation: @Repository (optional, Spring auto-detects interfaces extending JpaRepository)

Controller Layer

• Class name: [Entity]Controller.java (e.g., StudentController.java)
• Annotation: @RestController
• Base path annotation: @RequestMapping("/api/[plural-entity]") (e.g., /api/students)
• Lombok: @RequiredArgsConstructor for constructor injection

Exception Classes

• Pattern: [Entity]NotFoundException.java, Invalid[Entity]Exception.java
• Example: StudentNotFoundException.java
• Parent class: Extend RuntimeException
• Global Handler: Use @ControllerAdvice with @ExceptionHandler

DTOs

• Response: [Entity]NameResponse.java or [Entity]Response.java (e.g., StudentNameResponse.java)
• Request: [Entity]Request.java (e.g., CreateStudentRequest.java)
• Error: ErrorResponse.java (global error response DTO)

---

Code Patterns & Annotations

Service Layer Pattern

package com.example.hellospringboot.service;

import com.example.hellospringboot.dto.StudentResponse;
import com.example.hellospringboot.entity.Student;
import com.example.hellospringboot.exception.StudentNotFoundException;
import com.example.hellospringboot.repository.StudentRepository;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

@Service
@Slf4j
@RequiredArgsConstructor
public class StudentServiceImpl implements StudentService {

    private final StudentRepository studentRepository;

    @Override
    @Transactional(readOnly = true)
    public StudentResponse getStudentById(Integer id) {
        log.info("Getting student with ID: {}", id);

        Student student = studentRepository.findById(id)
            .orElseThrow(() -> new StudentNotFoundException("Student with ID " + id + " not found"));

        log.info("Student retrieved successfully: ID={}", id);
        return StudentResponse.from(student);
    }

    @Override
    @Transactional
    public StudentResponse createStudent(CreateStudentRequest request) {
        log.info("Creating new student: {}", request.getName());

        Student student = new Student();
        student.setName(request.getName());

        Student saved = studentRepository.save(student);
        log.info("Student created successfully: ID={}", saved.getId());

        return StudentResponse.from(saved);
    }
}

Key patterns to follow:

• Constructor injection with @RequiredArgsConstructor (Lombok)
• @Slf4j for logging (Lombok annotation)
• Service interface with implementation class
• @Transactional(readOnly=true) for read operations
• @Transactional (without params) for write operations
• Log important events (requests, successes, failures)

Controller Layer Pattern

package com.example.hellospringboot.controller;

import com.example.hellospringboot.dto.StudentResponse;
import com.example.hellospringboot.service.StudentService;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import jakarta.validation.Valid;

@RestController
@RequestMapping("/api/students")
@RequiredArgsConstructor
@Slf4j
public class StudentController {

    private final StudentService studentService;

    @GetMapping("/{id}")
    public ResponseEntity<StudentResponse> getStudent(@PathVariable Integer id) {
        log.info("Received request to get student: ID={}", id);
        StudentResponse response = studentService.getStudentById(id);
        return ResponseEntity.ok(response);
    }

    @PostMapping
    public ResponseEntity<StudentResponse> createStudent(@Valid @RequestBody CreateStudentRequest request) {
        log.info("Received request to create student");
        StudentResponse response = studentService.createStudent(request);
        return ResponseEntity.status(HttpStatus.CREATED).body(response);
    }

    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deleteStudent(@PathVariable Integer id) {
        log.info("Received request to delete student: ID={}", id);
        studentService.deleteStudent(id);
        return ResponseEntity.noContent().build();
    }
}

Key patterns:

• @RestController annotation
• Constructor injection for services (@RequiredArgsConstructor)
• @RequestMapping for base path
• @GetMapping, @PostMapping, @PutMapping, @DeleteMapping for endpoints
• @PathVariable for URL parameters
• @RequestBody with @Valid for request validation
• ResponseEntity for HTTP responses with proper status codes
• Logging at controller level

Repository Pattern

package com.example.hellospringboot.repository;

import com.example.hellospringboot.entity.Student;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.stereotype.Repository;

import java.util.Optional;
import java.util.List;

@Repository
public interface StudentRepository extends JpaRepository<Student, Integer> {

    // Spring Data JPA auto-implements findById(Integer id)

    // Custom query methods following Spring Data naming conventions
    Optional<Student> findByName(String name);
    List<Student> findByNameContaining(String keyword);
    boolean existsByName(String name);
}

Key patterns:

• Extend JpaRepository<Entity, ID_Type>
• Method naming follows Spring Data conventions
• Return Optional<T> for single results that might not exist
• Return List<T> for multiple results
• Use boolean for existence checks (existsBy...)

Entity Pattern

package com.example.hellospringboot.entity;

import jakarta.persistence.*;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

@Entity
@Table(name = "student")
@Data
@NoArgsConstructor
@AllArgsConstructor
public class Student {

    @Id
    @Column(name = "id")
    private Integer id;

    @Column(name = "name", length = 255, nullable = false)
    private String name;
}

Key patterns:

• @Entity and @Table annotations
• @Data from Lombok for getters/setters/toString/equals/hashCode
• @NoArgsConstructor and @AllArgsConstructor from Lombok
• @Id for primary key
• @Column annotations with constraints (length, nullable, unique)
• Use @GeneratedValue(strategy = GenerationType.IDENTITY) for auto-increment IDs

Exception Handling Pattern

Custom Exception:

package com.example.hellospringboot.exception;

public class StudentNotFoundException extends RuntimeException {
    public StudentNotFoundException(String message) {
        super(message);
    }
}

Global Exception Handler:

package com.example.hellospringboot.exception;

import com.example.hellospringboot.dto.ErrorResponse;
import lombok.extern.slf4j.Slf4j;
import org.springframework.dao.DataAccessException;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;

@ControllerAdvice
@Slf4j
public class GlobalExceptionHandler {

    @ExceptionHandler(StudentNotFoundException.class)
    public ResponseEntity<ErrorResponse> handleStudentNotFound(StudentNotFoundException ex) {
        log.warn("Student not found: {}", ex.getMessage());

        ErrorResponse error = ErrorResponse.of(
            "STUDENT_NOT_FOUND",
            ex.getMessage()
        );

        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(error);
    }

    @ExceptionHandler(DataAccessException.class)
    public ResponseEntity<ErrorResponse> handleDatabaseError(DataAccessException ex) {
        log.error("Database error: {}", ex.getMessage(), ex);

        ErrorResponse error = ErrorResponse.of(
            "DATABASE_ERROR",
            "Unable to process request due to database error"
        );

        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(error);
    }

    @ExceptionHandler(Exception.class)
    public ResponseEntity<ErrorResponse> handleGenericError(Exception ex) {
        log.error("Unexpected error: {}", ex.getMessage(), ex);

        ErrorResponse error = ErrorResponse.of(
            "INTERNAL_ERROR",
            "An unexpected error occurred"
        );

        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(error);
    }
}

DTO Pattern

package com.example.hellospringboot.dto;

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@NoArgsConstructor
@AllArgsConstructor
public class StudentResponse {
    private String id;
    private String name;

    public static StudentResponse from(Integer id, String name) {
        return new StudentResponse(String.valueOf(id), name);
    }
}

Validation Annotations

Used on DTO request classes:

import jakarta.validation.constraints.*;

@NotNull(message = "Name is required")
@NotBlank(message = "Name cannot be blank")
@Size(min = 1, max = 255, message = "Name must be between 1 and 255 characters")
@Pattern(regexp = "^[a-zA-Z0-9 ]+$", message = "Name can only contain letters, numbers, and spaces")
@Email(message = "Email must be valid")

---

Database Migration with Flyway

Migration File Location: src/main/resources/db/migration/

Naming Convention: V{version}__{description}.sql

Examples:

• V1__Create_student_table.sql
• V2__Add_program_table.sql
• V3__Add_foreign_keys.sql

Migration Example:

-- V1__Create_student_table.sql
CREATE TABLE student (
    id INTEGER PRIMARY KEY,
    name VARCHAR(255) NOT NULL
);

Configuration in application.properties:

spring.flyway.enabled=true
spring.flyway.baseline-on-migrate=true
spring.flyway.locations=classpath:db/migration
spring.jpa.hibernate.ddl-auto=validate

Important Rules:

• Never modify existing migration files after they've been applied
• Always create new migrations for schema changes
• Hibernate uses validate mode - it validates but doesn't auto-create/alter tables
• Use Flyway for all DDL changes (CREATE, ALTER, DROP)

---

HTTP Status Codes

Use these standard HTTP status codes in controllers:

Code	Meaning	When to Use
200 OK	Success	Successful GET, PUT (update)
201 Created	Resource created	Successful POST (new resource)
204 No Content	Success, no body	Successful DELETE
400 Bad Request	Validation error	Invalid input, failed validation
404 Not Found	Resource not found	Entity doesn't exist
409 Conflict	Conflict	Duplicate entries, constraint violations
500 Internal Server Error	Server error	Unexpected errors, database failures

Example:

return ResponseEntity.ok(response);                    // 200
return ResponseEntity.status(HttpStatus.CREATED).body(response); // 201
return ResponseEntity.noContent().build();             // 204
return ResponseEntity.status(HttpStatus.NOT_FOUND).body(error);  // 404

---

Development Workflow

Build Commands

./gradlew build              # Build the project
./gradlew bootRun           # Run the application
./gradlew clean             # Clean build artifacts
./gradlew build -x test     # Build without tests

Testing

./gradlew test                                          # Run all tests
./gradlew test --tests HelloSpringBootApplicationTests # Single test
./gradlew test --tests "*ControllerTests"             # Pattern match

Database (Docker)

cd docker
docker-compose up -d        # Start PostgreSQL + pgAdmin
docker-compose down         # Stop services
docker-compose logs -f      # View logs
docker-compose restart      # Restart services

Access Information:

• PostgreSQL: localhost:5432 (user: postgres, password: datpt, database: hello-spring-db)
• pgAdmin: http://localhost:5050 (email: admin@admin.com, password: admin)

Flyway Commands

./gradlew flywayInfo        # Check migration status
./gradlew flywayValidate    # Validate migrations
./gradlew flywayRepair      # Repair migration history (use with caution)
./gradlew flywayClean       # Clean database (WARNING: deletes all data)

---

Important Notes

Database Credentials

Development Only - Hardcoded in application.properties:

• Host: localhost:5432
• User: postgres
• Password: datpt
• Database: hello-spring-db

⚠️ Production: Use environment variables or secure credential management

Connection Pool Configuration

spring.datasource.hikari.maximum-pool-size=10
spring.datasource.hikari.auto-commit=true
spring.datasource.hikari.max-lifetime=300000

Known Issues

• Existing Program entity may have legacy code or typos
• Table naming: Use singular, lowercase (e.g., student, not students)
• Field naming in entities should be camelCase (e.g., firstName, not first_name)

---

When to Use This Skill

Claude will automatically reference this skill when:

• Generating technical design documents (/generate-design)
• Implementing new features (/implement-database, /implement-service, /implement-api)
• Reviewing code for consistency
• Creating new entities, services, controllers, or repositories
• Planning database migrations
• Setting up error handling patterns

---

Example: Creating a New Feature (Course Management)

When implementing a new "Course" feature:

1. Entity: Course.java (singular)

   • Package: com.example.hellospringboot.entity
   • Table: @Table(name="course") (singular, lowercase)
   • Lombok: @Data, @NoArgsConstructor, @AllArgsConstructor

2. Repository: CourseRepository.java

   • Package: com.example.hellospringboot.repository
   • Extends: JpaRepository<Course, Long>

3. Service: CourseService.java (interface) + CourseServiceImpl.java

   • Package: com.example.hellospringboot.service
   • Annotations: @Service, @Slf4j, @RequiredArgsConstructor
   • Use @Transactional appropriately

4. Controller: CourseController.java

   • Package: com.example.hellospringboot.controller
   • Annotations: @RestController, @RequestMapping("/api/courses")
   • Lombok: @RequiredArgsConstructor, @Slf4j

5. DTOs: CourseResponse.java, CreateCourseRequest.java

   • Package: com.example.hellospringboot.dto

6. Exceptions: CourseNotFoundException.java

   • Package: com.example.hellospringboot.exception

7. Migration: V{n}__Add_course_table.sql

   • Location: src/main/resources/db/migration/

---

Summary

This skill ensures that all generated code and documentation follows:

• ✅ Spring Boot 3.4.4 + Java 17
• ✅ PostgreSQL 15 with Flyway migrations
• ✅ Layer-based package structure
• ✅ Consistent naming conventions
• ✅ Lombok for boilerplate reduction
• ✅ Constructor injection with @RequiredArgsConstructor
• ✅ Proper transaction management
• ✅ Comprehensive logging with @Slf4j
• ✅ Global exception handling
• ✅ Proper HTTP status codes