Skip to Content
Meubles Morinière

The projectSkills and evidence3 min read

Architecture

Tools keep the code’s boundaries in place, without relying on discipline: one-way dependencies, two applications that no longer drift apart, a shared contract, decisions written down.

Several sessions work on the project at the same time, human or not. An instruction isn’t enough to stop them from breaking the architecture. So for every boundary described here, there’s a tool that checks it and rejects the commit.

Dependencies go in one direction, and the linter rejects the rest

In an application with several hundred thousand lines, one import too many is enough to create a cycle. After that, you end up with a module nobody dares to touch. The rule is “app/ composes, modules/ carries the business logic, shared/ depends on nothing”. But it’s only worth something if it gets checked.

The shared ESLint configuration takes care of that. For each application, it works out what each module is allowed to import. In the ERP, a module doesn’t import any other module, and whatever is shared moves down into shared/. On the storefront, the modules are arranged in layers. A module can import the ones in the layers before it, but not the ones in its own layer or in the layers after it. And if you forget to put a module in a layer, the configuration itself fails.

importableModulespackages/config/eslint.mjs · lines 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()]),
		),
	);
}

The two graphs below are computed at build time from the real imports. Nobody draws them. If an arrow crossed a boundary, you’d see it here, and the linter would already have rejected it.

The storefront’s modules and their importscart imports catalogue, promotions, shipping. checkout imports cart, promotions, shipping. products imports catalogue, closures, shipping. quotes imports shipping. account, catalogue, closures, collections, orders, projects, promotions, shipping, support, wishlist import no other module.closurespromotionsshippingaccountcatalogueprojectsquotessupportcartcollectionsproductswishlistcheckoutorders
Imports found in modules/ at every build of this documentation, arranged by MODULE_LAYERS (apps/site/eslint.config.mjs): a module only imports those in the layers below. Hover a module to isolate its arrows.
  • 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
The ERP’s 26 modules, read at every build of this documentation: none imports another.

Further reading: Code organization, ADR 0006.

Two applications born from a fork can no longer drift apart silently

The storefront started as a copy of the ERP. If you fix a VAT rule on one side and forget it on the other, the invoice no longer matches the amount collected online. And both applications still pass their tests, each on its own side.

So the shared code moves into packages, one piece at a time. In the meantime, a check compares the two applications on every push. If a file is identical on both sides and isn’t already on the tolerated list, the check rejects it. And that list can only shrink. A declaration that exists on both sides also has to keep the same text, unless the difference is recorded with its hash.

sharedDeclarationDriftsscripts/check-twins.mjs · lines 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));
}
code files still copied from one application to the other, a list that can only shrink
28
scripts/twins.manifest.json
accepted differences between the two applications, each recorded with its fingerprint
77
scripts/twins.manifest.json
Measured in the repository at each build of this documentation.

Here are the packages the two applications share, according to their manifests:

The monorepo’s workspaces and their dependencieserp depends on auth, contracts, db, domain, infra, orders, ui. In development, erp also depends on testing. site depends on auth, contracts, db, domain, infra, orders, ui. In development, site also depends on testing. docs depends on infra, ui. domain depends on db. orders depends on db, domain, infra. testing depends on db, domain, infra. ui depends on domain, infra. config — devDependency of the 11 other workspaces: eslint, gitignore-globs, tsconfig.base.json.erpapps/erpsiteapps/sitedocsapps/docsauth9 entriescontracts9 entriesdb2 entriesdomain68 entriesinfra27 entriesorders2 entriestesting6 entriesui65 entriesconfigdevDependency of the 11 other workspaces: eslint, gitignore-globs, tsconfig.base.json
Read from each workspace’s package.json at every build of this documentation. Solid line: dependencies; dashes: devDependencies; solid ink: an application. Hover a workspace to isolate its arrows.

Further reading: Two applications born from a fork, Shared packages, ADR 0005.

The two applications talk through a typed contract

When a customer withdraws or deletes their account, the storefront tells the ERP. If the path it calls, the shape of the message and the expected signature were written in each application, renaming something on one side would be enough to break the exchange, with no compile error at all.

So everything both sides have to say the same way is in the packages/contracts package: the path, the message schema, the headers and the signature. The message itself only contains its kind and an identifier. The ERP reads the rest from the database.

siteEventSchemapackages/contracts/src/site-events.ts · lines 25–28
export const siteEventSchema = z.strictObject({
	kind: z.enum(SITE_EVENT_KINDS),
	id: z.string().regex(SITE_EVENT_RECORD_ID),
});

Further reading: Exchanges between the applications, ADR 0002.

Every decision that would be costly to undo is written down, with its trade-offs

The important decisions are written in the ADR format: context, constraints, rejected alternatives, decision, trade-offs and consequences. Each one separates what the sources confirm from what’s still an assumption.

architecture decisions recorded as ADRs
14
apps/docs/content/docs/(public)/architecture/decisions
Measured in the repository at each build of this documentation.

Further reading: Architecture decisions.

On this page