Crealcs Development DokuWiki

Modifiez cette page et cliquez sur « Enregistrer ». Voyez le guide de mise en page pour une aide à propos du formatage. Veuillez ne modifier cette page que si vous pouvez l'améliorer. Si vous souhaitez faire des tests, faites vos premiers pas dans le bac à sable.

====== Architecture Hexagonale Backend NestJS ======

===== Objectifs =====

L'architecture backend doit répondre aux exigences suivantes :

* Forte maintenabilité
  * Forte testabilité
  * Séparation stricte des responsabilités
  * Évolutivité métier
  * Indépendance de la base de données
  * Indépendance des fournisseurs externes
  * Compatibilité microservices future
  * Compatibilité Event Driven Architecture

L'architecture retenue est :

* Architecture Hexagonale (Ports & Adapters)
  * Domain Driven Design (DDD)
  * CQRS
  * Event Bus
  * Repository Pattern
  * Clean Architecture

----

====== Vue globale ======

<code>
                   ┌──────────────────┐
                   │    Frontend      │
                   │     NextJS       │
                   └────────┬─────────┘
                            │
                            ▼

┌────────────────────┐
                  │    REST API        │
                  │ NestJS Controllers │
                  └────────┬───────────┘
                           │
                           ▼

┌─────────────────────────┐
                │    Application Layer    │
                │ Commands / Queries      │
                └──────────┬──────────────┘
                           │
                           ▼

┌─────────────────────────┐
                │      Domain Layer       │
                │ Entities / Services     │
                └──────────┬──────────────┘
                           │
                           ▼

┌─────────────────────────┐
                │ Infrastructure Layer    │
                │ PostgreSQL / S3 / SMTP  │
                └─────────────────────────┘
</code>

----

====== Structure du projet ======

<code>
src/

├── core/
│
├── modules/
│
├── infrastructure/
│
├── shared/
│
├── config/
│
└── main.ts
</code>

----

====== Core ======

Le dossier Core contient les composants techniques communs.

<code>
core/

├── domain/
│
├── application/
│
├── ports/
│
├── cqrs/
│
├── events/
│
├── exceptions/
│
├── value-objects/
│
└── shared-kernel/
</code>

----

====== Organisation DDD ======

Chaque domaine métier devient un Bounded Context.

<code>
modules/

├── auth
├── users
├── owners
├── properties
├── reservations
├── contracts
├── payments
├── crm
├── messaging
├── reporting
├── administration
└── notifications
</code>

Chaque module est totalement autonome.

----

====== Structure interne d'un module ======

Exemple : Reservation

<code>
reservations/

├── domain
│
├── application
│
├── infrastructure
│
└── presentation
</code>

----

===== Domain =====

Contient exclusivement le métier.

<code>
domain/

├── entities/
├── value-objects/
├── repositories/
├── services/
├── events/
└── exceptions/
</code>

Exemple :

<code>
Reservation.ts

ReservationStatus.ts

ReservationCreatedEvent.ts

ReservationRepository.ts
</code>

Aucune dépendance NestJS.

----

===== Application =====

Contient les cas d'usage.

<code>
application/

├── commands/
├── queries/
├── handlers/
├── dto/
└── mappers/
</code>

----

===== Infrastructure =====

Contient les implémentations.

<code>
infrastructure/

├── persistence/
├── external/
├── repositories/
├── mappers/
└── listeners/
</code>

----

===== Presentation =====

Couche d'exposition.

<code>
presentation/

├── controllers/
├── swagger/
└── validators/
</code>

----

====== Ports & Adapters ======

===== Ports =====

Définis dans le domaine.

<code ts>
export interface ReservationRepository {

save(
    reservation: Reservation
  ): Promise<void>;

findById(
    id: string
  ): Promise<Reservation>;

}
</code>

----

===== Adapter PostgreSQL =====

<code ts>
@Injectable()
export class ReservationRepositoryPg
implements ReservationRepository {

}
</code>

----

===== Adapter Stripe =====

<code ts>
export interface PaymentGateway {

createPayment(
    amount: number
  ): Promise<string>;

}
</code>

----

<code ts>
@Injectable()
export class StripeGateway
implements PaymentGateway {

}
</code>

----

===== Adapter Signature Électronique =====

<code ts>
export interface SignatureGateway {

sendDocument(
    document: Contract
  ): Promise<void>;

}
</code>

----

====== Architecture CQRS ======

Les commandes modifient l'état.

Les requêtes lisent l'état.

----

===== Commands =====

<code>
CreateReservationCommand

UpdateReservationCommand

CancelReservationCommand

ConfirmReservationCommand
</code>

----

===== Queries =====

<code>
GetReservationQuery

SearchReservationsQuery

GetCustomerReservationsQuery
</code>

