xpeditis2.0/docs/architecture.md

Architecture Globale - Xpeditis

Date de l'audit: 2025-12-22 Version: v0.1.0 Architecte: Audit automatisé Claude Code

---

📋 Vue d'ensemble

Xpeditis est une plateforme B2B SaaS de réservation de fret maritime construite avec une architecture hexagonale stricte (Ports & Adapters) côté backend et une architecture en couches côté frontend.

Stack technique

Backend:

• NestJS 10+ (Framework)
• TypeScript 5+ (strict mode)
• PostgreSQL 15+ (Base de données)
• TypeORM 0.3+ (ORM)
• Redis 7+ (Cache)
• Architecture: Hexagonale (Ports & Adapters)

Frontend:

• Next.js 14+ (App Router)
• React 18+
• TypeScript 5+
• TanStack Query (Server state)
• shadcn/ui (Components)
• Architecture: Layered + Feature-based

---

🏗️ Architecture Hexagonale - Backend

Principe fondamental

Infrastructure Layer → Application Layer → Domain Layer
     (Adapters)           (Use Cases)       (Business Logic)

Règle d'or: Les dépendances pointent UNIQUEMENT vers l'intérieur (vers le domaine). Le domaine ne connaît RIEN des couches externes.

Couches & Responsabilités

1. Domain Layer (Cœur métier)

Localisation: apps/backend/src/domain/

Contenu:

• Entities (13 fichiers): Objets métier avec identité
  • booking.entity.ts, rate-quote.entity.ts, user.entity.ts, etc.
• Value Objects (9 fichiers): Objets immuables sans identité
  • money.vo.ts, email.vo.ts, booking-number.vo.ts, etc.
• Services (7 fichiers): Logique métier pure
  • rate-search.service.ts, booking.service.ts, etc.
• Ports (21 fichiers):
  • In: 4 ports (use cases exposés)
  • Out: 17 ports (interfaces de dépendances externes)
• Exceptions (9 fichiers): Exceptions métier

Contraintes STRICTES:

• ❌ AUCUN import de framework (NestJS, TypeORM, etc.)
• ❌ AUCUNE dépendance externe
• ✅ TypeScript pur uniquement
• ✅ Testable sans NestJS TestingModule

2. Application Layer (Orchestration)

Localisation: apps/backend/src/application/

Contenu:

• Controllers (17 fichiers): Points d'entrée HTTP
• DTOs (15 fichiers): Validation des requêtes/réponses
• Services (11 fichiers): Orchestration des cas d'usage
• Mappers (8 fichiers): Conversion DTO ↔ Domain
• Guards (4 fichiers): Sécurité (JWT, RBAC, Rate limiting)
• Modules (14 fichiers): Configuration NestJS

Responsabilités:

• Recevoir les requêtes HTTP
• Valider les entrées (DTOs)
• Appeler les services domaine
• Mapper les résultats
• Retourner les réponses HTTP

Dépendances autorisées:

