Introduction

Bienvenue sur le portail de documentation technique de ChatBot Pro. Cette plateforme omnicanale et intelligente unifie vos tunnels de communication clients (Web Chat, WhatsApp, E-mail) en un centre de support optimisé par des agents IA autonomes et connectés à vos bases de connaissances internes.

Fonctionnalités Techniques Majeures

• Orchestration IA Avancée : Agents autonomes utilisant le Function Calling dynamique (planification d'outils) pour des actions métiers (création de tickets, transferts).
• RAG Sémantique Multilingue : Recherche vectorielle sémantique dans Qdrant avec traduction automatique des requêtes visiteurs à la volée.
• Téléphonie Vocale Temps Réel : Connexion bidirectionnelle à faible latence (WebRTC & WebSockets) via l'API OpenAI Realtime.
• Traduction de Dashboard Sans Rechargement : Dictionnaire dynamique synchronisé à l'aide d'un MutationObserver dans le DOM.
• Intégration Omnicanale : WhatsApp Business (API Cloud Meta), mail IMAP/SMTP et widget Web Chat unifié.

Démarrage Rapide

Procédez aux étapes suivantes pour lancer l'infrastructure locale et démarrer vos développements :

1. Lancer l'infrastructure conteneurisée

Accédez au dossier de configuration Docker et démarrez les conteneurs (FastAPI backend, PostgreSQL, Qdrant DB, Redis, Nginx) :

cd docker
docker-compose up -d

2. Exécuter les migrations de base de données

Initialisez la base de données relationnelle PostgreSQL en appliquant le schéma via Alembic :

docker-compose exec backend alembic upgrade head

3. Points d'accès locaux

Vue d'ensemble de l'architecture

Le système s'organise autour d'un reverse proxy global (Nginx) qui sécurise et distribue les requêtes aux différents conteneurs sous-jacents de la stack technique.

Composants du Système

Chaque conteneur remplit une fonction technique précise au sein de la plateforme :

• FastAPI (Backend) : Écrit en Python asynchrone (SQLAlchemy + asyncpg). Il héberge l'orchestrateur d'agents IA, le connecteur de base vectorielle Qdrant, l'intégration WhatsApp Meta Cloud, et gère les WebSockets bidirectionnels.
• PostgreSQL : Stocke de façon relationnelle les logs de messages, les profils utilisateurs (JWT), les organisations et les fiches tickets CRM.
• Qdrant DB : Moteur de base vectorielle optimisé pour la recherche de plus proches voisins. Il stocke les chunks de connaissances issues des PDFs ou sites parsés et permet la recherche RAG.
• Redis : Fait office de cache distribué pour limiter les appels coûteux aux APIs LLM et de broker de messages (Pub/Sub) pour synchroniser le chat en temps réel entre multiples instances d'API.
• Nginx : Sert de passerelle en gérant le cryptage SSL, le rate limiting sur les APIs et la distribution directe des ressources statiques HTML/CSS/JS pour le Widget et le Dashboard.

Traducteur de Dashboard (i18n)

Afin de simplifier le code du dashboard d'administration sans multiplier les vues templates ou utiliser de lourds frameworks, le système d'internationalisation (i18n.js) s'appuie sur une observation dynamique du DOM à l'aide de l'API MutationObserver.

Cinématique de traduction :

1. Un composant est inséré ou mis à jour dans l'arbre DOM par Javascript (ex: chargement de la liste des conversations).
2. L'observateur intercepte l'événement de modification du DOM.
3. Il parcourt les nœuds enfants de manière récursive à la recherche de textes et d'attributs à traduire (tels que placeholder, title).
4. Il recherche la clé d'origine (Français) dans le dictionnaire i18n.js et applique le remplacement vers la langue active (Anglais ou Arabe).

FAQ RAG Multilingue

Pour garantir la pertinence des réponses du Chatbot dans un contexte international, le service rag_service.py intègre un module de traduction de requêtes transparent pour l'utilisateur.

Si un visiteur pose une question dans une langue (ex: Arabe) alors que les ressources documentaires de l'organisation ont été rédigées en Français ou en Anglais :

1. La question du visiteur est analysée et traduite par l'IA dans la langue d'origine des documents.
2. La recherche sémantique est effectuée dans Qdrant avec le vecteur de la question traduite, garantissant un score de similarité vectorielle optimal.
3. Les chunks de documents récupérés sont injectés dans le prompt système de l'agent.
4. L'agent IA synthétise sa réponse finale directement dans la langue d'origine du visiteur (Arabe).

Runner d'Agent IA & Outils

Le runner de l'agent IA (agent_runner.py) exécute les fonctions applicatives appelées par le LLM (Function Calling) dans un sandbox asynchrone sécurisé.

Pour éliminer les erreurs typiques d'exécution LLM (ex: arguments manquants ou superflus provoquant des crashs de type TypeError), le runner utilise le module inspect de Python. Il compare dynamiquement les paramètres fournis par l'IA avec la signature de la fonction ciblée, filtre les arguments superflus et injecte automatiquement les variables de session contextuelles obligatoires (comme org_id et user_id).

Module Vocal Temps Réel

Le canal vocal permet au widget de chat d'interagir par la voix en temps réel avec un agent intelligent grâce aux flux audio WebRTC.

Le backend FastAPI ouvre une connexion WebSocket avec l'API OpenAI Realtime pour retransmettre l'audio brut capturé. Il gère l'annulation d'écho, la détection automatique de parole (VAD) et retransmet le flux de réponse audio (synthèse TTS) au widget avec une latence globale ultra-faible (inférieure à 1 seconde).

API : Authentification

Les appels aux APIs privées nécessitent de transmettre le jeton JWT dans l'en-tête HTTP Authorization: Bearer <token>.

{
  "email": "admin@chatbotpro.com",
  "password": "mot_de_passe_securise"
}

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

API : Conversations

curl -H "Authorization: Bearer " http://localhost:8443/api/v1/chat/conversations

{
  "widget_key": "wid-98fa-bc41",
  "visitor_name": "Paul Martin"
}

API : Indexation RAG

file: (binaire du fichier PDF)
org_id: "org-1234"

Infrastructure Docker & Déploiement

Le fichier de configuration docker-compose.yml orchestre les microservices et assure la persistance des volumes de données.

version: '3.8'

services:
  db:
    image: postgres:15-alpine
    container_name: chatbot_db
    environment:
      POSTGRES_USER: chatbot
      POSTGRES_PASSWORD: chatbot_secret
      POSTGRES_DB: chatbot_platform
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"

  redis:
    image: redis:7-alpine
    container_name: chatbot_redis
    ports:
      - "6379:6379"

  qdrant:
    image: qdrant/qdrant:v1.7.0
    container_name: chatbot_qdrant
    volumes:
      - qdrant_data:/qdrant/storage
    ports:
      - "6333:6333"

  backend:
    build:
      context: ../backend
      dockerfile: Dockerfile
    container_name: chatbot_backend
    environment:
      - DATABASE_URL=postgresql+asyncpg://chatbot:chatbot_secret@db:5432/chatbot_platform
      - REDIS_URL=redis://redis:6379/0
      - QDRANT_URL=http://qdrant:6333
    depends_on:
      - db
      - redis
      - qdrant

  nginx:
    image: nginx:alpine
    container_name: chatbot_nginx
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ../frontend/landing:/usr/share/nginx/html/landing:ro
      - ../frontend/admin-dashboard:/usr/share/nginx/html/admin:ro
    ports:
      - "8443:80"
    depends_on:
      - backend

Variables d'environnement (.env)

Ces variables régissent la configuration système du service API backend FastAPI :

# Base de données PostgreSQL relationnelle
DATABASE_URL=postgresql+asyncpg://chatbot:chatbot_secret@db:5432/chatbot_platform

# Cache et gestion de file Redis
REDIS_URL=redis://redis:6379/0

# URL de la base vectorielle Qdrant
QDRANT_URL=http://qdrant:6333

# Clé API OpenAI (pour les embeddings sémantiques et la génération d'agents)
OPENAI_API_KEY=sk-proj-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

# Clé de chiffrement pour les cookies de session et tokens d'API JWT
SECRET_KEY=votre_cle_secrete_super_securisee_ici

Recommandations de Sécurité

L'audit technique du système a relevé des points critiques à corriger avant toute mise en production :

Actions correctives obligatoires en production :

1. Restreindre les ports : Supprimer la directive ports: - "6379:6379" et "6333:6333" du docker-compose. Les services doivent uniquement communiquer dans le réseau virtuel privé interne de Docker.
2. SECRET_KEY obligatoire : Modifier backend/app/core/config.py pour lever une exception bloquante si la clé d'environnement SECRET_KEY n'est pas spécifiée en paramètre, empêchant ainsi le backend de démarrer avec des credentials par défaut non sécurisés.
3. Nettoyage alembic.ini : Retirer la variable codée en dur sqlalchemy.url du fichier alembic.ini. Privilégier le passage dynamique d'URL dans le script de migration env.py via config.set_main_option().

Guide du Développeur : Ajouter des Traductions

Le traducteur de dashboard intercepte dynamiquement les phrases textuelles écrites en Français au sein du code HTML et JS. Pour déclarer une nouvelle chaîne de traduction :

1. Déclarer le texte en Français

Écrivez simplement votre code d'interface avec la phrase par défaut rédigée en français :

// Dans settings.js
const label = document.createElement("label");
label.textContent = "Seuil de sensibilité de l'IA";

2. Mettre à jour le dictionnaire de traduction

Ouvrez [i18n.js](file:///d:/mes%20projet/bootchat/frontend/admin-dashboard/i18n.js) et rajoutez la traduction dans les clés en (Anglais) et ar (Arabe) :

const translations = {
  en: {
    "Seuil de sensibilité de l'IA": "AI Sensitivity Threshold"
  },
  ar: {
    "Seuil de sensibilité de l'IA": "حد حساسية الذكاء الاصطناعي"
  }
};