----

===== Handlers =====

<code>
CreateReservationHandler

UpdateReservationHandler

CancelReservationHandler
</code>

----

====== Exemple de flux CQRS ======

<code>
POST /reservations

│

▼

CreateReservationCommand

│

▼

CreateReservationHandler

│

▼

ReservationDomainService

│

▼

ReservationRepository

│

▼

PostgreSQL
</code>

----

====== Event Bus ======

Tous les événements métier sont publiés.

----

===== Événements Réservation =====

<code>
ReservationCreated

ReservationConfirmed

ReservationCancelled

ReservationCompleted
</code>

----

===== Événements Contrat =====

<code>
ContractGenerated

ContractSigned

ContractRefused
</code>

----

===== Événements Paiement =====

<code>
PaymentAuthorized

PaymentSucceeded

PaymentFailed

PaymentRefunded
</code>

----

===== Flux événementiel =====

<code>
ReservationCreated

│

├── NotificationService
       │
       ├── ContractService
       │
       ├── CRMService
       │
       └── AuditService
</code>

----

====== Repository Pattern ======

===== Interface Domaine =====

<code ts>
export interface PropertyRepository {

findById(
    id: string
  ): Promise<Property>;

save(
    property: Property
  ): Promise<void>;

}
</code>

----

===== Implémentation PostgreSQL =====

<code ts>
export class PropertyRepositoryPg
implements PropertyRepository {

}
</code>

----

====== Domain Services ======

Lorsque la logique dépasse une seule entité.

----

===== Exemple =====

<code>
ReservationDomainService

PropertyAvailabilityService

ContractGenerationService

PaymentCalculationService

OwnerRevenueService
</code>

----

====== Value Objects ======

Objets immuables métier.

----

===== Exemples =====

<code>
Money

Email

PhoneNumber

PostalAddress

DateRange

ReservationPeriod
</code>

----

====== Aggregate Roots ======

===== Reservation =====

<code>
Reservation

├── Guests
 ├── Payments
 ├── Contract
 └── Events
</code>

----

===== Property =====

<code>
Property

├── Address
 ├── Features
 ├── Photos
 ├── Availability
 └── Rates
</code>

----

====== Modules NestJS ======

<code>
AuthModule

UsersModule

OwnersModule

PropertiesModule

ReservationsModule

ContractsModule

PaymentsModule

MessagingModule

CRMModule

ReportingModule

AdministrationModule

NotificationsModule
</code>

----

====== Services externes ======

===== Paiement =====

<code>
Stripe

PayPal (optionnel)

MangoPay (optionnel)
</code>

----

===== Signature =====

<code>
Yousign

DocuSign
</code>

----

===== Stockage =====

<code>
AWS S3

MinIO

OVH Object Storage
</code>

----

===== Notifications =====

<code>
SMTP

SMS Gateway

Push Notifications
</code>

----

====== Architecture de déploiement ======

<code>
Internet

│

▼

Cloudflare

│

▼

Nginx

│

▼

Frontend NextJS

│

▼

Backend NestJS

│

├── API
 │
 ├── Workers
 │
 ├── Scheduler
 │
 └── Event Consumers

▼

PostgreSQL

▼

Redis

▼

S3
</code>

----

====== Redis ======

Utilisations :

* Cache
  * Sessions
  * Event Bus
  * Rate Limiting
  * File d'attente

----

====== Workers ======

Traitements asynchrones.

<code>
GenerateContractWorker

SendEmailWorker

SendNotificationWorker

GenerateInvoiceWorker

ReportingWorker
</code>

----

====== Sécurité ======

===== Authentification =====

* JWT Access Token
  * Refresh Token
  * Rotation Token

----

===== Autorisation =====

* RBAC
  * Permissions granulaires

----

===== Audit =====

Toutes les actions critiques :

* Création
  * Modification
  * Suppression
  * Connexion
  * Paiement

sont journalisées.

----

====== Résultat ======

Cette architecture permet :

* Scalabilité horizontale
  * Découplage métier
  * Forte maintenabilité
  * Tests unitaires complets
  * Tests d'intégration
  * Migration vers microservices
  * Évolution SaaS multi-agences

----

====== Étape suivante ======

À partir de cette architecture, nous pouvons désormais produire :

* Spécification OpenAPI 3.1 complète
  * Contrats DTO
  * Schémas JSON
  * Validation métier
  * Gestion des erreurs
  * Pagination
  * Filtrage
  * Tri
  * Authentification JWT
  * Documentation Swagger

Ce document servira ensuite de base à la génération automatique du frontend et des SDK clients.

Résumé

Note : En modifiant cette page, vous acceptez que le contenu soit placé sous les termes de la licence suivante : CC Attribution-Share Alike 4.0 International