Aller au contenu
Meubles Morinière

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.

importableModulespackages/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.

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.
  • 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.

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.

sharedDeclarationDriftsscripts/check-twins.mjs · lignes 168–183
function 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
Mesuré dans le dépôt à chaque build de cette documentation.

Voici les paquets que les deux applications partagent, d’après leurs manifestes :

Les espaces de travail du monorepo et leurs dépendanceserp dépend de auth, contracts, db, domain, infra, orders, ui. En développement, erp dépend aussi de testing. site dépend de auth, contracts, db, domain, infra, orders, ui. En développement, site dépend aussi de testing. docs dépend de infra, ui. domain dépend de db. orders dépend de db, domain, infra. testing dépend de db, domain, infra. ui dépend de domain, infra. config — devDependency des 11 autres espaces : eslint, gitignore-globs, tsconfig.base.json.erpapps/erpsiteapps/sitedocsapps/docsauth9 entréescontracts9 entréesdb2 entréesdomain68 entréesinfra27 entréesorders2 entréestesting6 entréesui65 entréesconfigdevDependency des 11 autres espaces : eslint, gitignore-globs, tsconfig.base.json
Lu dans le package.json de chaque espace à chaque build de cette documentation. Trait plein : dependencies ; tirets : devDependencies ; à l’encre pleine : une application. Survoler un espace isole ses flèches.

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.

siteEventSchemapackages/contracts/src/site-events.ts · lignes 25–28
export 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
Mesuré dans le dépôt à chaque build de cette documentation.

Pour aller plus loin : Décisions d’architecture.

Sur cette page