# Xpeditis — Maritime Freight Booking Platform

Plateforme B2B SaaS permettant aux transitaires de rechercher, comparer et réserver du fret maritime en temps réel.

---

## Démarrage rapide

```bash
# 1. Installer les dépendances
npm run install:all

# 2. Démarrer l'infrastructure (PostgreSQL + Redis + MinIO)
docker-compose up -d

# 3. Configurer l'environnement
cp apps/backend/.env.example apps/backend/.env
cp apps/frontend/.env.example apps/frontend/.env.local

# 4. Exécuter les migrations
cd apps/backend && npm run migration:run && cd ../..

# 5. Démarrer les serveurs
npm run backend:dev    # http://localhost:4000 · Swagger: /api/docs
npm run frontend:dev   # http://localhost:3000
```

---

## Structure du projet

```
xpeditis/
├── apps/
│   ├── backend/          # NestJS 10 — Architecture hexagonale
│   │   └── src/
│   │       ├── domain/          # Logique métier pure (TypeScript)
│   │       ├── application/     # Controllers, DTOs, Guards
│   │       └── infrastructure/  # TypeORM, Redis, S3, Email, Stripe
│   └── frontend/         # Next.js 14 App Router
│       ├── app/[locale]/        # Routing i18n (fr, en)
│       └── src/                 # Components, hooks, lib/api
├── docker-compose.yml    # PostgreSQL 15 + Redis 7 + MinIO
└── docs/                 # Documentation complète
```

---

## Documentation

| Sujet | Fichier |
|-------|---------|
| Index complet | [docs/README.md](docs/README.md) |
| Architecture hexagonale + conventions | [CLAUDE.md](CLAUDE.md) |
| Vue d'ensemble système | [docs/architecture/overview.md](docs/architecture/overview.md) |
| Schéma BDD (21 tables) | [docs/architecture/database.md](docs/architecture/database.md) |
| Démarrage rapide | [docs/getting-started/quick-start.md](docs/getting-started/quick-start.md) |

---

## Commandes de développement

```bash
# Backend
npm run backend:dev       # Serveur avec hot-reload
npm run backend:test      # Tests unitaires Jest
npm run backend:lint      # ESLint
npm run backend:build     # Build production

# Frontend
npm run frontend:dev      # Serveur avec hot-reload
npm run frontend:test     # Tests unitaires Jest
npm run frontend:lint     # ESLint
cd apps/frontend && npm run test:e2e  # Playwright E2E

# Qualité
npm run format            # Prettier (tous les fichiers)

# Base de données
cd apps/backend
npm run migration:generate -- src/infrastructure/persistence/typeorm/migrations/NomMigration
npm run migration:run
npm run migration:revert
```

---

## Stack technique

### Backend

| Composant | Technologie |
|-----------|-------------|
| Framework | NestJS 10 + TypeScript 5 (strict) |
| Base de données | PostgreSQL 15 + TypeORM |
| Cache | Redis 7 (ioredis) |
| Auth | JWT (15min) + Refresh + OAuth2 + API Keys (Argon2) |
| Temps réel | Socket.IO |
| Email | Nodemailer + MJML |
| Paiements | Stripe |
| Stockage | S3/MinIO |
| Logging | nestjs-pino |
| Monitoring | Sentry |

### Frontend

| Composant | Technologie |
|-----------|-------------|
| Framework | Next.js 14 App Router + TypeScript |
| Styling | Tailwind CSS + shadcn/ui (Radix UI) |
| State serveur | TanStack Query v5 |
| Tables | TanStack Table v8 + Virtual |
| Formulaires | react-hook-form + zod |
| Temps réel | Socket.IO client |
| i18n | next-intl (fr, en) |
| Graphiques | recharts |

---

## Carriers intégrés

| Carrier | Code | Statut |
|---------|------|--------|
| Maersk | MAEU | Connecteur API |
| MSC | MSCU | Connecteur API |
| CMA CGM | CMDU | Connecteur API |
| Hapag-Lloyd | HLCU | Connecteur API |
| ONE | ONEY | Connecteur API |
| SSC Consolidation | — | CSV |
| ECU Worldwide | — | CSV + API |
| TCC Logistics | — | CSV |
| NVO Consolidation | — | CSV |

---

## Fonctionnalités principales

- **Recherche tarifs** : FCL (carriers API + cache Redis 15min) + LCL CSV
- **Réservation standard** : workflow 4 étapes, numéro WCM-YYYY-XXXXXX
- **Réservation CSV + Portail Carrier** : magic link, accept/reject
- **Dashboard** : KPI, graphiques, table interactive virtuelle
- **Auth** : JWT, OAuth2 (Google/Microsoft), API Keys, RBAC (5 rôles)
- **Abonnements** : Stripe (FREE/BRONZE/SILVER/GOLD/PLATINIUM)
- **Notifications** : WebSocket temps réel + webhooks tiers
- **GDPR** : export/suppression des données utilisateur
- **Blog** : gestion de contenu bilingue (fr/en)
- **Audit** : journal d'audit de toutes les actions

---

*Architecture hexagonale — NestJS 10 + Next.js 14 — PostgreSQL 15 + Redis 7*