# Architecture Technique — IA Sans Panique

## 1. Vue d'ensemble du Système

**IA Sans Panique** est conçu selon une architecture à double exécution :
1. **Mode Navigateur Autonome (Offline / Zero-API)** : Le frontend intègre un moteur de simulation complet pour les 7 modules, le diagnostic, le RAG local et le graphe d'états agentique. Il permet à tout visiteur de portfolio ou apprenant de tester l'intégralité du parcours instantanément, sans latence ni clé API.
2. **Mode Serveur FastAPI (Live / Hybrid)** : Une API Python 3.12+ servant les endpoints de retrieval RAG (`/rag/query`), le graphe agentique avec checkpoints (`/agent/step`), et l'agrégation de cohorte en temps réel (`/trainer/stats`).

```
+-----------------------------------------------------------------------------------+
|                            FRONTEND INTERACTIF (SPA)                              |
|  - Layout Accessible (WCAG AA, Contrastes, Zoom 200%, prefers-reduced-motion)    |
|  - Modules Didactiques 1 à 7 + Mission Finale + Bilan de Parcours                 |
|  - Mode Formateur (Plan 3h30, Timer interactif, Fiches séance, Dashboard)        |
+-----------------------------------------------------------------------------------+
          |                                                       |
          | (Mode Offline / Local Engine)                         | (Mode Connecté HTTP/JSON)
          v                                                       v
+------------------------------------+          +------------------------------------+
|    Local Interactive Simulator     |          |       FastAPI Backend Service      |
| - Heuristic email classifier       |          | - /health (Statut & Mode)          |
| - SVG Overfitting curve engine     |          | - /rag/query (LlamaIndex style)    |
| - Tokenizer & Attention hover      |          | - /agent/step (LangGraph workflow) |
| - Local Knowledge Base chunks      |          | - /trainer/stats (Cohort analytics)|
| - State Machine Travel Agent       |          +------------------------------------+
+------------------------------------+                            |
                                                                  v
                                                +------------------------------------+
                                                |     Knowledge Base & Guardrails    |
                                                | - politique_conges.md              |
                                                | - procedure_achat.md               |
                                                | - charte_deplacement.md            |
                                                +------------------------------------+
```

## 2. Composant RAG (Retrieval-Augmented Generation)

- **Knowledge Base** : Documents réels d'entreprise au format Markdown avec sections explicites.
- **Chunking & Indexation** : Découpage hiérarchique par titre de section (`##`), normalisation textuelle et extraction de termes discriminants.
- **Scoring & Attribution** : Calcul de similarité lexicale/sémantique avec pondération des titres de sections.
- **Citations formelles** : Chaque extrait injecté porte un identifiant unique (ex: `[charte_deplacement.md — 2. Réservation d'Hébergement]`).
- **Garde-fou d'abstention** : Si le score de confiance maximal est inférieur au seuil (`threshold = 0.35`), le système refuse formellement d'inventer une réponse et émet l'avertissement de garde-fou.

## 3. Composant Agent (LangGraph Workflow)

Le workflow agentique suit une machine à états finis stricte avec interruption pour validation humaine :

1. `understand_request` : Extraction structurée de l'intention (destination: Lyon, heure: 10h00, contrainte de non-réservation autonome).
2. `retrieve_policy` : Requête de la charte de déplacement (TGV obligatoire <= 4h, plafond Lyon 160 €).
3. `search_options_mock` : Recherche parmi les options d'horaires et d'hôtels disponibles.
4. `rank_options` : Filtrage selon conformité stricte à la charte d'entreprise.
5. `human_approval` (**Point d'arrêt obligatoire**) : Suspension de l'exécution, présentation du récapitulatif à l'humain.
6. `draft_summary` : Synthèse rédigée après validation humaine formelle. Aucune réservation financière directe n'est possible.

## 4. Sécurité & Données Privées

- **Zero-Secret Client** : Aucune clé API n'est exposée ou stockée dans le navigateur.
- **Stockage Local** : La progression de l'apprenant et ses scores de pré/post-test sont enregistrés exclusivement dans le `localStorage` du navigateur.
- **Conformité RGPD & Article 4 AI Act** : Sensibilisation active au respect de la confidentialité des données d'entreprise et à l'acculturation IA des équipes.