docs: add HuggingFace → Railway migration plan

docs/migration-hf-to-railway/plan.md

@@ -0,0 +1,250 @@
+# Plan de Migration — HuggingFace → Railway
+
+**Objectif :** Supprimer HuggingFace du chemin critique de l'API, consolider sur Railway, et conserver l'accès aux modèles HF via l'Inference API.
+
+**Statut :** 🟡 À faire — après finalisation du review Meta  
+**Durée estimée :** 2–3 heures avec tests inclus  
+**Risque :** Moyen — le bot WhatsApp peut être coupé quelques minutes pendant le basculement du webhook
+
+---
+
+## Architecture actuelle (à migrer)
+
+```
+Netlify (Frontend)
+    │  VITE_API_URL = https://safetrack-edtech.hf.space
+    ▼
+HuggingFace Space  [port 7860]   ← API Fastify (POINT DE DÉFAILLANCE)
+    │  hiberne, pas de SLA, SSE instable
+    │  BullMQ (Redis)
+    ▼
+Railway "whatsapp-worker"        ← PM2 : API (7860) + Worker Bridge (8082)
+    └── seul à pouvoir appeler graph.facebook.com
+```
+
+## Architecture cible (après migration)
+
+```
+Netlify (Frontend)
+    │  VITE_API_URL = https://xamle-api-production-xxxx.up.railway.app
+    ▼
+Railway Service 1 : "api"        ← API Fastify [PORT=7860]
+    │  BullMQ (Redis partagé)    ← auth, orgs, contacts, stream SSE...
+    ▼
+Railway Service 2 : "worker"     ← Worker BullMQ [PORT=8082, pas exposé]
+    └── appelle graph.facebook.com (Meta WhatsApp)
+    └── appelle api-inference.huggingface.co (modèles HF via HF_TOKEN)
+```
+
+---
+
+## Étape 0 — Prérequis (avant de commencer)
+
+### 0.1 Variables d'environnement à noter
+Récupère ces valeurs depuis HuggingFace Space (Settings → Variables) et Railway :
+
+| Variable | Où la trouver | Usage |
+|---|---|---|
+| `DATABASE_URL` | HF Secrets ou Railway | Neon PostgreSQL |
+| `REDIS_URL` | HF Secrets ou Railway | BullMQ + cache |
+| `JWT_SECRET` | HF Secrets | Auth |
+| `ADMIN_API_KEY` | HF Secrets | Bridge interne |
+| `ENCRYPTION_SECRET` | HF Secrets | Chiffrement tokens |
+| `OPENAI_API_KEY` | HF Secrets | OpenAI |
+| `GOOGLE_AI_API_KEY` | HF Secrets | Gemini |
+| `WHATSAPP_VERIFY_TOKEN` | HF Secrets | Vérification webhook Meta |
+| `META_GRAPH_API_VERSION` | HF Secrets | `v22.0` |
+| `HF_TOKEN` | HuggingFace account → Settings → Tokens | **Nouveau** — pour l'Inference API |
+
+### 0.2 Choisir une fenêtre de maintenance
+Faire la migration en dehors des heures de pointe. Le bot sera coupé ~5 minutes pendant le basculement du webhook Meta.
+
+---
+
+## Étape 1 — Créer le service API sur Railway
+
+### 1.1 Nouveau service Railway
+1. Dashboard Railway → **New Service** → **GitHub Repo** → `blackpanthere/Edtech`
+2. Nom du service : `api`
+3. Root Directory : `/` (racine du monorepo)
+4. Builder : **Dockerfile** (détecté automatiquement)
+
+### 1.2 Configurer la variable SERVICES
+Dans Railway → service `api` → Variables :
+```
+SERVICES=api
+```
+Cette variable contrôle ce que PM2 démarre dans `ecosystem.config.js`. Avec `SERVICES=api`, seul le processus API (port 7860) démarre — pas le Worker.
+
+Sur le service `worker` existant, vérifier que :
+```
+SERVICES=worker
+```
+ou ne pas définir `SERVICES` (par défaut PM2 lance les deux, ce qui est le comportement actuel).
+
+### 1.3 Copier toutes les variables d'environnement
+Dans Railway → service `api` → Variables, ajouter toutes les variables du tableau de l'étape 0, plus :
+```
+NODE_ENV=production
+META_GRAPH_API_VERSION=v22.0
+PORT=7860
+HF_TOKEN=hf_xxxxxxxxxxxx     ← nouveau, pour l'Inference API HuggingFace
+```
+
+### 1.4 Générer un domaine public
+Railway → service `api` → Settings → **Generate Domain**  
+Noter l'URL générée : `https://api-production-xxxx.up.railway.app`
+
+### 1.5 Vérifier le démarrage
+Dans les logs Railway du service `api`, vérifier :
+```
+🚀 API Gateway running on http://0.0.0.0:7860
+✅ [META] Graph API version: v22.0
+```
+
+---
+
+## Étape 2 — Adapter le Worker pour n'exposer que le bridge
+
+Le service `worker` actuel fait tourner les deux processus (API + Worker). Après migration, il ne doit plus faire tourner l'API (pour éviter deux instances).
+
+Dans Railway → service `worker` → Variables :
+```
+SERVICES=worker
+```
+
+Redémarrer le service et vérifier les logs :
+```
+🚀 WhatsApp Worker + Bridge listening on port 8082
+```
+L'API ne doit plus apparaître dans les logs du Worker.
+
+---
+
+## Étape 3 — Ajouter l'Inference API HuggingFace
+
+Pour continuer à utiliser les modèles HF depuis Railway, ajouter l'appel via l'API :
+
+**Fichier :** `packages/ai-sdk/src/providers/huggingface.ts` (à créer si inexistant)
+
+```typescript
+const HF_API_URL = 'https://api-inference.huggingface.co/models';
+
+export async function callHuggingFaceModel(
+    modelId: string,
+    inputs: string,
+    hfToken: string
+): Promise<string> {
+    const res = await fetch(`${HF_API_URL}/${modelId}`, {
+        method: 'POST',
+        headers: {
+            'Authorization': `Bearer ${hfToken}`,
+            'Content-Type': 'application/json'
+        },
+        body: JSON.stringify({ inputs })
+    });
+    if (!res.ok) throw new Error(`HF Inference API error: ${res.status}`);
+    const data = await res.json();
+    return Array.isArray(data) ? data[0]?.generated_text ?? '' : data?.generated_text ?? '';
+}
+```
+
+**Variable d'environnement à ajouter sur Railway (api + worker) :**
+```
+HF_TOKEN=hf_xxxxxxxxxxxx
+```
+
+---
+
+## Étape 4 — Basculer le webhook Meta (⚠️ fenêtre de coupure)
+
+C'est l'étape critique. Le bot sera coupé pendant ce changement.
+
+### 4.1 Vérifier que le nouveau service API répond
+```bash
+curl https://api-production-xxxx.up.railway.app/v1/whatsapp/webhook?hub.mode=subscribe&hub.verify_token=TON_VERIFY_TOKEN&hub.challenge=test
+# Doit retourner : test
+```
+
+### 4.2 Changer l'URL webhook dans Meta
+1. Ouvrir [developers.facebook.com](https://developers.facebook.com) → ton App → WhatsApp → Configuration
+2. **Webhook URL** : remplacer l'URL HF par `https://api-production-xxxx.up.railway.app/v1/whatsapp/webhook`
+3. **Verify Token** : identique à `WHATSAPP_VERIFY_TOKEN` dans Railway
+4. Cliquer **Vérifier et Enregistrer**
+5. Meta envoie une requête GET de vérification → le service Railway doit répondre 200
+
+### 4.3 Tester le bot
+Envoyer un message WhatsApp test → vérifier dans les logs Railway que le job est bien enqueueué et traité.
+
+---
+
+## Étape 5 — Basculer le frontend Netlify
+
+1. Netlify → Site → **Environment Variables**
+2. `VITE_API_URL` : remplacer `https://safetrack-edtech.hf.space` par `https://api-production-xxxx.up.railway.app`
+3. **Trigger Deploy** (ou attendre le prochain push)
+4. Vérifier sur le frontend :
+   - Login fonctionne
+   - Page `/clients` charge les organisations
+   - SSE connecté (pas de 401 dans la console)
+   - Import Excel fonctionne
+
+---
+
+## Étape 6 — Désactiver HuggingFace Space
+
+⚠️ Ne faire cette étape que si tout fonctionne depuis ≥ 24h.
+
+1. HuggingFace → Space `safetrack/edtech` → Settings → **Pause Space**  
+   (ne pas supprimer tout de suite — garder en pause pour rollback rapide)
+2. Après 1 semaine sans incident → supprimer le Space si souhaité
+
+---
+
+## Plan de rollback (si ça casse)
+
+Si le bot ne fonctionne plus après la migration :
+
+1. **Remettre l'URL webhook Meta** → `https://safetrack-edtech.hf.space/v1/whatsapp/webhook`
+2. **Remettre `VITE_API_URL` Netlify** → `https://safetrack-edtech.hf.space`
+3. **Relancer le HF Space** si en pause → HuggingFace → Space → Resume
+4. Durée du rollback : ~5 minutes
+
+---
+
+## Checklist de validation finale
+
+### Backend Railway (service `api`)
+- [ ] Logs de démarrage : `🚀 API Gateway running on http://0.0.0.0:7860`
+- [ ] Logs de démarrage : `✅ [META] Graph API version: v22.0`
+- [ ] `GET /health` → `200 OK`
+- [ ] `GET /v1/whatsapp/webhook?hub.mode=subscribe&...` → répond le challenge
+- [ ] Variables d'env identiques à HF (DATABASE_URL, REDIS_URL, JWT_SECRET…)
+
+### Worker Railway (service `worker`)
+- [ ] Logs : `🚀 WhatsApp Worker + Bridge listening on port 8082`
+- [ ] L'API Fastify NE démarre PAS dans ce service (`SERVICES=worker`)
+- [ ] Les jobs BullMQ sont consommés (logs : `[WORKER] Processing job`)
+
+### Frontend Netlify
+- [ ] `VITE_API_URL` mis à jour
+- [ ] Login fonctionne
+- [ ] Page `/clients` : Daily Limit affiche une valeur (pas `—`)
+- [ ] SSE connecté : pas de 401 dans la console navigateur
+- [ ] Import Excel : sélecteur de fichier s'ouvre sans erreur
+
+### Bot WhatsApp
+- [ ] Envoyer un message test → réponse reçue en < 10 secondes
+- [ ] Vérifier logs Railway Worker : job `handle-inbound` traité sans erreur
+
+---
+
+## Points d'attention spécifiques à ce projet
+
+> Le bug "bot WhatsApp coupé" lors de la précédente tentative de migration venait probablement d'une ou plusieurs de ces causes :
+> - `ADMIN_API_KEY` différente entre HF et Railway → le bridge refusait les appels internes
+> - `REDIS_URL` différente → les jobs n'étaient pas partagés entre l'API et le Worker
+> - `WHATSAPP_VERIFY_TOKEN` absente sur Railway → Meta rejetait la vérification du webhook
+> - `SERVICES` non défini → PM2 lançait deux fois l'API, le Worker tournait en double
+
+> **Règle :** L'API et le Worker DOIVENT partager exactement le même `REDIS_URL` et le même `ADMIN_API_KEY`. Ce sont les deux variables qui font fonctionner la communication interne.