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

                   ┌──────────────────┐
                   │    Frontend      │
                   │     NextJS       │
                   └────────┬─────────┘
                            │
                            ▼

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

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

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

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

src/

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

Le dossier Core contient les composants techniques communs.

core/

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

Chaque domaine métier devient un Bounded Context.

modules/

├── auth
├── users
├── owners
├── properties
├── reservations
├── contracts
├── payments
├── crm
├── messaging
├── reporting
├── administration
└── notifications

Chaque module est totalement autonome.

Exemple : Reservation

reservations/

├── domain
│
├── application
│
├── infrastructure
│
└── presentation

Contient exclusivement le métier.

domain/

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

Exemple :

Reservation.ts

ReservationStatus.ts

ReservationCreatedEvent.ts

ReservationRepository.ts

Aucune dépendance NestJS.

Contient les cas d'usage.

application/

├── commands/
├── queries/
├── handlers/
├── dto/
└── mappers/

Contient les implémentations.

infrastructure/

├── persistence/
├── external/
├── repositories/
├── mappers/
└── listeners/

Couche d'exposition.

presentation/

├── controllers/
├── swagger/
└── validators/

Définis dans le domaine.

export interface ReservationRepository {
 
  save(
    reservation: Reservation
  ): Promise<void>;
 
  findById(
    id: string
  ): Promise<Reservation>;
 
}

@Injectable()
export class ReservationRepositoryPg
implements ReservationRepository {
 
}

export interface PaymentGateway {
 
  createPayment(
    amount: number
  ): Promise<string>;
 
}

@Injectable()
export class StripeGateway
implements PaymentGateway {
 
}

export interface SignatureGateway {
 
  sendDocument(
    document: Contract
  ): Promise<void>;
 
}

Les commandes modifient l'état.

Les requêtes lisent l'état.

CreateReservationCommand

UpdateReservationCommand

CancelReservationCommand

ConfirmReservationCommand

GetReservationQuery

SearchReservationsQuery

GetCustomerReservationsQuery

CreateReservationHandler

UpdateReservationHandler

CancelReservationHandler

POST /reservations

        │

        ▼

CreateReservationCommand

        │

        ▼

CreateReservationHandler

        │

        ▼

ReservationDomainService

        │

        ▼

ReservationRepository

        │

        ▼

PostgreSQL

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

ReservationCreated

ReservationConfirmed

ReservationCancelled

ReservationCompleted

ContractGenerated

ContractSigned

ContractRefused

PaymentAuthorized

PaymentSucceeded

PaymentFailed

PaymentRefunded

ReservationCreated

       │

       ├── NotificationService
       │
       ├── ContractService
       │
       ├── CRMService
       │
       └── AuditService

export interface PropertyRepository {
 
  findById(
    id: string
  ): Promise<Property>;
 
  save(
    property: Property
  ): Promise<void>;
 
}

export class PropertyRepositoryPg
implements PropertyRepository {
 
}

Lorsque la logique dépasse une seule entité.

ReservationDomainService

PropertyAvailabilityService

ContractGenerationService

PaymentCalculationService

OwnerRevenueService

Objets immuables métier.

Money

Email

PhoneNumber

PostalAddress

DateRange

ReservationPeriod

Reservation

 ├── Guests
 ├── Payments
 ├── Contract
 └── Events

Property

 ├── Address
 ├── Features
 ├── Photos
 ├── Availability
 └── Rates

AuthModule

UsersModule

OwnersModule

PropertiesModule

ReservationsModule

ContractsModule

PaymentsModule

MessagingModule

CRMModule

ReportingModule

AdministrationModule

NotificationsModule

Stripe

PayPal (optionnel)

MangoPay (optionnel)

Yousign

DocuSign

AWS S3

MinIO

OVH Object Storage

SMTP

SMS Gateway

Push Notifications

Internet

 │

 ▼

Cloudflare

 │

 ▼

Nginx

 │

 ▼

Frontend NextJS

 │

 ▼

Backend NestJS

 │

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

 ▼

PostgreSQL

 ▼

Redis

 ▼

S3

Utilisations :

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

Traitements asynchrones.

GenerateContractWorker

SendEmailWorker

SendNotificationWorker

GenerateInvoiceWorker

ReportingWorker

• JWT Access Token
• Refresh Token
• Rotation Token

• RBAC
• Permissions granulaires

Toutes les actions critiques :

• Création
• Modification
• Suppression
• Connexion
• Paiement

sont journalisées.

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

À 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.