backend/CLAUDE.md

# CLAUDE.md

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

## Project Overview

Xpeditis is a Spring Boot-based logistics/shipping application built with a modular Maven architecture. The project follows Hexagonal Architecture (Clean Architecture) principles with clear separation of concerns.

## Architecture

### Modular Structure
The project is organized into Maven modules:

- **bootstrap**: Main application entry point and configuration (XpeditisApplication.java)
- **application**: REST controllers and web layer (AuthenticationRestController, UserRestController)
- **domain**: Core business logic split into:
  - **api**: Service interfaces (UserService, AuthenticationService, etc.)
  - **data**: DTOs and exceptions (UserAccount, AuthenticationRequest/Response)
  - **service**: Service implementations (UserServiceImpl, AuthenticationServiceImpl)
  - **spi**: Repository interfaces (UserRepository, AuthenticationRepository)
- **infrastructure**: Data access layer with JPA entities, repositories, and external integrations
- **common**: Shared utilities (CommonUtil)

### Key Technologies
- Spring Boot 3.4.1 with Java 23
- Spring Security with JWT authentication
- JPA/Hibernate for data persistence
- MapStruct for entity mapping
- Lombok for boilerplate reduction
- Flyway for database migrations
- MySQL (prod) / H2 (dev) databases

## Development Commands

### Build and Test
```bash
# Clean build and install all modules
./mvnw clean install

# Run tests
./mvnw test

# Run single test class
./mvnw test -Dtest=UserServiceImplTest

# Run specific test method
./mvnw test -Dtest=UserServiceImplTest#shouldCreateUser
```

### Database Management
```bash
# Development (H2) - migrate database
./mvnw clean install flyway:migrate '-Dflyway.configFiles=flyway-h2.conf' -Pdev

# Production (MySQL) - migrate database  
./mvnw clean install flyway:migrate -Pprod

# Start application with dev profile (default)
./mvnw spring-boot:run

# Start with production profile
./mvnw spring-boot:run -Pprod
```

### Docker Operations
```bash
# Build and start services with Docker Compose
docker-compose up --build

# Start database only
docker-compose up db

# View logs
docker-compose logs -f back
```

## Development Profiles

- **dev** (default): Uses H2 in-memory database, simplified configuration
- **prod**: Uses MySQL database, includes Flyway migrations, production-ready settings

## Key Configuration Files

- `bootstrap/src/main/resources/application.yml`: Main configuration
- `bootstrap/src/main/resources/application-dev.yml`: Development overrides  
- `bootstrap/src/main/resources/application-prod.yml`: Production overrides
- `infrastructure/flyway.conf`: Database migration configuration
- `compose.yml`: Docker services configuration

## API Documentation

Swagger UI is available at: http://localhost:8080/swagger-ui.html

## Security Implementation

The application uses JWT-based authentication with:
- JWT token generation and validation (JwtUtil)
- Security configuration (SecurityConfiguration)  
- Authentication filter (JwtAuthenticationFilter)
- Logout service (LogoutService)
- Role-based access control with Permission enum

## Testing Strategy

- Unit tests for service layer implementations (AddressServiceImplTest, etc.)
- Repository tests for data access layer (AddressJpaRepositoryTest, etc.) 
- Integration tests in bootstrap module (LeBlrApplicationTests)
- Use AssertJ for fluent assertions

## Database Schema

Database migrations are in `infrastructure/src/main/resources/db/migration/`:
- `structure/V1__INIT_DB_SCHEMA.sql`: Initial schema
- `data/V1.1__INIT_DB_DATA.sql`: Initial data

## Logging

Structured logging configuration in `logback-spring.xml` with:
- Production logs written to `./logs/prod/`
- Request logging via CommonsRequestLoggingFilter
- Configurable log levels per package

## 🏗️ Checklist Architecture Hexagonale - Étapes de Validation Pré-Codage

### 📋 Phase 1 : Analyse et Compréhension du Contexte

#### ✅ 1.1 Identification du Domaine Métier
- [ ] Clarifier le domaine d'activité : Quel est le métier principal ?
- [ ] Identifier les entités métier principales : Quels sont les objets centraux ?
- [ ] Définir les règles de gestion : Quelles sont les contraintes business ?
- [ ] Mapper les cas d'usage : Que doit faire l'application ?

#### ✅ 1.2 Analyse des Besoins d'Intégration
- [ ] Identifier les acteurs externes : Qui utilise l'application ?
- [ ] Répertorier les services externes : BDD, APIs, systèmes de fichiers ?
- [ ] Définir les interfaces d'entrée : REST, GraphQL, CLI ?
- [ ] Spécifier les interfaces de sortie : Persistance, notifications, etc.

### 📐 Phase 2 : Conception Architecturale

#### ✅ 2.1 Structure des Modules Maven
- [ ] Valider la structure 4 modules :
  - `domain` (cœur hexagonal)
  - `application` (couche application)
  - `infrastructure` (couche infrastructure)
  - `bootstrap` (module de lancement)

#### ✅ 2.2 Définition des Ports
- [ ] Identifier les Ports API (interfaces exposées par le domaine) :
  - Services métier que le domaine expose
  - Interfaces appelées par les adaptateurs d'entrée
- [ ] Identifier les Ports SPI (interfaces requises par le domaine) :
  - Repositories pour la persistance
  - Services externes (notifications, intégrations)
  - Interfaces que le domaine définit mais n'implémente pas

#### ✅ 2.3 Conception des Adaptateurs
- [ ] Adaptateurs d'Entrée (Driving) :
  - Contrôleurs REST
  - Interfaces utilisateur
  - Tests automatisés
