# 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 :

```typescript
// 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)