Structure et cycle d'une requête

Le backend est un monolithe modulaire Express 5 écrit en TypeScript. Il expose une API REST, un serveur Socket.IO et, selon la configuration, des workers BullMQ et les services de lecture de la blockchain. Cette page décrit l'organisation du dossier backend/src, l'ordre exact des middlewares appliqués à chaque requête et la façon dont les deux points d'entrée démarrent et s'arrêtent. Le choix du monolithe est justifié dans l'ADR 0001.

#Arborescence de backend/src

backend/src/
├── app.ts                  application Express : middlewares et montage des routeurs
├── server.ts               point d'entrée de l'API (HTTP + Socket.IO + workers optionnels)
├── worker.ts               point d'entrée du process worker (BullMQ + indexeur + keeper)
├── api/                    un dossier par module métier
│   ├── system/             sondes de santé et configuration client
│   ├── auth/  lottery/  marketplace/  partners/  user/  analytics/  admin/
│   └── webhooks/           webhook blockchain signé (mode simulé)
├── blockchain/             client RPC, passerelle du contrat, indexeur, keeper, file d'actions, ABI
├── config/                 env, Prisma, Redis, Nodemailer, Swagger
├── middlewares/            auth, RBAC, âge, validation Zod, idempotence, rate limiting, corps JSON, erreurs, contexte
├── observability/          métriques Prometheus, contexte de requête, arrêt propre
├── queues/                 producteurs BullMQ (emails, ledger) et options communes
├── workers/                consommateurs BullMQ et indexeur du webhook simulé
├── services/               services transverses (sessions, OTP, TOTP, ledger, email, S3, blockchain)
├── socket/                 serveur Socket.IO, authentification, événements, relais Redis
├── templates/emails/       8 gabarits HTML des emails transactionnels
├── types/                  types partagés (réponses API, JWT, événements Socket.IO)
└── utils/                  chiffrement, logger, pagination, format des réponses

Chaque module de api/ suit le même découpage en cinq fichiers. Seuls system (un seul fichier de routes) et webhooks (signature et contrôleur séparés) s'en écartent.

Les services et repositories sont des classes instanciées une seule fois et exportées par défaut (export const lotteryService = new LotteryService()). Les tests remplacent les modules prisma.config et redis.config par des doublures en mémoire (voir Tests).

#Cycle d'une requête

L'ordre ci-dessous est celui de backend/src/app.ts. Il détermine ce qui est journalisé, mesuré, limité ou court-circuité.

flowchart TD
    A["Requête entrante"] --> B["requestContextMiddleware : X-Request-Id et contexte"]
    B --> C["httpMetricsMiddleware : histogramme et requêtes en cours"]
    C --> D["helmet : en-têtes de sécurité"]
    D --> E["cors : origines autorisées"]
    E --> F["globalJsonParser 1 Mo, sauf envoi de pièce d'identité, et urlencoded"]
    F --> G{"Route système ou /metrics ?"}
    G -- oui --> G1["Réponse /health, /api/config, /metrics"]
    G -- non --> H{"MAINTENANCE_MODE ?"}
    H -- "oui, hors /api/admin" --> H1["503 Retry-After 300"]
    H -- non --> I["globalRateLimiter : 300 requêtes par 15 min et par IP"]
    I --> J{"/api/docs ?"}
    J -- oui --> J1["Swagger UI"]
    J -- non --> K["Routeur /api/v1 puis /api"]
    K --> L["Middlewares de route : authRateLimiter, authenticate, requireRoles, idempotency, validate"]
    L --> M["Contrôleur, service, repository"]
    M --> N["sendSuccess"]
    K -- "aucune route" --> O["notFoundHandler 404"]
    L -- "next(error)" --> P["errorHandler"]
    M -- "next(error)" --> P

#Middlewares globaux

#Middlewares de route

Ils sont déclarés route par route dans les fichiers *.routes.ts, toujours dans cet ordre quand ils sont présents.

idempotency est placé avant validate : une réponse 400 de validation est mémorisée comme les autres réponses inférieures à 500. Une nouvelle tentative avec la même clé et un corps corrigé rejoue donc le 400 pendant 24 heures. Il faut générer une nouvelle clé après une erreur de validation.

#Points d'entrée

#server.ts

backend/src/server.ts démarre l'API :

1. crée le serveur HTTP Node autour de app, avec keepAliveTimeout = HTTP_KEEP_ALIVE_TIMEOUT_MS, headersTimeout = HTTP_KEEP_ALIVE_TIMEOUT_MS + 1000 et requestTimeout = HTTP_REQUEST_TIMEOUT_MS ;
2. attache Socket.IO (initSocketServer) et démarre l'abonnement au relais Redis des événements temps réel (startSocketEventBridge) ;
3. si RUN_WORKERS=true, démarre les workers BullMQ (startWorkers) et, en mode onchain, l'indexeur et le keeper (startChainServices) ;
4. enregistre les étapes d'arrêt, puis écoute sur PORT.

En développement, npm run dev lance tsx watch src/server.ts. En production, npm run compile produit dist/ et npm start exécute node dist/src/server.js.

#worker.ts

backend/src/worker.ts démarre uniquement les traitements de fond : workers BullMQ (emails, ledger, chain-actions) et services de chaîne. Il ne sert aucune route de l'API. Il ouvre un petit serveur HTTP sur PORT + 1 qui répond à /health/live (200, ou 503 pendant l'arrêt) et /metrics. Si aucun worker n'a pu être créé, le process s'arrête avec le code 1.

Dans la stack Docker, le service backend tourne avec RUN_WORKERS=false et le service worker exécute dist/src/worker.js avec une sonde sur le port 2054. La répartition des traitements est détaillée dans Files et workers.

#Arrêt propre

backend/src/observability/shutdown.ts enregistre les gestionnaires de SIGTERM, SIGINT, unhandledRejection et uncaughtException.

sequenceDiagram
    participant OS as "Orchestrateur"
    participant P as "Process"
    participant L as "lifecycle"
    OS->>P: SIGTERM
    P->>L: markShuttingDown
    Note over P: /health/ready et /health/live du worker renvoient 503
    P->>P: minuteur SHUTDOWN_TIMEOUT_MS
    P->>P: étapes propres au point d'entrée
    P->>P: files BullMQ, client RPC, Prisma, Redis
    P->>OS: exit 0

Les étapes sont exécutées l'une après l'autre. Une étape en erreur est journalisée en warn et n'interrompt pas les suivantes.

Si l'ensemble dépasse SHUTDOWN_TIMEOUT_MS (25 secondes par défaut), le process sort avec le code 1. Le stop_grace_period de 30 secondes des services Docker laisse cette marge. Une promesse rejetée non gérée est journalisée et ne provoque l'arrêt qu'en production ; une exception non capturée arrête toujours le process avec le code 1.

#Pour aller plus loin

• Configuration : chargement et validation de l'environnement.
• Modules métier : routes, règles et effets de bord.
• Ajouter un endpoint : mise en pratique du découpage en cinq fichiers.