- [ ] Adaptateurs de Sortie (Driven) :
  - Implémentations des repositories
  - Clients pour services externes
  - Systèmes de fichiers/messaging

### 🏛️ Phase 3 : Architecture en Couches

#### ✅ 3.1 Module Domain (Cœur)
- [ ] Vérifier l'isolation complète : Aucune dépendance externe
- [ ] Structure du package :
```
com.{project}.domain/
├── model/          # Entités métier
├── service/        # Services du domaine  
├── port/
│   ├── in/        # Ports d'entrée (API)
│   └── out/       # Ports de sortie (SPI)
└── exception/     # Exceptions métier
```

#### ✅ 3.2 Module Application
- [ ] Responsabilités claires : Exposition des services
- [ ] Structure du package :
```
com.{project}.application/
├── controller/    # Contrôleurs REST
├── dto/          # Data Transfer Objects
├── mapper/       # Mappers DTO ↔ Domain
└── config/       # Configuration Spring
```

#### ✅ 3.3 Module Infrastructure
- [ ] Implémentation des SPI : Tous les ports de sortie
- [ ] Structure du package :
```
com.{project}.infrastructure/
├── adapter/
│   ├── in/       # Adaptateurs d'entrée (si applicable)
│   └── out/      # Adaptateurs de sortie
├── repository/   # Implémentations JPA
├── entity/       # Entités JPA
└── mapper/       # Mappers JPA ↔ Domain
```

#### ✅ 3.4 Module bootstrap
- [ ] Point d'entrée unique : Classe @SpringBootApplication
- [ ] Assemblage des dépendances : Configuration complète
- [ ] Dépendances vers tous les modules

### 🔧 Phase 4 : Validation Technique

#### ✅ 4.1 Gestion des Dépendances
- [ ] Module domain : Aucune dépendance externe (sauf tests)
- [ ] Module application : Dépend uniquement de domain
- [ ] Module infrastructure : Dépend uniquement de domain
- [ ] Module bootstrap : Dépend de tous les autres modules

#### ✅ 4.2 Respect des Patterns
- [ ] Domain-Driven Design : Entités, Value Objects, Aggregates
- [ ] SOLID Principles : SRP, DIP, ISP appliqués
- [ ] Repository Pattern : Abstraction de la persistance
- [ ] Clean Architecture : Règle de dépendance respectée

#### ✅ 4.3 Configuration Spring
- [ ] Injection de dépendance : Utilisation de @Configuration
- [ ] Éviter @Component dans le domaine
- [ ] Gestion des transactions : @Transactional dans l'application

### 🧪 Phase 5 : Stratégie de Test

#### ✅ 5.1 Tests par Couche
- [ ] Tests unitaires du domaine : Sans dépendances externes
- [ ] Tests d'intégration : Par adaptateur spécifique
- [ ] Tests end-to-end : Flux complets
- [ ] Mocking strategy : Interfaces bien définies

#### ✅ 5.2 Testabilité
- [ ] Isolation du domaine : Tests sans Spring Context
- [ ] Adaptateurs mockables : Interfaces clairement définies
- [ ] Données de test : Jeux de données cohérents

### 📝 Phase 6 : Naming et Conventions

#### ✅ 6.1 Conventions de Nommage
- [ ] Ports : Suffixe "Port" ou noms explicites d'interfaces
- [ ] Adaptateurs : Suffixe "Adapter"
- [ ] Services : Suffixe "Service"
- [ ] Repositories : Suffixe "Repository"

#### ✅ 6.2 Structure des Packages
- [ ] Cohérence : Nommage uniforme entre modules
- [ ] Lisibilité : Structure claire et intuitive
- [ ] Séparation : Concerns bien séparés

### 🎯 Phase 7 : Questions de Validation Finale

#### ✅ 7.1 Questions Critiques à Se Poser
- [ ] Le domaine est-il complètement isolé ?
- [ ] Les dépendances pointent-elles vers l'intérieur ?
- [ ] Peut-on tester le domaine sans Spring ?
- [ ] Peut-on changer de base de données sans impact sur le domaine ?
- [ ] Peut-on ajouter une nouvelle interface (GraphQL) facilement ?

#### ✅ 7.2 Validation des Flux
- [ ] Flux d'entrée : HTTP → Contrôleur → Service → Port API
- [ ] Flux de sortie : Port SPI → Adaptateur → Base/Service externe
- [ ] Mapping : DTO ↔ Domain ↔ JPA entities clairement défini

### 🚦 Phase 8 : Checklist Pré-Codage

#### ✅ 8.1 Avant de Commencer
- [ ] Architecture validée avec le demandeur
- [ ] Modules Maven structure approuvée
- [ ] Ports et Adaptateurs identifiés et documentés
- [ ] Stack technique confirmée (Spring Boot, H2, MapStruct)
- [ ] Stratégie de tests définie

#### ✅ 8.2 Ordre de Développement Recommandé
1. Module domain : Entités, services, ports
2. Module infrastructure : Adaptateurs de sortie, repositories
3. Module application : Contrôleurs, DTOs, mappers
4. Module bootstrap : Configuration, assemblage
5. Tests : Unitaires → Intégration → E2E

### 💡 Points d'Attention Spéciaux

#### ⚠️ Pièges à Éviter
- Dépendances circulaires entre modules
- Logique métier dans les adaptateurs
- Annotations Spring dans le domaine
- Couplage fort entre couches
- Tests qui nécessitent le contexte Spring pour le domaine

#### 🎯 Objectifs à Atteindre
- Domaine pur et testable isolément
- Flexibilité pour changer d'adaptateurs
- Maintenabilité et évolutivité
- Séparation claire des responsabilités
- Code réutilisable et modulaire