Architecture — les choix et leur pourquoi¶
Ce document argumente les partis pris techniques de l'API : ce qu'on a choisi, ce qu'on a écarté, et pourquoi. Il complète les rules (.cursor/rules/), qui restent le contrat opérationnel — concises, optimisées pour la review et les agents. Ici on garde la mémoire des décisions ; là-bas on garde la règle applicable.
Document vivant
Rédigé à partir de l'état du code en juin 2026, module de référence : project-financing-request. À compléter par l'équipe au fil des décisions.
__new/ : la cible, et le legacy autour¶
src/__new/ est le début de l'architecture en modules par feature. Tout ce qui y entre suit l'intégralité des conventions ; le reste de la codebase est du legacy sur lequel on met volontairement moins d'effort de standardisation.
Deux objectifs structurants :
- Éliminer un maximum de dépendances à TypeORM et à NestJS. On souhaite se débarrasser des deux à terme : TypeORM est déjà remplacé par Kysely dans la stack cible, et NestJS est réduit au strict minimum HTTP (routing, guards, exception filter) — pas de modules Nest, pas de DI, pas de décorateurs hors controllers.
- Migrer par attrition (pattern strangler) : pas de big-bang. Refactorer du code legacy = le migrer dans
__new/. On migre ce qu'on touche, quand on le touche.
La stack cible en un coup d'œil¶
| Brique | Choix | Remplace | Argumenté dans |
|---|---|---|---|
| Découpage | Modules par feature, flat | Couches techniques globales | Modules & couches |
| Erreurs | Result + apiErr, no-throw |
HttpException throwées |
Erreurs & Result |
| Accès DB | Kysely, types dérivés de zod | TypeORM + SQL brut | Accès aux données |
| Migrations | Flyway SQL, forward-only | Migrations ORM | Migrations |
| Validation | zod v4, source unique des types | idonttrustlikethat | Validation |
| Nommage | Sémantique déterministe | — | Nommage |
La stack est à privilégier pour tout nouveau module, dans la limite du raisonnable : elle est d'abord adaptée aux modules au code indépendant, car l'interop avec TypeORM et idtlt n'est pas optimale. À terme, tout converge vers elle — elle est simple, typée et très DX friendly.
Comment lire ces pages¶
Chaque page suit le même squelette : la décision, le contexte, pourquoi, les alternatives écartées, les limites assumées et la trajectoire. Les limites sont documentées au même titre que les choix : une entorse connue et assumée vaut mieux qu'une règle silencieusement contournée.