Le code7 min de lecture
Architecture
Le monorepo, ses applications Next.js et ses paquets : ce qui appartient à chacun, qui dépend de qui, qui parle à qui en prod, et où tout est hébergé.
Le dépôt, c’est un monorepo pnpm avec trois applications Next.js et les paquets qu’elles partagent. La règle est simple : les dépendances descendent. Une application importe des paquets, un paquet importe un paquet plus bas, et jamais dans l’autre sens. Une application assemble et s’exécute. Un paquet contient ce que les applications doivent dire ou calculer de la même façon. Pourquoi cette forme et ce qu’elle coûte, c’est expliqué décision par décision dans les Décisions d’architecture, avec les sources, les alternatives et ce qui reste supposé. Ce qu’on n’a pas construit, la dette assumée et les risques qui restent sont dans Dette, risques et évolutions.
Carte du dépôt
| Chemin | Rôle | Port local |
|---|---|---|
apps/erp | ERP de l'atelier : catalogue, commandes, devis, comptabilité, webhook Stripe, veille quotidienne | 3000 |
apps/site | Site public : catalogue, panier, paiement, suivi de commande, devis, compte client (ARCHITECTURE.md) | 3001 |
apps/docs | Documentation technique, en français et en anglais (Fumadocs) : architecture, ERP, site, logique métier, sécurité, qualité | 3002 |
packages/db | Schéma Prisma, migrations et client généré (@meublesmoriniere/db) | |
packages/domain | Règles métier communes : TVA, prix, remises, port, totaux, numéros de pièce, délais et date promise, horaires, identité légale, textes de la rétractation (@meublesmoriniere/domain) | |
packages/auth | Better Auth : comptes du personnel (ERP) et comptes clients (site), rôles, limites de débit (@meublesmoriniere/auth) | |
packages/ui | Kit d'interface commun aux deux apps (@meublesmoriniere/ui) | |
packages/contracts | Ce que les deux apps doivent dire pareil : routes publiques, chemins machine, tags de cache, Stripe, et le contrat HTTP de leurs échanges (corps, signature) | |
packages/infra | Briques techniques : journaux, collecteur d'erreurs, traces, envoi d'e-mail (fabrique), e-mail d'alerte, adaptateur et arrêt de Prisma, comparaison à temps constant (@meublesmoriniere/infra) | |
packages/orders | Traitements de commande que les deux apps exécutent pareil, sur des ports qu'elles fournissent : la rétractation, l'annulation d'une commande en attente (@meublesmoriniere/orders) | |
packages/testing | Outillage de test des deux apps : fixtures de la suite Postgres, doubles et contrôle axe des e2e, gardes de base locale (@meublesmoriniere/testing) | |
packages/config | tsconfig de base, fabriques ESLint, motifs .gitignore (@meublesmoriniere/config) |
Node 24, pnpm 10. Le schéma et les migrations vivent dans packages/db/prisma ; seul l'ERP les joue (pnpm db:migrate, pnpm db:pre-deploy). Le client Prisma se génère au pnpm install (postinstall de packages/db) ou par pnpm db:generate.
Les versions des dépendances communes vivent une seule fois, dans le catalog: de pnpm-workspace.yaml. Une version publiée depuis moins de 24 heures est refusée (minimumReleaseAge) ; une exception se déclare dans minimumReleaseAgeExclude.
packages/domain n'ouvre aucune connexion et ne lit ni le réseau ni les variables d'environnement : ses deux lectures communes (grille de port, stock libre au paiement) reçoivent le client Prisma de l'app. Un texte qui dépend de l'app (l'adresse du site dans la signature des e-mails) s'y passe en paramètre, et l'envoi d'un e-mail ou l'écriture en base restent dans l'app. Il ne dépend que de zod et de packages/db : ses enums, et les types Prisma des quelques formes de requête que les deux apps doivent lire pareil (BUYABLE_VARIANT_WHERE, grille de port, accueil). packages/ui ne dépend d'aucune app : les fichiers shared/components/ui/*.tsx des apps le réexportent, et app/globals.css déclare @source "../../../packages/ui/src" pour que Tailwind en lise les classes.
Qui dépend de qui
- Aucune application ne dépend d’une autre. L’ERP et le site ne s’importent pas. Ils partagent des paquets et une base. Pour ce qui ne doit appartenir qu’à l’un des deux, ils passent par HTTP (plus bas). Et aucun paquet ne dépend d’une application.
db,infra,contractsetauthne dépendent d’aucun autre paquet.dbcontient le schéma et le client Prisma,infral’outillage technique,contractsce que les deux applications s’échangent, etauthl’authentification.authne dépend même pas dedb, parce que chaque application lui passe son client Prisma.domainne dépend que dedb, pour ses énumérations et ses types. Il n’ouvre aucune connexion et ne lit ni le réseau ni l’environnement. Ses deux lectures communes, la grille de port (shipping-grid-read.ts) et le stock libre au paiement (stock-reservation.ts), reçoivent le client Prisma de l’application.ui,ordersettestingassemblent les précédents. Le kit d’interface reprend les types de prix dedomain. La rétractation enchaîne des règles dedomainet des briques d’infra. Et l’outillage de test prépare une base avecdb.- La doc ne prend que
uietinfra, pour la palette de la marque et les en-têtes de sécurité. Elle n’a ni base ni secret.
Le détail de ce que chaque paquet contient et de ce qu’il s’interdit est dans Paquets partagés.
Ce qui appartient à chaque application
| Application | Ce qu’elle fait | Ce qu’elle est seule à avoir, ou ce qu’elle ne peut pas faire |
|---|---|---|
ERP (apps/erp) | l’outil de l’équipe (catalogue, ventes, achats, stock, comptabilité), le webhook Stripe, la veille du matin et Fisher | les migrations et le rôle propriétaire de la base, les clés d’écriture (Stripe qui rembourse, Blob, notifications, passerelle IA), la confirmation d’un paiement, l’émission d’une facture |
Site (apps/site) | la boutique : catalogue, panier, paiement, suivi, devis, compte client | rien d’irréversible. Il a un rôle Postgres limité, une clé Stripe restreinte, pas de jeton Blob, et il ne peut créer qu’une commande en attente de paiement |
Documentation (apps/docs) | ces pages, en français et en anglais | rien. Elle n’a ni base ni secret, et elle lit le dépôt au build |
Qui parle à qui en prod
Postgres · Neon
la base commune
- ERP →
DATABASE_· rôle propriétaireURL
- Site →
DATABASE_· rôle moriniere_siteURL
Stripe
paiements
- ERP →
STRIPE_· clé secrèteSECRET_ KEY - ERP ←
STRIPE_· webhookWEBHOOK_ SECRET
- Site →
STRIPE_· clé restreinteSECRET_ KEY
Vercel Blob
photos, pièces comptables
- ERP →
BLOB_· photos, écritureREAD_ WRITE_ TOKEN - ERP →
INVOICE_· factures et devis, écritureBLOB_ READ_ WRITE_ TOKEN
- Site →
BLOB_· photos, lecture seulePUBLIC_ HOST
Resend
e-mails
- ERP →
RESEND_· envoiAPI_ KEY
- Site →
RESEND_· envoiAPI_ KEY
Upstash Redis
limites de débit
- ERP →
KV_· débit, idempotenceREST_ API_ URL
- Site →
KV_· débitREST_ API_ URL
Vercel AI Gateway
Fisher, modèles Anthropic
- ERP →
AI_· appelsGATEWAY_ API_ KEY
Web Push
notifications du personnel
- ERP →
VAPID_· signaturePRIVATE_ KEY
La Poste
suivi des colis
- ERP →
LA_· API SuiviPOSTE_ OKAPI_ KEY
Vercel Cron
tâche planifiée
- ERP ←
/· « 0 6 * * * », UTCapi/ veille
Entre les deux applications
- ERP → Site
/api/revalidate·REVALIDATE_· périmer le cache des pagesSECRET - Site → ERP
/api/evenements-site·SITE_· annoncer une rétractation, une suppression de compteEVENTS_ SECRET - Site → ERP
/api/devis-site·QUOTE_· obtenir le PDF d’un devisPDF_ SECRET - Site → ERP
/api/factures-site·QUOTE_· obtenir le PDF d’une facturePDF_ SECRET
Le site ne confirme jamais un paiement et n’écrit pas dans Blob. C’est l’ERP qui le fait, parce que lui seul a les clés. Avec son rôle Postgres, le site lit le catalogue, crée une commande web en attente de paiement et gère le compte client. Un paiement, un remboursement ou un litige, c’est le webhook qui le confirme à l’ERP. Côté Stripe, le site n’a qu’une clé restreinte. Elle ouvre des sessions de paiement et rien d’autre de sensible.
Pour les canaux entre les deux applications, leur contrat et leurs secrets, voyez Échanges entre les applications. Tous les services externes, y compris ceux qui ne demandent pas de clé, sont dans Intégrations.
Hébergement
- Vercel, région Paris (
cdg1). Il y a un projet Vercel par application, cette doc comprise. Chaque projet ne déploie que la branchemain, et il saute le build quand le commit ne touche ni l’application ni les paquets (ignoreCommandde chaquevercel.json). - Neon pour Postgres, avec l’adaptateur de
packages/infra(prisma-adapter.ts). La base de prod est aux États-Unis, en Virginie (us-east-1d’AWS,packages/domain/src/legal-identity.ts#DATABASE_HOST). C’est loin des fonctions de Paris, donc chaque aller-retour entre une fonction et la base traverse l’Atlantique. - Une tâche planifiée : chaque matin, Vercel appelle la veille de l’ERP (
cronsdeapps/erp/vercel.json). Elle est décrite dans ERP.
- Rangement du codeLes trois couches de chaque application, le sens des imports, les modules et leurs vraies dépendances, et pourquoi il y a ces frontières.
- Paquets partagésCe que contient chaque paquet et ce qu’il s’interdit, comment une application l’utilise et le câble, et pourquoi les paquets sont publiés en source.
- DonnéesLe modèle Prisma et PostgreSQL d’un magasin de meubles (catalogue, ventes, stock, achats, comptabilité) : ses relations, ce que la base refuse elle-même, les transactions et les verrous, avec leurs raisons et leurs limites.
- Next.js et ReactComment l’ERP et le site utilisent Next.js 16 et React 19 (composants serveur et client, rendu, lectures, cache, flux, navigation, état) : le problème que règle chaque choix, ce qu’il change et ses limites.
- Échanges entre les applicationsLes quatre canaux HTTP entre l’ERP et le site, le contrat qu’ils partagent et ce qui les protège.
- IntégrationsLes services externes, à quoi sert chacun et quelle application a sa clé, puis le parcours d’un paiement Stripe jusqu’à l’ERP.