# Architecture STAS (OUSTADO)

## Vision fonctionnelle
- Tutor virtuel accessible sur tablette, alimente par le backend Laravel et les services IA.
- Orchestration temps reel entre parcours eleve, generation IA (LLM + Avatar) et gouvernance des donnees.
- Pile PHP/MySQL pour les fonctions coeur (utilisateurs, cursus, journalisation) et microservices specialises pour l'adaptation et la synthese IA.

## Macro-architecture
1. **Core API (Laravel 12)**
   - Expose les APIs REST `v1` vers les tablettes et les portails enseignants.
   - Gere les eleves, profils adaptatifs, decisions, contenus sources et logs.
   - Integre les APIs conversationnelles via `AdaptiveEngineClient` (HTTP + JSON).
2. **Microservice "Adaptive Engine" (FastAPI)**
   - Simplifie le traitement ML/LLM en amont des appels couteux.
   - Applique des heuristiques et formatte le prompt a envoyer au LLM + Avatar provider.
   - Peut etre remplace par un moteur IA proprietaire sans impacter le core.
3. **Fournisseurs IA externes**
   - **LLM** pour re-ecrire la ressource selon le profil de l'eleve.
   - **Avatar / TTS-V** pour convertir le script personnalise en video.
   - Les deux services sont encapsules derriere le microservice d'adaptation afin de centraliser les prompts et le caching.

## Flux principal (adaptation d'une lecon)
1. La tablette appelle `POST /api/v1/adaptations/generate` avec `eleve_id`, `contenu_source_id` et les objectifs du module.
2. L'API Laravel recupere le profil cognitif (`profil_adaptatifs`), les logs recent (`log_interactions`) et construit un snapshot.
3. `AdaptiveEngineClient` envoie ce snapshot au service FastAPI.
4. Le microservice renvoie: type de decision, prompt LLM, script avatar et projection du profil.
5. Transaction MySQL: insertion dans `adaptive_decisions`, `contenu_adaptes`, mise a jour du profil.
6. Le backend renvoie soit la ressource mise en cache, soit la reponse generee. Le front peut ensuite
   - envoyer `prompt/script` au LLM/Avatar,
   - ou consommer directement la ressource stockee.

## Schema de donnees clefs
| Table | Objectif |
| ----- | -------- |
| `eleves` | Identite scolaire + preferences initiales. |
| `profil_adaptatifs` | Etat cognitif dynamique (style, niveau, risque). |
| `contenu_sources` | Support de reference fourni par les enseignants. |
| `adaptive_decisions` | Trace des decisions prises par le moteur (raison, modele, parametres). |
| `contenu_adaptes` | Cache des prompts, scripts et couts API generes pour un profil donne. |
| `log_interactions` | Journal fin des actions tablettes (engagement, difficulte, structure). |

Les colonnes respectent les contraintes du cahier des charges: JSON pour `profil_cible_utilise`, `prompt_integre` versionne, bool `prediction_risque_echec`, etc.

## Modelisation cote API
- **Controllers REST** (`EleveController`, `ProfilAdaptatifController`, `AdaptiveDecisionController`, etc.) fournissent une couche CRUD propre.
- **AdaptationController** orchestre la logique cross-table et gere le caching via une signature SHA-256.
- **Services**: `AdaptiveEngineClient` isole les appels reseau, facilite le remplacement par un vrai moteur ML.

## Gouvernance et audit
- Chaque decision stocke la justification (`raison`, `parametres_cibles`, `metadonnees`).
- Les logs d'interactions reference l'ID decision -> permet un Audit Trail complet.
- Les tables utilisent `timestamps` + `derniere_date_maj` pour faciliter la supervision et la detection de derives.

## Scalabilite
- **MySQL**: partitionnement recommande sur `log_interactions` (par date ou par eleve) et indexation sur `eleve_id`, `horodatage`.
- **API Laravel**: stateless, donc facilement horizontalisable derriere un load-balancer.
- **Adaptive Engine**: microservice independant, deploiement dans un conteneur leger (FastAPI + Uvicorn). Il peut servir de facade pour des modeles lourds (HuggingFace, Azure OpenAI, moteur Avatar) et appliquer le caching `hash_signature` avant toute inference couteuse.

## Observabilite
- Ajouter `laravel/telescope` ou OpenTelemetry pour tracer les latences.
- Le microservice expose `/health` pour l'orchestration (Kubernetes, Nomad ou Docker Compose).
- Les couts API sont journalises (champ `cout_estime_centimes`) pour suivre le budget IA.

## Etapes suivantes
1. Connecter les API LLM/Avatar reels (Synthesia, HeyGen, Azure AI Speech) a partir du prompt fourni.
2. Ajouter des jobs planifies (queue Laravel) pour rejouer les decisions en batch (pre-generation des videos).
3. Enrichir `AdaptiveEngineService` avec un vrai pipeline ML (regression logistique + clustering) une fois les logs massifs collectes.
4. Mettre en place une interface analytics (tableau enseignant) utilisant `profil_adaptatifs` + `log_interactions` pour expliquer les recommandations.