ADR-0001 — Adopter NestJS en Clean Architecture pour tous les services backend
Status : Accepted Date : 2026-02 (rétroactif) Deciders : équipe plateforme Nex Tickets : —
Contexte
À la création de la plateforme Nex, plusieurs frameworks Node.js étaient envisageables pour les microservices : Express nu, Fastify, NestJS, AdonisJS. Les besoins exprimés :
- Architecture modulaire pour faire évoluer la plateforme sans réécrire.
- Typage fort (TypeScript strict mode) pour limiter les bugs en production.
- Standardisation entre les 11+ microservices prévus.
- Convention reconnue côté audit pour faciliter l’onboarding de partenaires.
Décision
Tous les microservices backend sont implémentés en NestJS, organisés en Clean Architecture avec quatre couches :
- Domain — entités, value objects, exceptions métier.
- Application — use-cases (orchestrateurs), DTOs, ports.
- Infrastructure — repositories TypeORM, clients HTTP, adapters externes.
- Presentation — controllers HTTP, guards, pipes.
Les boundaries de couches sont strictes : un controller ne peut pas appeler un repository directement, il passe par un use-case.
Conséquences
Positives
- Tests unitaires faciles côté use-cases (pas de dépendance infrastructure).
- Onboarding rapide d’un dev expérimenté NestJS.
- Patterns reconnus (DI, decorators, modules) qui structurent le code.
- Swagger auto-généré via
@nestjs/swaggersur 10 services sur 11.
Négatives / risques
- Verbosité (beaucoup de fichiers et boilerplate pour des cas simples).
- Apprentissage initial pour les devs venant d’Express nu.
- Risque d’over-engineering sur des use-cases triviaux (mitigation : règle « max 70 lignes logiques par fonction » dans
dev/coding-standards).
Alternatives écartées
- Express + structure ad-hoc — flexibilité maximale mais zéro convention entre services, drift garanti à 11 services.
- Fastify — performance supérieure mais écosystème plus pauvre, pas de Clean Architecture out-of-the-box.
- AdonisJS — full-stack mais opinions trop fortes sur ORM (Lucid), incompatible avec TypeORM.
Suivi
- Tous les services dans
services/respectent la structure. Voir /architecture/services-catalog. - Les conventions de code sont documentées dans /dev/coding-standards (à enrichir).