Aller au contenu
Meubles Morinière

Le codeArchitecture4 min de lecture

Rangement du code

Les trois couches de chaque application, le sens des imports, les modules et leurs vraies dépendances, et pourquoi il y a ces frontières.

Chaque application range son code en trois couches, au-dessus des paquets. C’est la fabrique ESLint commune qui impose le sens des imports. Si un import passe une frontière, le lint échoue et son message dit laquelle.

  1. app/

    Les routes : pages, mises en page, gestionnaires. Elles composent ce que les modules lisent et font.

    importemodules/shared/les paquets
    jamaisPrismale client généré
  2. modules/<métier>/

    Le métier, un dossier par couche : data, services, actions, components, lib, schemas… 26 modules dans l’ERP, 14 dans le site.

    importeshared/les paquetssite : les modules des couches précédentes
    jamaisapp/ERP : un autre module
  3. shared/

    Ce que deux modules, ou un module et une route, partagent : environnement, client Prisma, relais des paquets, kit d’interface.

    importeles paquets
    jamaismodules/app/
  4. packages/*

    Ce que les applications partagent entre elles : 9 paquets.

    imported’autres paquets
    jamaisune application
Chaque « jamais » est une erreur de lint (packages/config/eslint.mjs). Les nombres sont comptés dans le dépôt à chaque build.

Où ranger le code

Chaque app a trois couches, dont ESLint garde les frontières : app/ compose, modules/ porte les métiers, shared/ ce qui sert à tous.

  • app/ : les routes, et à côté d'elles ce qu'elles seules utilisent, dans des dossiers privés (préfixe _, ignorés du routeur). _components/ pour les composants React, _lib/ pour le reste : modèles de vue, calculs, lectures composées. Un fichier se range au plus proche ancêtre commun de ses routes : app/(site)/compte/_components/ sert les pages du compte, app/(site)/_components/ tout le site public (barre de navigation, destinations de la recherche), app/_components/ aussi la page d'attente hors du groupe (site) (données structurées). Une route n'importe jamais le dossier privé d'une route sœur : ce qui sert à deux routes remonte.
  • modules/<métier>/ : un dossier par couche (actions, components, constants, data, hooks, lib, schemas, services, stores, types). Un hook va dans hooks/, une logique sans rendu dans lib/, même quand un seul composant s'en sert. Un module n'importe jamais app/ ; dans l'ERP, il n'importe aucun autre module, et dans le site seulement ceux des couches qui précèdent la sienne (voir « Modules »). Le site impose en plus le chemin relatif à l'intérieur d'un module : l'alias @/modules/<autre> n'y sert qu'à franchir une frontière.
  • shared/ : le code qu'au moins deux modules, ou un module et une route, partagent. Ce qu'une seule route utilise descend dans son dossier privé.

Les tests vivent dans un __tests__/ voisin du fichier testé, routes comprises (devis/[token]/pdf/__tests__/route.test.ts).

Modules

Dans chaque app, app/ compose, modules/ porte le métier, shared/ l'outillage commun ; shared/ n'importe aucun module. Dans l'ERP, un module n'importe jamais un autre module. Le site range les siens en couches (MODULE_LAYERS, apps/site/eslint.config.mjs) : un module importe ceux des couches qui précèdent la sienne, jamais ceux de sa couche ni des suivantes. La fiche d'une pièce montre les cartes du catalogue et y renvoie, la commande lit le panier, le panier lit les promotions et la livraison ; rien ne remonte. Un module nouveau du site prend sa place dans une couche, sans quoi le lint refuse de démarrer.

Voici les modules du site, avec les imports qui existent vraiment entre eux :

Les modules du site et leurs importscart importe catalogue, promotions, shipping. checkout importe cart, promotions, shipping. products importe catalogue, closures, shipping. quotes importe shipping. account, catalogue, closures, collections, orders, projects, promotions, shipping, support, wishlist n’importent aucun autre module.closurespromotionsshippingaccountcatalogueprojectsquotessupportcartcollectionsproductswishlistcheckoutorders
Imports relevés dans modules/ à chaque build de cette documentation, rangés selon MODULE_LAYERS (apps/site/eslint.config.mjs) : un module n’importe que ceux des couches du dessous. Survoler un module isole ses flèches.

Et ceux de l’ERP. Aucun n’en importe un autre :

  • auth
  • brands
  • categories
  • closures
  • collections
  • colors
  • customers
  • decisions
  • homepage
  • materials
  • media
  • monitoring
  • orders
  • payments
  • products
  • promotions
  • purchase-orders
  • push
  • quotes
  • refunds
  • shipping
  • store
  • supplier-invoices
  • suppliers
  • users
  • variants
Les 26 modules de l’ERP, relevés à chaque build de cette documentation : aucun n’en importe un autre.

Pourquoi ces frontières

Dans l’ERP, on peut lire, retoucher ou retirer un module sans toucher aux autres, parce qu’aucun autre module n’en dépend. Pour retirer un métier, on retire son dossier, ses routes et son entrée dans le menu, et on n’a pas à chercher qui l’importe. Quand deux modules ont besoin de la même chose, elle descend dans shared/, et rien dans shared/ n’importe un module. Du coup, le graphe des imports de l’ERP n’a pas d’arête, et il ne peut pas y avoir de cycle.

Sur le site, c’est différent. Il a des couches, parce qu’une boutique en ligne est faite de vues qui se composent. La fiche d’un meuble montre les cartes du catalogue, le panier calcule le port et les promotions, et la commande relit le panier. Si on avait interdit ces imports, ces vues seraient descendues dans shared/, loin de leur métier. Avec les couches, on garde la composition et il n’y a toujours pas de cycle, parce qu’un module n’importe que ceux des couches d’en dessous. Le graphe ci-dessus le montre tel que le code l’écrit.

Une route ne fait que composer, elle ne touche pas à la base. app/ lit avec les lectures de modules/*/data et écrit avec une server action. Dans l’ERP, une lecture qui touche une donnée sensible, et chaque get-admin-*, commence par la garde de session (requireAdminReader()), et un test l’impose (apps/erp/test/admin-reads.regression.test.ts). Donc une page ne peut pas lire une donnée sensible sans passer par une lecture gardée. Et comme toute lecture passe par une fonction, les tests la simulent par son chemin.

Ces frontières ont un coût :

  • shared/ grossit, et il n’y a pas que de l’outillage dedans. Tout ce que deux modules de l’ERP partagent y descend, donc on y trouve aussi du métier (la facturation, apps/erp/shared/invoicing).
  • Les couches du site se maintiennent à la main. Un nouveau module doit prendre sa place dans MODULE_LAYERS, sinon le lint refuse de démarrer. Et quand on a besoin d’une couche du dessus, il faut déplacer du code, on ne peut pas juste écrire l’import.
  • Une règle de lint ne voit que les imports. Deux modules peuvent encore dépendre l’un de l’autre par la base, s’ils lisent les mêmes tables. Dans ce cas, ce sont les contraintes et les gardes de la base (Données) qui protègent ce que les frontières du code ne voient pas.

Sur cette page