docs: add technical documentation for WhatsApp B2B architecture (force add)

docs/whatsapp_b2b_architecture.md

@@ -0,0 +1,45 @@
+# Architecture WhatsApp B2B - Xamlé Studio
+
+Ce document détaille l'architecture technique, la sécurité et les flux de données mis en place pour la plateforme EdTech multi-organisations.
+
+## 1. Sécurité & Infrastructure
+
+### 🔐 Gestion des Secrets
+La plateforme utilise une approche "Zero-Trust" pour les variables d'environnement critiques. Le serveur refuse de démarrer si les secrets suivants ne sont pas configurés ou s'ils sont trop courts (minimum 32 caractères pour la production) :
+
+-   **`JWT_SECRET`** : Utilisé pour signer et vérifier les tokens d'authentification des administrateurs d'organisation.
+-   **`ENCRYPTION_SECRET`** : Clé maître utilisée pour chiffrer les secrets des tenants (Clés OpenAI, Stripe, Tokens Meta) avant leur stockage en base de données.
+-   **`ADMIN_API_KEY`** : Clé utilisée pour sécuriser les communications entre les micro-services (Gateway <-> API <-> Worker).
+
+### 🌐 Restriction CORS
+Pour prévenir les attaques XSS et les accès non autorisés, le middleware CORS est configuré de manière stricte dans `apps/api/src/index.ts`. Seuls les domaines suivants sont autorisés à appeler l'API en production :
+-   `https://admin.xamle.studio` (Dashboard principal)
+-   `https://xamle.studio` (Site vitrine)
+-   `https://edtechadmin.netlify.app` / `https://edtechadminweb.netlify.app` (Environnements de staging/admin)
+
+## 2. Communication Interne & Webhooks
+
+### 🔄 Forwarding des Webhooks
+Comme la plateforme peut être déployée derrière une Gateway (ex: HuggingFace ou Railway Public), un mécanisme de forwarding intelligent est en place :
+
+1.  **Réception** : L'API reçoit le webhook de Meta sur `/v1/whatsapp/webhook`.
+2.  **Validation HMAC** : L'API vérifie la signature `x-hub-signature-256` envoyée par Meta avec le `WHATSAPP_APP_SECRET`.
+3.  **Forwarding** : Si l'API agit comme Gateway, elle renvoie la requête au Worker interne via `RAILWAY_INTERNAL_URL`.
+4.  **Authentification Interne** : Ce transfert est sécurisé par le header **`x-api-key`** contenant la `ADMIN_API_KEY`. Le service de destination valide ce header avant de traiter la requête.
+
+## 3. Flux "Embedded Signup" (Intégration Meta)
+
+L'intégration d'une nouvelle organisation à WhatsApp se fait via le flux **Embedded Signup** de Meta.
+
+### 🌊 Parcours de Données
+1.  **Frontend** : L'administrateur clique sur "Connexion WhatsApp". Le SDK Meta s'ouvre, l'utilisateur sélectionne son compte Business et son numéro.
+2.  **Callback** : Le Frontend reçoit un `accessToken` temporaire et les IDs Meta (`wabaId`, `phoneNumberId`).
+3.  **Backend (API)** : Le Frontend appelle la route `POST /v1/organizations/:id/whatsapp-setup`.
+4.  **Chiffrement & Stockage** :
+    -   L'API chiffre l' `accessToken` avec l' `ENCRYPTION_SECRET`.
+    -   Elle stocke le token et le `wabaId` dans la table `Organization`.
+    -   Elle effectue un `upsert` dans la table `WhatsAppPhoneNumber` pour lier le numéro technique à l'organisation.
+5.  **Invalidation Cache** : Le service `invalidateOrganizationCache` est appelé pour forcer le Worker à charger la nouvelle configuration au prochain message reçu.
+
+## 4. Maintenance
+Toute modification du schéma de données doit être accompagnée d'une migration Prisma (`npx prisma migrate dev`). Les logs sont centralisés via **Pino** et formatés en JSON pour être indexables par des outils comme Logtail ou Datadog.