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

# 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
Architecture hexagonale + conventions	CLAUDE.md
Vue d'ensemble système	docs/architecture/overview.md
Schéma BDD (21 tables)	docs/architecture/database.md
Démarrage rapide	docs/getting-started/quick-start.md

---

Commandes de développement

# 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