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
```typescript
// 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
```typescript
// 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`:
```typescript
{
  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

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

### RBAC (Role-Based Access Control)

```typescript
@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](../CLAUDE.md) - Guide complet d'implémentation
- [docs/backend/cleanup-report.md](backend/cleanup-report.md) - Rapport de nettoyage backend
- [docs/frontend/cleanup-report.md](frontend/cleanup-report.md) - Rapport de nettoyage frontend
- [docs/decisions.md](decisions.md) - Décisions architecturales

---

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