6.9 KiB
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 :
- Clean Architecture (Robert C. Martin) : Séparation en couches concentriques avec règle de dépendance stricte vers l'intérieur.
- 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.
- 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émentantShared\DDD\Model\EntityouShared\DDD\Model\AggregateRoot(modèles d'écriture) et/ouShared\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\etShared\. 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>).
- Chaque cas d'usage se compose d'un triplet obligatoire :
3. Presentation\ - Les Points d'Entrée Utilisateur / API
- Dépendance : Dépend de
Application\,Domain\etShared\. Peut utiliser les composants HTTP de Laravel. - Contenu :
Controllers/: Single-action invokables (__invoke). Reçoivent laFormRequest, construisent l'Input, appellentUsecaseBuilderet retournent uneJsonResponse.Requests/:FormRequestpour la validation syntaxique HTTP.Presenters/&Views/: Transformateurs de l'OutputUse 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\etShared\. - 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\:ClockPSR-20,SystemClock,SystemUtcClock,FrozenClock, FaçadeUtc).
- Socle DDD (
🚫 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\* |