• ✅ Domain layer (via imports @domain/*)
• ✅ NestJS (decorators, guards, interceptors)
• ❌ Infrastructure layer directement (uniquement via injection)

3. Infrastructure Layer (Adapters externes)

Localisation: apps/backend/src/infrastructure/

Contenu:

• Persistence/TypeORM:
  • ORM Entities (15 fichiers)
  • Repositories (13 implémentations)
  • Mappers ORM ↔ Domain (9 fichiers)
  • Migrations (18 fichiers)
• Carriers (7 connecteurs): Maersk, MSC, CMA CGM, etc.
• Cache: Redis adapter
• Email: MJML templates + Nodemailer
• Storage: S3/MinIO adapter
• PDF: PDF generation adapter
• Security: Helmet, CORS config

Responsabilités:

• Implémenter les ports définis par le domaine
• Gérer les détails techniques (DB, API externes, cache, etc.)
• Mapper les données externes vers le domaine

Pattern clé: Chaque adapter implémente un port domaine

// Domain port
export interface BookingRepository {
  save(booking: Booking): Promise<Booking>;
  findById(id: string): Promise<Booking | null>;
}

// Infrastructure implementation
export class TypeOrmBookingRepository implements BookingRepository {
  async save(booking: Booking): Promise<Booking> {
    const ormEntity = BookingOrmMapper.toOrm(booking);
    const saved = await this.repository.save(ormEntity);
    return BookingOrmMapper.toDomain(saved);
  }
}

---

🎯 Flux de données typique

Exemple: Recherche de tarifs

1. HTTP Request
   ↓
2. RatesController (@application/controllers/rates.controller.ts)
   - Reçoit RateSearchRequestDto
   - Valide avec class-validator
   ↓
3. RateSearchService (@domain/services/rate-search.service.ts)
   - Logique métier pure
   - Utilise CarrierConnectorPort (interface)
   - Utilise CachePort (interface)
   ↓
4. Adapters (@infrastructure/)
   - MaerskConnector implémente CarrierConnectorPort
   - RedisCacheAdapter implémente CachePort
   ↓
5. Response
   - Mapper Domain → DTO
   - Retour JSON via RatesController

Diagramme de dépendances

┌──────────────────────────────────────────────────┐
│              HTTP Client (Frontend)              │
└────────────────────┬─────────────────────────────┘
                     │
                     ↓
┌──────────────────────────────────────────────────┐
│         Controllers (@application)                │
│  - Validation (DTOs)                             │
│  - Error handling                                │
└────────────────────┬─────────────────────────────┘
                     │
                     ↓ (depends on)
┌──────────────────────────────────────────────────┐
│      Domain Services (@domain/services)          │
│  - Pure business logic                           │
│  - No framework dependencies                     │
│  - Uses Ports (interfaces)                       │
└────────────────────┬─────────────────────────────┘
                     │
                     ↓ (implemented by)
┌──────────────────────────────────────────────────┐
│       Infrastructure Adapters                     │
│  - TypeOrmRepository → BookingRepository         │
│  - RedisCache → CachePort                        │
│  - MaerskAPI → CarrierConnectorPort              │
└──────────────────────────────────────────────────┘

---

🌐 Architecture Frontend

Structure en couches

apps/frontend/
├── app/                 # Next.js App Router (Routing)
├── src/
│   ├── components/      # React components (UI Layer)
│   ├── lib/
│   │   ├── api/        # API clients (Infrastructure Layer)
│   │   └── context/    # Global state (Application Layer)
│   ├── hooks/          # Custom hooks (Application Logic)
│   ├── types/          # TypeScript types
│   └── utils/          # Utilities

Séparation des responsabilités

Couche	Responsabilité	Exemples
Pages (app/)	Routing + Layout	app/dashboard/page.tsx
Components	UI Rendering	BookingsTable.tsx, Button.tsx
Hooks	Application Logic	useBookings(), useNotifications()
API Clients	HTTP Communication	api/bookings.ts, api/rates.ts
Context	Global State	auth-context.tsx

Pattern de data fetching

Recommandé: React Query + API clients

// API client
export const fetchBookings = async (filters: BookingFilters) => {
  return apiClient.get<BookingListResponse>('/api/v1/bookings', { params: filters });
};

// Dans un composant
const { data, isLoading } = useQuery({
  queryKey: ['bookings', filters],
  queryFn: () => fetchBookings(filters),
});

---

📊 Modules NestJS - Organisation

Total: 21 modules NestJS

Feature Modules (Application Layer) - 14 modules

Module	Contrôleur	Responsabilité
AuthModule	AuthController	Authentication JWT
RatesModule	RatesController	Rate search
BookingsModule	BookingsController	Booking management
PortsModule	PortsController	Port search
OrganizationsModule	OrganizationsController	Organization CRUD
UsersModule	UsersController	User management
DashboardModule	DashboardController	KPIs & analytics
NotificationsModule	NotificationsController	User notifications
AuditModule	AuditController	Audit logs
WebhooksModule	WebhooksController	Webhook config
GDPRModule	GDPRController	GDPR compliance
AdminModule	AdminController	Admin features
CsvBookingsModule	CsvBookingsController	CSV imports

Infrastructure Modules - 7 modules

Module	Adapter	Implémente
CacheModule	RedisCacheAdapter	CachePort
CarrierModule	MaerskConnector, etc.	CarrierConnectorPort
EmailModule	EmailAdapter	EmailPort
StorageModule	S3StorageAdapter	StoragePort
PdfModule	PdfAdapter	PdfPort
SecurityModule	-	Configuration Helmet/CORS
CsvRateModule	CsvRateLoaderAdapter	CsvRateLoaderPort

---

🔒 Patterns de sécurité

Guards globaux

Configurés dans app.module.ts:

{
  provide: APP_GUARD,
  useClass: JwtAuthGuard, // Toutes les routes protégées par défaut
},
{
  provide: APP_GUARD,
  useClass: CustomThrottlerGuard, // Rate limiting global
}

Contournement pour routes publiques

@Public() // Decorator pour bypass JWT
@Post('login')
async login(@Body() dto: AuthLoginDto) {
  // ...
}

RBAC (Role-Based Access Control)

@Roles('ADMIN', 'MANAGER')
@Get('users')
async getUsers() {
  // Accessible uniquement par ADMIN ou MANAGER
}

---

📈 Métriques d'architecture

Backend

Métrique	Valeur	Cible
Total fichiers TypeScript	~220+	-
Modules NestJS	21	-
Controllers	17	-
Domain Entities	13	-
Domain Value Objects	9	-
Domain Services	7	-
Ports (interfaces)	21	-
Repository Implementations	13	-
Migrations	18	-
Compliance hexagonale	95%	100%
Violations critiques	1	0

Frontend

Métrique	Valeur	Cible
Page routes	31	-
Components React	29	-
Custom hooks	5	-
API client modules	20	-
Type definitions	5	-
Strict TypeScript	❌ Non	✅ Oui

---

🎯 Objectifs de qualité

Backend

• ✅ Domain Layer purity: 100% (1 violation à corriger)
• ✅ Port/Adapter pattern: 100%
• ✅ Repository pattern: 100%
• ✅ DTO validation: 100%
• ✅ Test coverage domain: 90%+

Frontend

• ⚠️ Strict TypeScript: À activer
• ⚠️ Business logic separation: Amélioration nécessaire
• ⚠️ Data fetching consistency: Standardisation requise
• ✅ Component composition: Bon
• ✅ API client coverage: 100%

---

📚 Références

• CLAUDE.md - Guide complet d'implémentation
• docs/backend/cleanup-report.md - Rapport de nettoyage backend
• docs/frontend/cleanup-report.md - Rapport de nettoyage frontend
• docs/decisions.md - Décisions architecturales

---

Dernière mise à jour: 2025-12-22 Prochaine révision: Après correction de la violation domain layer