Structurer un Codebase : Par Couche, Par Fonctionnalité ou Par Domaine ?

Vous ouvrez un nouveau projet et la première chose que vous faites — avant d'écrire une seule ligne de logique — c'est créer un dossier. Peut-être qu'il s'appelle controllers/. Peut-être qu'il s'appelle orders/. Dans les deux cas, ce choix tranquille est déjà une décision architecturale, et il façonnera silencieusement tout ce qui suit : la vitesse à laquelle un nouveau coéquipier prend ses marques, le nombre de fichiers que vous touchez quand une seule fonctionnalité change, et si dans six mois votre codebase se lit comme votre métier ou comme votre framework.

Cet article est un tour pratique des trois approches principales — par couche, par fonctionnalité et screaming (par domaine) — avec des compromis honnêtes à chaque taille d'entreprise. Aucune réponse unique ne gagne dans toutes les situations, mais vous repartirez avec un modèle mental clair pour choisir délibérément plutôt que par défaut.

Pourquoi la structure des dossiers est une décision architecturale, pas du pinaillage

Les gens balaient la structure des dossiers d'un revers de main en disant « c'est juste de l'organisation ». C'est bien plus que ça. La façon dont vous regroupez le code contrôle trois choses qui s'avèrent énormément importantes :

• Couplage. Quand du code qui change ensemble vit loin les uns des autres, chaque petite mise à jour devient une expédition entre dossiers. Quand il vit ensemble, les changements connexes se regroupent en un seul endroit.
• Découvrabilité. Un développeur qui ne connaît pas votre codebase va demander : « où est le code pour la facturation ? » La réponse à cette question — un dossier, ou cinq dossiers éparpillés — détermine le temps d'intégration.
• Rayon d'impact. Combien de fichiers devez-vous ouvrir pour livrer une nouvelle fonctionnalité, ou pour supprimer en toute sécurité une ancienne ? La structure contraint ce rayon d'impact ou le laisse se propager sans limites.

La Loi de Conway — l'observation que les systèmes logiciels reflètent les structures de communication des équipes qui les construisent — s'applique ici aussi. Si votre équipe est organisée autour de capacités métier (une squad paiements, une squad commandes), une structure par fonctionnalité semblera naturelle et imposera les bonnes frontières. Une structure par couche se battra contre vous.

Par couche : le défaut familier

L'organisation par couche regroupe les fichiers par leur rôle technique. Un projet Node ou Spring Boot typique finit par ressembler à quelque chose comme ça :

src/
├─ controllers/
│  ├─ OrderController.ts
│  ├─ UserController.ts
│  └─ BillingController.ts
├─ services/
│  ├─ OrderService.ts
│  ├─ UserService.ts
│  └─ BillingService.ts
├─ repositories/
│  ├─ OrderRepository.ts
│  ├─ UserRepository.ts
│  └─ BillingRepository.ts
└─ models/
   ├─ Order.ts
   ├─ User.ts
   └─ Invoice.ts

Tous les tutoriels de frameworks web aboutissent ici. Rails le fait, le starter Spring Boot le fait, les générateurs Express le font. Cette familiarité est son principal atout.

Là où la structure par couche brille :

• Les petites apps avec deux ou trois fonctionnalités — la structure est si plate qu'elle a peu d'importance.
• Les équipes où tout le monde travaille sur toutes les fonctionnalités ; la couche est l'unité de spécialisation.
• Les prototypes et les outils internes où la rapidité de mise en place initiale prime sur la clarté à long terme.

Là où la structure par couche fait mal :

• Une seule fonctionnalité est dispersée dans plusieurs dossiers. Ajouter une fonctionnalité « remboursement » signifie toucher controllers/, services/, repositories/ et models/. C'est quatre dossiers pour ce qui est conceptuellement une seule chose.
• Supprimer une fonctionnalité est un projet d'archéologie. Comment savoir quels fichiers dans services/ appartiennent à la facturation versus aux commandes ? Le nom du dossier ne vous le dit pas.
• Les conflits de fusion se multiplient. Chaque modification de fonctionnalité touche les mêmes fichiers au niveau des couches, provoquant des collisions quand deux développeurs travaillent en parallèle.

