feat: Add technical documentation for SpotterCopilot

.gitignore

@@ -7,3 +7,4 @@
 .vscode/launch.json
 .vscode/settings.json
 backend/.funcignore
+__pycache__/

DOCUMENTATION.md

@@ -0,0 +1,68 @@
+# Documentation Technique de SpotterCopilot
+
+Ce document détaille l'architecture technique, le fonctionnement interne et les composants du projet SpotterCopilot, un agent conversationnel expert en sport basé sur Azure.
+
+## 1. Vue d'ensemble de l'Architecture
+
+SpotterCopilot est une application web qui suit une architecture client-serveur classique, enrichie par une architecture RAG (Retrieval-Augmented Generation) pour le traitement des requêtes IA.
+
+-   **Frontend** : Une interface de chat en HTML, CSS et JavaScript pur, responsable de l'interaction avec l'utilisateur.
+-   **Backend** : Un serveur Python qui orchestre la logique métier, la communication avec les services Azure et la gestion des conversations.
+-   **Services Azure** :
+    -   **Azure OpenAI** : Utilisé pour deux tâches critiques :
+        1.  La **génération d'embeddings** pour transformer le texte (questions des utilisateurs, descriptions d'exercices) en vecteurs sémantiques.
+        2.  La **génération de réponses** (Chat Completions) via un modèle de langage avancé (type GPT-4).
+    -   **Azure AI Search** : Fait office de base de données vectorielle. Il stocke les embeddings des exercices et permet une recherche par similarité sémantique rapide et efficace.
+
+## 2. Backend en détail (`main.py`)
+
+Le backend est le cœur de l'application. Il est responsable de la réception des requêtes du frontend, de leur traitement via le pipeline RAG et du retour des réponses générées.
+
+### Flux de traitement d'une requête :
+
+1.  **Réception de la requête** : Le serveur (exposant une API, par exemple `/api/chat`) reçoit une requête POST du frontend contenant la question de l'utilisateur (`user_input`) et son identifiant unique (`X-User-Id`).
+2.  **Récupération de l'historique** : Le script charge l'historique des performances de l'utilisateur (poids, séries) associé à son ID. Actuellement, cet historique est stocké en mémoire, mais il est conçu pour être facilement adaptable à une base de données persistante (comme Azure Table Storage).
+3.  **Phase de Récupération (Retrieval - RAG)** :
+    -   Le `main.py` appelle la fonction `retrieve_docs` du module `backend/chat/retrieve_docs.py`.
+    -   Cette fonction prend la question de l'utilisateur, la transforme en un **vecteur d'embedding** via un appel à Azure OpenAI.
+    -   Ce vecteur est ensuite utilisé pour interroger **Azure AI Search**. La recherche ne se fait pas sur des mots-clés, mais sur la **similarité cosinus** entre le vecteur de la question et les vecteurs des exercices stockés.
+    -   Azure AI Search retourne les `k` exercices les plus pertinents (par défaut, 5).
+4.  **Phase d'Augmentation (Augmentation - RAG)** :
+    -   Le script construit un **contexte riche** (prompt) pour le modèle de langage. Ce contexte est crucial pour la qualité de la réponse et contient :
+        a.  Un **Prompt Système** : Définit le rôle, le ton et les instructions de l'IA ("Tu es SpotterCopilot, un coach expert...").
+        b.  **L'historique des performances** : Pour que l'IA puisse personnaliser les charges.
+        c.  **Les documents récupérés** : Le contenu des exercices trouvés par Azure AI Search.
+        d.  **La question de l'utilisateur**.
+5.  **Phase de Génération (Generation - RAG)** :
+    -   Ce contexte complet est envoyé à l'API de Chat Completion d'Azure OpenAI.
+    -   Le modèle de langage génère une réponse en s'appuyant sur les informations fournies. Les exercices proposés sont donc directement issus de la base de connaissances, et les charges sont adaptées à l'utilisateur.
+6.  **Gestion de la réponse** :
+    -   La réponse textuelle est renvoyée au frontend.
+    -   Si la réponse contient des informations structurées (comme une mise à jour des poids au format JSON), le backend les extrait et met à jour l'historique de l'utilisateur.
+
+## 3. Frontend en détail (`frontend/`)
+
+Le frontend est une application monopage (SPA) simple, conçue pour être intuitive et réactive.
+
+-   **`index.html`** : Structure la page avec une zone de chat, une zone de saisie et des modales pour l'introduction et le signalement de bugs.
+-   **`styles.css`** : Gère l'apparence visuelle de l'interface de chat.
+-   **`script.js`** : Contient toute la logique côté client.
+    -   **Gestion de l'utilisateur** : Attribue un `userId` unique via `crypto.randomUUID()` et le conserve dans le `localStorage` pour assurer la persistance entre les sessions.
+    -   **Communication API** : La fonction `ask()` envoie les requêtes au backend (`/api/chat`) en utilisant l'API `fetch`, en incluant le `userId` dans les en-têtes.
+    -   **Affichage dynamique** : Gère l'ajout des bulles de chat, l'affichage d'un état de chargement et le défilement automatique de la conversation.
+    -   **Formatage intelligent** : La fonction `formatProgram` détecte les réponses contenant des programmes d'entraînement et les met en forme en HTML pour une meilleure lisibilité.
+    -   **Assistance au Feedback** : Le bouton "📝 Feedback" simplifie la vie de l'utilisateur en pré-remplissant un modèle de feedback basé sur le dernier programme généré.
+
+## 4. Données du Projet
+
+-   **`ressources/Large_Exercises_CSV.csv`** : La source de connaissance principale de l'agent. Ce fichier CSV contient une liste d'exercices avec des descriptions, des groupes musculaires ciblés, etc. Il est importé dans Azure AI Foundry (ou Azure AI Studio) pour créer l'index de recherche.
+-   **`grounded_chat.prompty`** : Un fichier template pour le prompt système. Bien que le prompt soit défini directement dans `main.py` dans la version actuelle, ce fichier montre une approche plus modulaire où les prompts peuvent être gérés comme des actifs séparés dans Azure AI Studio.
+-   **Historique utilisateur** : Stocké sous forme d'objet JSON associant un nom d'exercice à un poids. Par exemple : `{"Développé couché": "60kg", "Squat": "80kg"}`.
+
+## 5. Configuration et Dépendances
+
+-   **`.env`** : Fichier crucial (et non versionné) contenant toutes les clés d'API et les endpoints pour les services Azure.
+-   **`requirements.txt`** : Liste les dépendances Python nécessaires pour le backend (`openai`, `azure-search-documents`, `python-dotenv`, etc.).
+-   **`.devcontainer/`** : Contient la configuration pour un environnement de développement conteneurisé (Docker), assurant que l'environnement de développement est cohérent et reproductible pour tous les contributeurs.
+
+Ce document fournit une vue d'ensemble complète du projet SpotterCopilot. Pour des détails plus spécifiques sur l'implémentation, veuillez vous référer aux commentaires dans le code source.