Architecture technique — v2

👔 Pour le client

Cette section s'adresse à l'équipe technique. À retenir côté métier : les fonctionnalités ne changent pas — c'est la « machinerie » interne qui est modernisée. Vous pouvez passer directement aux Fonctionnalités.

⚠️ Changement de stack. Le cahier des charges décrit le périmètre fonctionnel issu de la rétro-ingénierie de recette-erp v1 (Next.js 14 / Supabase / JavaScript). La v2 (recette-erp-v2) réimplémente ce même périmètre sur une stack entièrement différente, décrite ici. Les fiches fonctionnelles conservent le comportement métier ; seules les couches techniques (backend, base, auth, sécurité, API) changent.

Stack cible v2

Couche	Technologie	Source
Langage	TypeScript (strict)	catalog typescript ^5.9.3
Framework web	Next.js 16 (App Router), React 19	apps/recette-erp/package.json
Style / UI	Tailwind CSS 4 + package @recette/ui (primitives type shadcn)	packages/ui
Backend / base / temps réel	Convex (base documentaire réactive, fonctions serveur)	packages/backend/convex
Authentification	Better Auth via @convex-dev/better-auth	packages/backend/convex/auth.ts
Validation	Zod partagé (@recette/validators), branché sur Convex + formulaires	packages/validators
Utilitaires backend	convex-helpers (custom functions, zod, relations, RLS, triggers, migrations…)	voir la page dédiée
Stockage fichiers	Convex File Storage (preuves)	remplace Supabase Storage
Monorepo / build	Turborepo + pnpm workspaces, organisation feature-first	CLAUDE.md, turbo.json
Hébergement	Front : Vercel · Backend : déploiement Convex	—

Organisation feature-first (monorepo)

apps/recette-erp/src/
├── app/          # routes Next.js — composition uniquement, zéro logique métier
├── features/     # 1 dossier par domaine (auth, campagnes, tests, synthese, anomalies, journal, crims)
└── lib/          # infra transverse minimale (auth-client, convex-client)

packages/
├── backend/      # Convex : schema.ts, functions.ts (wrappers), lib/authz.ts, domaines métier
├── ui/           # primitives UI (button, card, dialog, table…) + thème clair/sombre
└── validators/   # schémas Zod partagés (table Convex + args fonction + formulaire)

Règles clés (voir CLAUDE.md) : une feature ne dépend pas d'une autre feature (partage via app/ ou promotion en package) ; packages/ui ne connaît ni Convex ni Better Auth ; packages/backend ne dépend jamais d'une app. Frontière imposée en lint (eslint-plugin-boundaries), pas seulement documentée.

Correspondance v1 → v2

Domaine	recette-erp v1 (existant documenté)	recette-erp v2 (cible)
Langage	JavaScript	TypeScript
Base de données	PostgreSQL (Supabase)	Convex (documents + index)
Lecture des données	Client Supabase direct (RLS)	Requêtes Convex réactives (useQuery) — temps réel
Écriture / mutations	Routes app/api/* + requireRole	Mutations Convex (api.<domaine>.*) via wrappers zMutation
Logique serveur atomique	Fonctions RPC PostgreSQL SECURITY DEFINER	Mutations Convex (transactionnelles par nature)
Authentification	Supabase Auth (email/mot de passe)	Better Auth (@convex-dev/better-auth)
Session	Cookies + middleware Next (updateSession)	Better Auth (handler app/api/auth/[...all]) + authComponent
Autorisation (isolation)	RLS PostgreSQL (organization_id)	ABAC applicatif (lib/authz.ts + RLS helper convex-helpers)
Schéma / évolutions	Migrations SQL manuelles (SQL Editor)	schema.ts Convex + composant migrations
Stockage preuves	Supabase Storage (bucket evidence, URL signées)	Convex File Storage (ctx.storage, getUrl)
Dénormalisations sync	Boucle upsert fire-and-forget (fragile)	Triggers convex-helpers (atomiques)
État client / réactivité	Zustand + mises à jour optimistes + revalidatePath	Réactivité Convex native (les vues se mettent à jour seules)
Notifications in-app	Store Zustand (toast)	@recette/ui toast.tsx
Thème sombre	❌ absent (« pas de mode sombre » en v1)	✅ présent (packages/ui theme.tsx)

Modèle d'autorisation (RBAC → Permissions → ABAC → ReBAC)

Défini dans packages/backend/convex/lib/authz.ts (framework ; les permissions réelles sont posées par chaque feature). Rôles typés en v2 : admin, consultant, testeur.

• RBAC : rôle porté par l'utilisateur Better Auth (hérité de la matrice v1 roleGuard.js).
• Permissions : mapping rôle → actions (ROLE_PERMISSIONS).
• ABAC : porte l'isolation multi-tenant (organizationId) et les règles d'état (ex. campagne figée = lecture seule). C'est l'équivalent applicatif des RLS v1.
• ReBAC : documenté comme point d'extension, non construit (pas de relation pair-à-pair).

❓ À CLARIFIER (nommage des rôles) : la v2 (lib/authz.ts) type 3 rôles (admin/consultant/testeur), là où la v1 en définissait 4 (admin/consultant/metier/viewer). Correspondance retenue : metier → testeur. Le rôle viewer (lecture seule) n'est pas encore typé en v2 → à trancher. Voir Rôles & Permissions.