From 2db338a9f528056d26079c172a45cec5ee9f940d Mon Sep 17 00:00:00 2001
From: laurentbarontini <l.barontini@open-squared.ch>
Date: Sun, 5 Apr 2026 11:08:08 +0200
Subject: [PATCH] End session

---
 DEPLOYMENT_NOTES.md  | 74 ++++++++++++++++++++++++++++++++++++++++++++
 MEMORY.md            | 56 +++++++++++++++++++++++++++++++++
 frontend/src/App.jsx |  2 +-
 3 files changed, 131 insertions(+), 1 deletion(-)
 create mode 100644 DEPLOYMENT_NOTES.md
 create mode 100644 MEMORY.md

diff --git a/DEPLOYMENT_NOTES.md b/DEPLOYMENT_NOTES.md
new file mode 100644
index 0000000..64e35b2
--- /dev/null
+++ b/DEPLOYMENT_NOTES.md
@@ -0,0 +1,74 @@
+# Deployment Notes
+
+## Stack Reelle
+
+Le deploiement utilise sur le serveur n'est pas celui d'un `docker-compose.yml` versionne dans ce repo.
+
+La stack reelle comprend notamment:
+- `tutor-backend`
+- `tutor-frontend`
+- `tutor-postgres`
+- `tutor-redis`
+- `nginx`
+
+## Routage Nginx
+
+Pour `prof.open-squared.tech`, la conf partagee pendant la session est:
+
+- `location /api/` -> `http://tutor-backend:8000/`
+- `location /` -> `http://tutor-frontend:3000/`
+
+Consequence:
+- le frontend doit appeler l'API via `/api`
+- nginx supprime le prefixe `/api/` avant d'envoyer au backend
+- `GET /api/students` devient `GET /students` cote FastAPI
+
+## Incidents Rencontres
+
+### 1. Bouton "Creer un eleve" casse
+
+Cause:
+- le frontend recevait une page HTML d'erreur au lieu d'un JSON
+- `JSON.parse` echouait
+
+Diagnostic final:
+- nginx renvoyait `502 Bad Gateway`
+- `tutor-backend` etait indisponible
+
+### 2. Backend qui ne demarre plus
+
+Cause:
+- ajout de la route `/transcribe`
+- FastAPI exige `python-multipart` pour les uploads `multipart/form-data`
+
+Resolution:
+- ajouter `python-multipart` dans `backend/requirements.txt`
+- rebuild du conteneur backend
+
+### 3. Micro automatique instable dans Firefox
+
+Cause:
+- la premiere approche de detection audio etait trop fragile dans Firefox
+
+Resolution:
+- simplification et renforcement de la capture audio
+- relance automatique du segment d'ecoute apres la reponse du prof
+
+## Commandes Utiles Cote Serveur
+
+Quelques commandes utiles deja identifiees:
+
+```bash
+docker logs tutor-backend
+docker compose up -d --build tutor-backend
+curl -i https://prof.open-squared.tech/api/health
+curl -i https://prof.open-squared.tech/api/students
+```
+
+## Ameliorations Possibles
+
+- Servir le frontend compile plutot que Vite en production
+- Supprimer le bruit HMR/WebSocket en production
+- Ajouter une page ou section admin de diagnostic micro/API
+- Documenter la stack serveur hors repo dans un espace partage dedie
+
diff --git a/MEMORY.md b/MEMORY.md
new file mode 100644
index 0000000..58bdd3f
--- /dev/null
+++ b/MEMORY.md
@@ -0,0 +1,56 @@
+# Memoire Projet
+
+## Contexte
+
+Ce projet est un POC de professeur virtuel pour enfants, avec:
+- frontend React + Vite
+- backend FastAPI
+- PostgreSQL pour les donnees eleve
+- Redis present dans la stack
+- integration OpenAI pour reponses texte et transcription audio
+
+## Points Importants
+
+- Le frontend appelle l'API via le prefixe `/api`.
+- Le backend expose une route `POST /transcribe` pour la transcription audio.
+- La route `/transcribe` utilise `UploadFile`, donc `python-multipart` est requis dans le backend.
+- Le vrai `docker-compose.yml` de production n'est pas dans ce repo. Il est situe un niveau au-dessus sur le serveur.
+- La conf nginx reelle route:
+  - `/api/` vers `tutor-backend:8000`
+  - `/` vers `tutor-frontend:3000`
+
+## Dictée Vocale
+
+- L'ancien bouton de dictee marchait en mode manuel avec `MediaRecorder.start()` puis `stop()`.
+- Le mode actuel est un mode mains libres:
+  - activation via un clic utilisateur
+  - enregistrement automatique
+  - detection du silence
+  - transcription automatique
+  - envoi automatique du message
+- Firefox s'est montre capricieux avec la mesure temps reel via `AnalyserNode`.
+- La solution retenue s'appuie sur un traitement plus direct du flux audio pour determiner le niveau sonore.
+- L'ecoute se rearme automatiquement apres:
+  - la transcription/envoi du message eleve
+  - la fin de lecture vocale du professeur
+
+## Voix du Professeur
+
+- Le frontend charge les voix du navigateur via `speechSynthesis.getVoices()`.
+- Une liste de voix est proposee dans l'interface.
+- Les voix francaises sont priorisees dans le tri.
+
+## Points de Vigilance
+
+- Les erreurs WebSocket Vite/HMR sur `wss://prof.open-squared.tech/...` sont du bruit de dev tant que le frontend tourne via Vite derriere nginx.
+- Ces erreurs ne sont pas la cause principale si `/api/*` renvoie des `502` ou si le micro se comporte mal.
+- En cas de `502` sur `/api/*`, verifier d'abord `docker logs tutor-backend`.
+
+## Fichiers Touchés Pendant Cette Session
+
+- `frontend/src/App.jsx`
+- `frontend/vite.config.js`
+- `backend/app/main.py`
+- `backend/app/services.py`
+- `backend/requirements.txt`
+
diff --git a/frontend/src/App.jsx b/frontend/src/App.jsx
index c7a7960..8d7c0cb 100644
--- a/frontend/src/App.jsx
+++ b/frontend/src/App.jsx
@@ -4,7 +4,7 @@ const API_BASE = '/api'
 const AUTO_STOP_SILENCE_MS = 2500
 const SPEECH_START_THRESHOLD = 0.02
 const SILENCE_THRESHOLD = 0.012
-const DEBUG_AUDIO = true
+const DEBUG_AUDIO = false
 
 async function parseApiResponse(res) {
   const contentType = res.headers.get('content-type') || ''