# Architecture — Clean Architecture (Hexagonale)

## Structure des couches

L'application suit une **Clean Architecture** avec le pattern Ports & Adapters :

```
src/main/java/com/olhar/olharapi/
  domain/           ← Entités métier et exceptions (aucune dépendance framework)
    model/
    exception/
  application/      ← Cas d'usage (logique métier), ports d'entrée et de sortie
    port/
      in/           ← Interfaces des cas d'usage (appelées par interfaces/)
      out/          ← Interfaces de sortie (implémentées par infrastructure/)
    usecase/        ← Implémentations des cas d'usage
  infrastructure/   ← Adaptateurs sortants (BDD, sécurité, configuration)
    persistence/
      entity/       ← Entités JPA (distinctes des entités domaine)
      mapper/       ← Conversion domaine ↔ JPA
      repository/   ← Adaptateurs JPA implémentant les ports out
    security/
    config/
  interfaces/       ← Adaptateurs entrants (REST)
    rest/
      controller/
      dto/
        request/
        response/
      mapper/       ← Conversion domaine ↔ DTO REST
    exception/      ← Handlers d'exception globaux
```

## Règles par couche

- **`domain/`** : Java pur — pas de Spring, pas de JPA, pas de Lombok avancé. Entités et exceptions métier uniquement.
- **`application/`** : interfaces des ports (`port/in`, `port/out`) + services implémentant les cas d'usage. Pas de dépendance à Spring Web ou JPA.
- **`infrastructure/`** : adaptateurs Spring/JPA/sécurité. Implémente les ports `out`. Annoté Spring (`@Service`, `@Repository`, `@Component`).
- **`interfaces/`** : contrôleurs REST et DTOs. Invoque les ports `in`. Annoté `@RestController`. Pas de logique métier inline.

## Interdictions

- Jamais d'import de `infrastructure/` ou `interfaces/` depuis `domain/` ou `application/`.
- Jamais de logique métier dans un contrôleur (`interfaces/rest/controller/`).
- Jamais d'entité JPA (`infrastructure/persistence/entity/`) retournée directement par un contrôleur.
- Jamais d'appel direct à un repository JPA depuis `application/usecase/` — passer par les ports `out`.
- Les mappers (`UserPersistenceMapper`, `UserRestMapper`) restent dans leur couche respective, pas dans `domain/`.

## Règles de code

- Utiliser **Lombok** pour les entités, DTOs et mappers (mais pas dans `domain/model/` si les entités sont simples).
- Pas de commentaires explicatifs sur ce que fait le code — seulement sur le **pourquoi** si non évident.
- Pas d'abstraction prématurée : implémenter ce qui est demandé, pas ce qui pourrait être utile plus tard.