The codeArchitecture(in French)4 min read
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.
Not translated yet
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.
app/
Les routes : pages, mises en page, gestionnaires. Elles composent ce que les modules lisent et font.
importemodules/shared/les paquetsjamaisPrismale client généré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édentesjamaisapp/ERP : un autre moduleshared/
Ce que deux modules, ou un module et une route, partagent : environnement, client Prisma, relais des paquets, kit d’interface.
importeles paquetsjamaismodules/app/packages/*
Ce que les applications partagent entre elles : 9 paquets.
imported’autres paquetsjamaisune application
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 danshooks/, une logique sans rendu danslib/, même quand un seul composant s'en sert. Un module n'importe jamaisapp/; 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 :
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
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.