expria-frontend/docs/adr/004-types-duplication.md

ADR 004 — Types partagés par duplication contrôlée

Statut : Accepté Date : 2026-04-17 Décideur : Hermann

---

Contexte

Le frontend Expria et le backend Expria sont dans deux dépôts GitHub séparés (expria-frontend et expria-backend). Plusieurs types TypeScript doivent exister à l'identique des deux côtés :

• Plan ('free' | 'standard' | 'premium')
• PlanPermissions (l'objet de l'objet PLANS)
• Production (enregistrement d'une simulation)
• Report (rapport de correction)
• ApiResponse<T> (contrat de réponse normalisé)

Sans synchronisation, ces types divergent, ce qui cause des bugs subtils (ex : un champ renommé dans le backend mais pas dans le frontend).

Options envisagées

Option A — Monorepo avec pnpm workspaces ou Turborepo

• Avantages : un seul dépôt, types partagés via un package @expria/types, refactor global en une seule PR.
• Inconvénients : restructuration massive (les dépôts actuels sont indépendants, chacun avec son propre CI/CD sur Render et Cloudflare Pages), courbe d'apprentissage pour un fondateur non-technique, complexité des commandes (pnpm --filter frontend run dev), incompatibilité avec le workflow Claude Code actuel (une session = un dépôt).

Option B — Package npm publié (@expria/types)

• Avantages : types versionnés, installable comme n'importe quelle dépendance.
• Inconvénients : publication sur npm (privé = $7/mois/dev, public = expose la structure du produit), versioning à gérer, friction de workflow (publier une nouvelle version à chaque changement).

Option C — Génération automatique via tsc --declaration

• Avantages : les types sont dérivés directement du code backend, pas de divergence possible.
• Inconvénients : pipeline de build à maintenir entre les deux dépôts, chaque modification backend nécessite un commit dans frontend pour régénérer les types, fragile au démarrage.

Option D — Duplication manuelle avec commentaire source

• Avantages : zéro infrastructure, chaque dépôt reste autonome, compatible avec le workflow Claude Code actuel.
• Inconvénients : discipline humaine requise pour synchroniser à chaque changement backend.

Décision

Option D — duplication manuelle, avec règle de discipline stricte.

Format imposé

Chaque fichier de types dupliqué commence par :

// SOURCE OF TRUTH: expria-backend/src/types/<fichier>.ts
// Synchronisé le : YYYY-MM-DD
// Si ce fichier diverge du backend, le frontend doit être mis à jour immédiatement.

Règle de synchronisation

Tout changement de type dans le backend doit être répercuté dans le frontend dans le même commit logique (même jour, même session de travail). Cette règle est intégrée à DEVELOPMENT_PRINCIPLES.md frontend.

Liste des fichiers concernés

• src/entities/user/types.ts ← expria-backend/src/types/plan.ts
• src/entities/production/types.ts ← expria-backend/src/types/production.ts
• src/entities/report/types.ts ← expria-backend/src/types/report.ts
• src/shared/types/api.ts ← expria-backend/src/types/api.ts

Fichier critique particulier

src/entities/user/lib/access.ts doit être identique au bit près à expria-backend/src/lib/access.ts. Cette règle est inscrite dans ARCHITECTURE.md §10 Règle 2 backend — on l'étend au frontend.

Conséquences

Positives :

• Zéro infrastructure, zéro outillage à maintenir.
• Chaque dépôt reste autonome (cohérent avec le choix de dépôts séparés — ARCHITECTURE.md backend §3).
• Workflow Claude Code inchangé (une session = un dépôt).
• Coût zéro.

Négatives :

• Discipline humaine requise. Si la règle n'est pas respectée, divergence silencieuse possible.
• Mitigation : ajouter dans GOLDEN_DATASET.md frontend un test de cohérence minimal — appeler /plans/status et vérifier que la structure retournée correspond aux types frontend.

À revisiter si :

• Un dev senior rejoint l'équipe et préfère un monorepo pnpm (décision à prendre avec lui).
• Le projet stabilise ses types (6-12 mois de production sans changement de schéma). À ce moment, un package @expria/types devient viable.
• Les divergences silencieuses causent plus de 2 bugs en production.

Références

• ARCHITECTURE.md backend §3 (dépôts séparés)
• ARCHITECTURE.md backend §10 Règle 2 (source de vérité unique pour access.ts)
• DEVELOPMENT_PRINCIPLES.md frontend (règle de synchronisation à ajouter)