batchCooking/specs/batch-cooking-architecture.md

# Architecture technique — Projet Batch-cooking

> Documentation de l'architecture serveur/client de l'application.

---

## Vue d'ensemble

L'application repose sur une architecture **client-serveur** classique :

- Un **serveur** exposant une **API** (échanges standards) et un canal **websocket** (communication temps réel)
- Plusieurs **clients** (Client 1, Client 2, Client 3...) connectés simultanément au serveur
- Une base de données **PostgreSQL**

```mermaid
flowchart TB
  subgraph SERVER["Server"]
    API["API (REST)"]
    CALC["Calcul batch-cooking<br/><i>(TODO)</i>"]
    IMPORT["Import d'une recette<br/><i>implémenté</i>"]
    IMP1["Import depuis source<br/>(RecipeSourceAdapter)"]
    IMP2["Traduction en étapes<br/>(ingrédients + techniques)"]
    IMP3["Sauvegarde<br/>(sur ajout au planning, ou revue manuelle)"]
    DB[("Database<br/>PostgreSQL")]

    IMPORT --> IMP1 --> IMP2 --> IMP3 --> DB
  end

  C1["Client 1"]
  C2["Client 2"]
  C3["Client 3"]

  API <--> C1
  API <--> C2
  API <--> C3

  style SERVER fill:none,stroke:#888,stroke-width:1px
```

*(Le canal websocket envisagé dans la conception d'origine pour le calcul
batch-cooking temps réel n'existe pas encore — rien à documenter tant que ce
module reste TODO ; voir la note plus bas.)*

---

## Composants

### API
Point d'entrée principal pour les échanges entre les clients et le serveur — REST classique, `requireAuth` (cookie JWT httpOnly) sur toute route qui n'est pas une donnée de référence publique. Détail complet des modules : [backend-architecture.md](./backend-architecture.md).

### Module « Calcul batch-cooking »
Logique de calcul du batch-cooking (optimisation du planning/des recettes selon le planning). **Statut : TODO — reste à développer**, avec `packages/shared`'s `assertIsNever` déjà en place comme outil prêt à l'emploi pour ce futur module (voir [backend-architecture.md](./backend-architecture.md#packagesshared--assertisnever)).

### Module « Import d'une recette »
**Statut : implémenté.** Pipeline en trois étapes, comme prévu à la conception :

1. **Import depuis source** — chaque source concrète (aujourd'hui : TheMealDB,
   API officielle) implémente le contrat `RecipeSourceAdapter`
   (`apps/api/src/lib/recipe-sources/recipe-source-adapter.ts` — `list`/`fetchDetail`/`parse`),
   enregistré dans un registre en mémoire et synchronisé vers la table
   `sources`. Un scraper générique JSON-LD/schema.org (`json-ld-recipe.ts`)
   existe aussi, en briques réutilisables par un futur adaptateur dédié à un
   site précis — volontairement pas lui-même une source sélectionnable.
2. **Traduction en étapes** — `recipe-translation.ts` orchestre la résolution
   des ingrédients/unités en texte libre contre les catalogues de référence
   (`ingredient-matcher.ts`, anglais uniquement pour l'instant) et la
   détection des techniques (`tech-step-matcher.ts`, matching par expressions
   régulières pondérées, avec résolution des chevauchements).
3. **Sauvegarde** — persistance en base (`recipe.service.ts`'s
   `createImportedRecipe`), déclenchée soit automatiquement quand un import
   "complet" (aucune ligne à arbitrer) est ajouté au planning, soit après une
   revue manuelle (ingrédients non résolus complétés à la main).

Détail complet du flux (endpoints, algorithmes, décisions produit) :
[backend-architecture.md](./backend-architecture.md#sources-externes--adaptateur-registre-synchronisation)
côté API, [frontend-architecture.md](./frontend-architecture.md#recettes--catalogue-favoris-import-depuis-une-source-externe)
côté web.

### Database (PostgreSQL)
Stockage de l'ensemble des données de l'application (voir
[batch-cooking-modele.md](./batch-cooking-modele.md) pour le détail des
tables — le modèle a beaucoup grandi par rapport à la conception d'origine :
sources externes, catalogue d'ingrédients/unités normalisé, techniques
détectées, favoris, visibilité des recettes).

---

## Notes

- **La « Liste de courses » est implémentée** (`GET /shopping-list`, voir
  [backend-architecture.md](./backend-architecture.md#liste-de-courses--agrégation-des-ingrédients-planifiés))
  — une simple **agrégation** des ingrédients déjà planifiés (somme par
  ingrédient/unité, mise à l'échelle par les portions de chaque créneau),
  pas une optimisation. Le module « Calcul batch-cooking » lui-même reste
  `TODO` : il désigne quelque chose de plus ambitieux qu'une somme
  d'ingrédients — optimiser le planning/les recettes entre elles (ex.
  mutualiser une préparation entre plusieurs recettes de la semaine), pas
  encore défini plus précisément. C'est le principal chantier restant côté
  serveur.
- Le canal websocket envisagé pour la communication temps réel n'a pas encore
  été construit — rien ne le remplace aujourd'hui (pas de polling), à
  reconsidérer au moment d'attaquer le calcul batch-cooking.

---

## Documents liés

Documentation d'implémentation (ajoutée au fil des features, complète ce document
conceptuel sans le remplacer) :

- [batch-cooking-modele.md](./batch-cooking-modele.md) — schéma de données complet
- [backend-architecture.md](./backend-architecture.md) — organisation d'`apps/api` (modules, sources, matching)
- [frontend-architecture.md](./frontend-architecture.md) — organisation d'`apps/web`
- [error-handling.md](./error-handling.md) — contrat d'erreurs partagé entre l'API et le client