Le projetCompétences et preuves3 min de lecture
Architecture
Ce sont des outils qui font respecter les frontières du code, sans compter sur la discipline : des dépendances à sens unique, deux applications qui ne divergent plus, un contrat partagé, des décisions écrites.
Plusieurs sessions travaillent sur le projet en même temps, humaines ou non. Une consigne ne suffit pas à les empêcher de casser l’architecture. Du coup, pour chaque frontière décrite ici, il y a un outil qui la vérifie et qui refuse le commit.
Les dépendances vont dans un seul sens, et le lint refuse le reste
Dans une application de plusieurs centaines de milliers de lignes, il suffit d’un import de trop pour créer un cycle. Et après, on se retrouve avec un module que personne n’ose plus toucher. La règle, c’est « app/ compose, modules/ porte le métier, shared/ ne dépend de rien ». Mais elle ne vaut quelque chose que si on la vérifie.
C’est la configuration ESLint commune qui s’en charge. Pour chaque application, elle calcule ce que chaque module a le droit d’importer. Dans l’ERP, un module n’importe aucun autre module, et ce qui se partage descend dans shared/. Sur le site, les modules sont rangés en couches. Un module peut importer ceux des couches d’avant, mais pas ceux de sa propre couche ni ceux des couches d’après. Et si on oublie de ranger un module dans une couche, c’est la configuration elle-même qui échoue.
packages/config/eslint.mjs · lignes 273–295/**
* Les modules que chaque module peut importer. Sans `moduleLayers`, aucun : un module n'importe
* jamais un autre module. Avec, un module importe ceux des couches qui précèdent la sienne, jamais
* ceux de sa couche ni des suivantes : les dépendances vont dans un seul sens, sans cycle possible.
* Chaque module du dossier doit y figurer une fois, et seulement ceux du dossier.
*/
function importableModules(modules, moduleLayers) {
if (moduleLayers === undefined) return new Map(modules.map((name) => [name, []]));
const layered = moduleLayers.flat();
const unlayered = modules.filter((name) => !layered.includes(name));
const unknown = layered.filter((name) => !modules.includes(name));
const repeated = layered.filter((name, index) => layered.indexOf(name) !== index);
if (unlayered.length + unknown.length + repeated.length > 0) {
throw new Error(
`moduleLayers ne décrit pas modules/ : sans couche [${unlayered.join(", ")}], inconnus [${unknown.join(", ")}], en double [${repeated.join(", ")}].`,
);
}
return new Map(
moduleLayers.flatMap((layer, depth) =>
layer.map((name) => [name, moduleLayers.slice(0, depth).flat()]),
),
);
}Les deux graphes ci-dessous sont calculés au build à partir des vrais imports. Personne ne les dessine. Si une flèche traversait une frontière, on la verrait ici, et le lint l’aurait déjà refusée.
- 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
Pour aller plus loin : Rangement du code, ADR 0006.
Deux applications nées d’un fork ne peuvent plus diverger en silence
Au départ, le site est une copie de l’ERP. Si on corrige une règle de TVA d’un côté et qu’on l’oublie de l’autre, la facture ne correspond plus au montant encaissé en ligne. Et pourtant les deux applications passent leurs tests, chacune de son côté.
Du coup, le code commun part dans des paquets, un morceau à la fois. En attendant, un contrôle compare les deux applications à chaque push. Si un fichier est identique des deux côtés et qu’il n’est pas déjà dans la liste des tolérés, le contrôle le refuse. Et cette liste ne peut que diminuer. Une déclaration qui existe des deux côtés doit aussi garder le même texte, sauf si l’écart est noté avec son empreinte.
scripts/check-twins.mjs · lignes 168–183function sharedDeclarationDrifts() {
return comparedSources()
.filter((file) => existsSync(siteFile(file)) && !areIdentical(file))
.flatMap((file) => {
const erp = topLevelDeclarations(join(ERP, file));
const site = topLevelDeclarations(siteFile(file));
return [...erp]
.filter(([name, text]) => site.has(name) && site.get(name) !== text)
.map(([name, text]) => ({
declaration: `${file}#${name}`,
erp: fingerprint(text),
site: fingerprint(site.get(name)),
}));
})
.sort((left, right) => left.declaration.localeCompare(right.declaration));
}- fichiers de code encore copiés d’une application à l’autre, liste qui ne peut que diminuer
- 28
- scripts/twins.manifest.json
- écarts assumés entre les deux applications, chacun consigné avec son empreinte
- 77
- scripts/twins.manifest.json
Voici les paquets que les deux applications partagent, d’après leurs manifestes :
Pour aller plus loin : Deux applications nées d’un fork, Paquets partagés, ADR 0005.
Les deux applications parlent par un contrat typé
Quand un client se rétracte ou supprime son compte, le site prévient l’ERP. Si le chemin appelé, la forme du message et la signature attendue étaient écrits dans chaque application, il suffirait de renommer quelque chose d’un seul côté pour casser l’échange, sans aucune erreur de compilation.
Donc tout ce que les deux côtés doivent dire pareil est dans le paquet packages/contracts : le chemin, le schéma du message, les en-têtes et la signature. Le message lui-même ne contient que son type et un identifiant. L’ERP relit le reste dans la base.
packages/contracts/src/site-events.ts · lignes 25–28export const siteEventSchema = z.strictObject({
kind: z.enum(SITE_EVENT_KINDS),
id: z.string().regex(SITE_EVENT_RECORD_ID),
});Pour aller plus loin : Échanges entre les applications, ADR 0002.
Chaque décision qui coûterait cher à défaire est écrite, avec ses compromis
Les décisions importantes sont écrites au format ADR : contexte, contraintes, alternatives écartées, décision, compromis et conséquences. Dans chacune, on sépare ce que les sources confirment de ce qui reste une hypothèse.
- décisions d’architecture consignées au format ADR
- 14
- apps/docs/content/docs/(public)/architecture/decisions
Pour aller plus loin : Décisions d’architecture.