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

flowchart TB
  subgraph SERVER["Server"]
    API["API (REST)"]
    CALC["Calcul batch-cooking<br/><i>v1 implémentée (GET /cooking-session)</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 — le module v1 est un GET recalculé à chaque visite, pas de temps réel ; 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.

Module « Calcul batch-cooking »

Logique de calcul du batch-cooking (optimisation des recettes entre elles selon le planning). Statut : v1 implémentée — GET /cooking-session?date= → optimizeCookingPlan (apps/api/src/lib/recipe-matching/cooking-optimizer.ts, pur) réorganise les recettes d'une semaine planifiée en phases ordonnées : une « mise en place » qui mutualise la découpe commune (même technique de découpe + même ingrédient dans une étape purement prep de ≥ 2 recettes = une seule tâche), puis des phases de cuisson qui interclassent les recettes en poussant les cuissons passives (mijotage, four…) en tâche de fond. v1 hors périmètre : fusion de cuissons, durées estimées, persistance/progression, canal websocket. Détail : backend-architecture.md.

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 côté API, frontend-architecture.md côté web.

Database (PostgreSQL)

Stockage de l'ensemble des données de l'application (voir 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) — 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, optimise les recettes entre elles (mutualiser une préparation commune, paralléliser les cuissons passives) — v1 implémentée via GET /cooking-session (voir backend-architecture.md).
• 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). Le calcul batch-cooking v1 est un simple GET recalculé à chaque visite (comme la liste de courses), pas de temps réel ; à reconsidérer si une session de cuisine partagée/synchronisée est ajoutée.

---

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 — schéma de données complet
• backend-architecture.md — organisation d'apps/api (modules, sources, matching)
• frontend-architecture.md — organisation d'apps/web
• error-handling.md — contrat d'erreurs partagé entre l'API et le client