ldc-arcadia-api/documentation/Architecture/01-architecture-globale.md

6.9 KiB

Architecture Globale - Arcadia API

Ce document présente l'architecture logicielle d'Arcadia API à destination des développeurs.


🏛️ Les 3 Piliers Architecturaux

Arcadia API combine 3 paradigmes éprouvés pour créer une base de code hautement maintenable, testable et découplée du framework :

  1. Clean Architecture (Robert C. Martin) : Séparation en couches concentriques avec règle de dépendance stricte vers l'intérieur.
  2. Domain-Driven Design (Eric Evans) : Modèle métier riche et expressif (Entités, Value Objects, Agrégats, Événements de Domaine), indépendant de tout détail technique.
  3. Architecture Hexagonale (Alistair Cockburn) : Ports (interfaces dans le Domaine) et Adaptateurs (implémentations techniques dans l'Infrastructure).
┌─────────────────────────────────────────────────────────────┐
│                       PRESENTATION                          │
│  (API Controllers, FormRequests, Presenters, Views, DTOs)   │
├──────────────────────────────┬──────────────────────────────┤
│         APPLICATION          │            INFRA             │
│   (Use Cases, Input, Output) │ (Eloquent, DB, Cache, Logs)  │
├──────────────────────────────┴──────────────────────────────┤
│                           DOMAIN                            │
│    (Entities, Value Objects, Ports/Interfaces, Events)      │
├─────────────────────────────────────────────────────────────┤
│                           SHARED                            │
│       (Socle DDD générique, UsecaseBuilder, Pagination)     │
└─────────────────────────────────────────────────────────────┘

🎯 Rôle et Responsabilité de Chaque Couche

1. Domain\ - Le Coeur Métier Pur

  • Dépendance : Ne dépend de RIEN (sauf Shared\). Aucun import Laravel / Eloquent / HTTP n'est toléré.
  • Contenu :
    • Models/Entities/ : Entités riches, final readonly, immutables, implémentant Shared\DDD\Model\Entity ou Shared\DDD\Model\AggregateRoot (modèles d'écriture) et/ou Shared\DDD\Model\ReadModel (modèles de lecture).
    • Models/ValueObjects/ : Objets-valeurs typés et auto-validants (ex: SiRhMatricule, NutriScore, BrandCode).
    • Ports/ : Interfaces des opérations externes :
      • Directories/ : Ports de lecture seule pour modèles de lecture purs (Directory<TId, TReadModel of ReadModel>).
      • Repositories/ : Ports de cycle de vie et requêtes d'agrégats racines (Repository<TId, TAggregate of AggregateRoot>).
      • Services/ : Interfaces pour services externes métier.
    • Events/ : Événements métier purs (ex: BrandCreated).
    • Services/ : Logique métier pure impliquant plusieurs entités.

2. Application\ - L'Orchestration des Cas d'Usage

  • Dépendance : Dépend uniquement de Domain\ et Shared\. Pas de Laravel ni d'HTTP.
  • Contenu : Cas d'usage métier découpés par contexte (Application/Arcadia/Usecase/{Context}/{Action}/).
    • Chaque cas d'usage se compose d'un triplet obligatoire :
      • Input.php : DTO d'entrée typé (Shared\DDD\Usecase\Input).
      • Output.php : DTO de sortie agnostique (Shared\DDD\Usecase\Output).
      • {ActionName}.php : Classe orchestratrice (Shared\DDD\Usecase\Usecase<Input, Output>).

3. Presentation\ - Les Points d'Entrée Utilisateur / API

  • Dépendance : Dépend de Application\, Domain\ et Shared\. Peut utiliser les composants HTTP de Laravel.
  • Contenu :
    • Controllers/ : Single-action invokables (__invoke). Reçoivent la FormRequest, construisent l'Input, appellent UsecaseBuilder et retournent une JsonResponse.
    • Requests/ : FormRequest pour la validation syntaxique HTTP.
    • Presenters/ & Views/ : Transformateurs de l'Output Use Case en DTO de vue spécifique (Presenter<Output, View>).
    • Responses/ & Dto/ : Sérialisation finale en JSON (conformité OpenAPI).

4. Infra\ - L'Infrastructure et les Adaptateurs Techniques

  • Dépendance : Dépend de Domain\, Application\ et Shared\.
  • Règle d'or : Aucune autre couche n'importe Infra\. C'est le conteneur d'injection de dépendances (Service Provider) qui lie les Ports du Domaine aux Adaptateurs d'Infra.
  • Contenu :
    • Adapters/ : Implémentations Eloquent des Ports (EloquentEmployeeDirectory, EloquentBrandRepository).
    • Database/Models/ : Modèles Eloquent anémiques (mapping BDD uniquement).
    • Database/Concerns/ : Traits de persistance (HasUuidV7CreatedAt).
    • Casts/ : Casts Eloquent bidirectionnels (UtcDateTimeCast, UuidCast, etc.).
    • Http/Middleware/ : Middlewares techniques (HMAC, Auth).
    • Providers/ : Configuration des bindings Laravel (DomainServiceProvider, SecurityServiceProvider, ConfigServiceProvider).
    • Usecase/LaravelExecutor.php : Exécuteur transactionnel et logging PSR-3.

5. Shared\ - Le Socle DDD Transverse

  • Dépendance : Zéro dépendance externe (hors PSR-20).
  • Contenu :
    • Socle DDD (Entity, EntityId, AggregateRoot, ReadModel, Usecase, Input, Output, Presenter, DomainEventDispatcher, TransactionalDomainEventDispatcher, UsecaseBuilder, Paginated, Pagination).
    • Gestion du temps (Shared\Time\ : Clock PSR-20, SystemClock, SystemUtcClock, FrozenClock, Façade Utc).

🚫 Règles de Dépendance (Vérifiées par Pest Arch)

Couche Peut importer... Ne peut JAMAIS importer...
Domain Shared Application, Presentation, Infra, Illuminate\*, Laravel
Application Domain, Shared Presentation, Infra, Illuminate\*, Laravel
Presentation Application, Domain, Shared Infra (sauf bindings conteneur)
Infra Domain, Application, Shared Presentation
Shared Rien Domain, Application, Presentation, Infra, Illuminate\*