CLAUDE

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Purpose

This is the GitHub Wiki for lgzarturo/springboot-course — a Spring Boot + Kotlin course teaching REST API development with Hexagonal Architecture, DDD, and TDD. The wiki contains course documentation in Spanish.

Wiki Structure

File	Content
Home.md	Course overview and objectives
1.-Arquitectura-Recomendada.md	Hexagonal Architecture + Screaming Architecture patterns
2.-Guía-de-desarrollo.md	Dev setup, naming conventions, feature development flow
3.-Roadmap-del-curso.md	12-week curriculum outline
5.-Seguridad,-flujo-y-convenciones.md	Security (JWT), Git flow, migrations
7.-Testing-y-calidad.md	Testing pyramid and commands
8.-Lista-de-ejercicios-propuestos.md	Proposed exercises
9.-Gamificando-la-plataforma.md	Gamification with Pokémon API integration
Calendario-de-trabajo-para-milestones.md	Release calendar
_Sidebar.md	Wiki navigation
_Footer.md	Wiki footer

Course Project Commands (for the main repo, not this wiki)

./gradlew bootRun          # Run the application
./gradlew test             # Run all tests
./gradlew test --tests "PingServiceTest"  # Run a single test class

Dev endpoints: /swagger-ui.html, /api-docs, /h2-console (H2, dev only).

Architecture (MVC by Features / Screaming Architecture)

The course uses MVC organized by features (Screaming Architecture). Each feature is self-contained under features/. The project started with Hexagonal Architecture and was migrated — the full reasoning is in docs/architecture/mvc-migration-plan.md in the main repo.

com.lgzarturo.springbootcourse/
  config/            # global Spring config (CORS, OpenAPI)
  common/            # cross-cutting: exception/, pagination/, constants/, extensions/
  features/
    hotels/
      HotelController.kt   # @RestController
      HotelService.kt      # @Service — business logic
      HotelRepository.kt   # @Repository — Spring Data JPA
      HotelEntity.kt       # @Entity JPA
      Hotel.kt             # pure domain model (no Spring deps)
      dto/
        HotelResponse.kt   # includes companion object fromDomain()
        CreateHotelRequest.kt
    users/
    ping/
    rooms/
    sentry/

Key rules:

• Max 2 nesting levels within a feature: hotels/dto/ is the limit.
• No port interfaces — the service IS the interface, the repository IS the interface.
• No separate mapper classes — use companion object fromDomain() in the response DTO.
• No per-feature config classes — use @Service, @Repository, @Component directly.
• YAGNI: don't create feature stubs; create when actually needed.

Naming Conventions

• Classes follow the pattern: PingController, PingService, PingResponse — no PingUseCase or PingMapper
• Mapping lives in a companion object fromDomain() inside the response DTO, not in a separate mapper class
• Constructor injection only (no field injection)
• Kotlin idioms: data class for DTOs and domain models, val over var, null-safety, extension functions
• Database migrations with Flyway: V001__init.sql, V002__add_user_table.sql
• Security roles: TRAINER (guest), GYM_LEADER (staff), PROFESOR_OAK (admin)

Git Conventions

• Branches: feature/, fix/, chore/
• Commits follow Conventional Commits (optional but recommended)
• Content is primarily in Spanish

Testing Approach

• Unit tests: domain services instantiated directly (no Spring context)
• Integration tests: controllers via MockMvc with @WithMockUser for security
• Pattern: Given-When-Then
• Tech stack: JUnit 5, MockK, Spring Boot Test
• Domain test coverage targets business rules, not annotations