Par fonctionnalité : un changement vit dans un seul dossier

L'organisation par fonctionnalité regroupe les fichiers selon la tranche du produit qu'ils servent. Les couches techniques (controller, service, model) existent toujours — elles vivent juste à l'intérieur de chaque dossier de fonctionnalité au lieu d'être au premier niveau :

src/
├─ orders/
│  ├─ OrderController.ts
│  ├─ OrderService.ts
│  ├─ OrderRepository.ts
│  └─ Order.ts
├─ billing/
│  ├─ BillingController.ts
│  ├─ BillingService.ts
│  ├─ BillingRepository.ts
│  └─ Invoice.ts
├─ auth/
│  ├─ AuthController.ts
│  ├─ AuthService.ts
│  └─ User.ts
└─ shared/
   ├─ database.ts
   ├─ logger.ts
   └─ Money.ts

Là où la structure par fonctionnalité brille :

• Un changement vit dans un seul dossier. Ajouter un flux de remboursement signifie ajouter des fichiers dans billing/ — aucun autre dossier n'est touché. Le rayon d'impact est petit et contenu.
• Supprimer une fonctionnalité est simple. Supprimez le dossier. Si quelque chose en dehors importe encore depuis lui, votre IDE vous le dira immédiatement.
• La propriété est évidente. L'équipe paiements possède billing/ ; l'équipe identité possède auth/. Les outils de monorepo et les règles de revue de code peuvent l'imposer mécaniquement.
• L'intégration est plus rapide. Un nouveau développeur travaillant sur les commandes ne lit que orders/. Il n'a pas besoin de comprendre tout le codebase d'abord.

Là où la structure par fonctionnalité nécessite de l'attention :

• Le placement du code partagé est gênant. Le type Money est utilisé à la fois par orders/ et billing/. Doit-il vivre dans orders/ ? Ça semble bizarre. Il finit dans shared/ — qui peut lui-même devenir un second tiroir à tout si personne ne le possède.
• Les dépendances entre fonctionnalités nécessitent de la discipline. Si orders/OrderService.ts importe directement depuis billing/BillingService.ts, vous avez créé un couplage que la structure des dossiers ne peut pas voir. Les équipes utilisent des règles de lint (eslint-plugin-import/no-restricted-paths) ou des outils de frontières de modules (Nx, modules NestJS) pour les rendre explicites.

Screaming Architecture : que dit votre premier niveau ?

Uncle Bob (Robert C. Martin) a inventé le terme Screaming Architecture dans un célèbre billet de blog : « Que crie l'architecture de votre application ? Quand vous regardez la structure du répertoire de premier niveau, et les fichiers sources dans le package de plus haut niveau ; crient-ils : Système de soins de santé, ou Système de comptabilité, ou Système de gestion des stocks ? Ou crient-ils : Rails, ou Spring/Hibernate, ou ASP.Net ? »

L'intuition est élégante : si vos dossiers de premier niveau sont controllers/, models/, views/, votre codebase crie framework MVC. Le framework est un outil — il ne devrait pas être la première chose qu'un lecteur rencontre.

La Screaming Architecture (aussi appelée par domaine) pousse la structure par fonctionnalité un cran plus loin. Non seulement les fonctionnalités sont au premier niveau — mais les noms de ces fonctionnalités sont tirés directement du langage métier (le Langage Ubiquitaire du Domain-Driven Design), et non des rôles techniques :

// Crie « plateforme e-commerce »
src/
├─ catalog/          // le concept de domaine : un catalogue de produits
├─ ordering/         // le concept de domaine : passer et suivre des commandes
├─ fulfillment/      // le concept de domaine : préparation, emballage, expédition
├─ payments/         // le concept de domaine : débits, remboursements, factures
└─ identity/         // le concept de domaine : comptes, auth, permissions

// Comparez avec l'alternative qui crie « framework » :
src/
├─ controllers/      // crie « MVC »
├─ models/           // crie « ORM »
├─ views/            // crie « moteur de templates »
└─ services/         // crie « pattern couche de service »

À l'intérieur de chaque dossier de domaine, la mise en page interne est laissée à l'équipe — et c'est bien. La promesse clé est que le premier niveau communique le métier, pas l'infrastructure. Un nouveau développeur (ou votre directeur technique, ou un expert métier du côté business) peut lire les dossiers de premier niveau et comprendre ce que fait le système sans savoir comment il est construit.

Comparaison côte à côte

Voici une évaluation honnête selon cinq dimensions pratiques :

Le hybride pragmatique sur lequel la plupart des bonnes équipes atterrissent

En pratique, les meilleures équipes ne choisissent pas une seule approche et ne l'appliquent pas partout avec une cohérence religieuse. Elles utilisent un hybride pragmatique : dossiers de fonctionnalité ou de domaine au premier niveau, petites couches techniques à l'intérieur de chacun.

Cet hybride vous offre le meilleur des deux mondes :

• Le premier niveau crie votre métier — les nouveaux venus savent immédiatement que c'est une app e-commerce, pas un squelette MVC générique.
• Chaque fonctionnalité est autonome — un changement dans le flux de facturation ne touche que billing/.
• Les couches techniques existent toujours à l'intérieur de chaque dossier, donc les développeurs qui pensent en termes de MVC ou de couches Clean Architecture ne sont pas perdus. Ils regardent juste à l'intérieur du dossier de fonctionnalité.
• Un dossier shared/ contient les préoccupations vraiment transverses (un objet-valeur Money, un logger, une connexion de base de données). La règle clé : si quelque chose est ajouté à shared/, il doit être extrait et possédé délibérément — et non déversé là comme échappatoire.

À grande échelle : frontières imposées et monorepos

À mesure qu'un codebase grandit et que plusieurs équipes contribuent, les conventions de dossiers seules ne suffisent plus — un développeur peut toujours traverser une frontière avec un import relatif rapide. L'étape suivante consiste à rendre les frontières imposées :

• Les modules NestJS rendent les dépendances inter-modules explicites : vous n'avez accès qu'à ce qu'un autre module exporte. Un import qui traverse une frontière de module sans passer par l'API publique est une erreur de compilation.
• Les règles de frontière Nx vous permettent de déclarer quelles fonctionnalités ou bibliothèques sont autorisées à dépendre de quelles autres, puis de l'imposer comme erreur de lint en CI.
• Les Monorepos vont le plus loin : chaque domaine (orders, billing, auth) devient son propre package avec son propre package.json, ses propres tests et ses exports publiés explicites. Turborepo et Nx sont les outils dominants dans l'écosystème JavaScript pour gérer ça. La structure ressemble moins à un arbre de dossiers et plus à un graphe de packages — mais l'idée sous-jacente est identique : regrouper par capacité métier, rendre les frontières explicites, les imposer mécaniquement.

Passer à un monorepo n'est pas toujours nécessaire. Beaucoup d'équipes fonctionnent heureusement avec un seul package et une structure hybride bien disciplinée pendant des années. Tournez-vous vers les outils de monorepo quand le couplage inter-équipes devient une vraie douleur — pas de façon préventive.

Recommandations par taille d'entreprise

La bonne structure dépend de l'endroit où votre organisation en est aujourd'hui. Voici une recommandation directe pour chaque stade :

Voir la différence : ce qui s'allume quand vous livrez une fonctionnalité

La façon la plus concrète de ressentir la différence entre par couche et par fonctionnalité est de demander : quelles boîtes s'allument quand j'ajoute une nouvelle fonctionnalité ?

Ce diagramme est l'argument le plus clair pour le regroupement par fonctionnalité. Le « rayon d'impact » n'est pas un concept abstrait — c'est le nombre de dossiers et de fichiers que vous ouvrez dans une seule pull request. Les relecteurs, les pipelines CI et git blame fonctionnent tous mieux quand un changement de fonctionnalité est un bloc cohésif, pas une traînée à travers chaque couche.

Maintenant que vous avez vu comment structurer le code à l'intérieur d'un seul service, la question naturelle suivante est ce qu'il faut faire quand un seul service ne suffit plus. Continuez la lecture : Monolithe → Microservices.