Architecture

Vue d'ensemble#

Tout tient dans un docker compose. Les requêtes HTTP restent courtes ; le travail lourd part dans une file RabbitMQ et un worker dédié s'en charge, sans bloquer l'interface.

L'API interroge aussi Qdrant et le modèle de langage pour répondre aux questions de l'assistant ; le worker, lui, écrit transcriptions et résumés dans le dossier médias et les statuts en base.

L'API : ports et adaptateurs#

Le paquet e_learning est découpé en quatre couches. Les dépendances vont uniquement vers l'intérieur, et c'est vérifié : import-linter échoue si une couche importe une couche plus externe, ou si le domaine importe FastAPI, SQLAlchemy ou Pydantic.

L'API, la CLI et le worker sont trois adaptateurs primaires sur les mêmes cas d'usage : lancer une transcription depuis le navigateur ou depuis la ligne de commande exécute le même code.

Bounded contexts#

Authentification#

• Ports applicatifs (application/user/ports.py) : PasswordHasher, TokenService, LoginThrottle. Le domaine ne voit que l'empreinte du mot de passe, jamais le mot de passe ni l'algorithme.
• Adaptateurs (infrastructure/security/) : argon2 via pwdlib (calcul dans un thread, hors boucle d'événements), JWT HS256 via pyjwt (sub, iat, exp), compteur d'échecs en mémoire du processus.
• Garde par routeur : chaque routeur FastAPI déclare dependencies=[Depends(get_current_user)] ou [Depends(require_admin)]. Toutes les écritures du catalogue sont regroupées dans studio_router. Une nouvelle route est donc protégée par défaut.
• Relecture en base : get_current_user décode le jeton puis relit le compte, une requête SQL par appel. Désactivation et retrait du rôle s'appliquent sans attendre l'expiration du jeton.
• Garde-fou : tests/integration/api/test_access_matrix.py liste chaque route avec son rôle et échoue si une route n'est pas classée ou pas gardée.

Cycle de vie d'un job#

1. La requête HTTP crée un Job en base (queued) et passe le statut métier de la vidéo à processing.
2. Après le commit, le message est publié sur l'exchange elearning_jobs (type direct, durable). Publier avant le commit exposerait le worker à un job qui n'existe pas encore.
3. L'API répond 202 avec la vidéo et ses active_jobs.
4. Le worker consomme (APP_WORKER_PREFETCH en parallèle), passe le job en running et met à jour progress et message.
5. À la fin : succeeded ou failed, et le statut métier (transcription_status, summary_status, processing_status) passe à ready ou failed.
6. Transcription et résumé réussis enchaînent un job rag_index_video.

Les clients n'ont pas de canal temps réel : ils interrogent la formation toutes les 3 secondes tant qu'un statut vaut processing. Les jobs terminés disparaissent de active_jobs ; les colonnes de statut restent la vérité métier.

Disque et base#

• Chaque média et document a un relative_path unique : c'est la clé de réconciliation entre le dossier et PostgreSQL.
• Les identifiants sont des UUIDv7 (module uuid de Python 3.14), ordonnés dans le temps, indépendants du chemin.
• Renommer une formation ou un chapitre réécrit les chemins relatifs de son contenu ; réordonner ne touche que position.
• Transcription et résumé sont des fichiers voisins du média (.txt, .md), pas des colonnes.
• Le stream (GET /videos/{id}/stream) gère les requêtes Range, nécessaires au déplacement dans la vidéo.

Le front#

Next.js 16 en App Router, mais toutes les pages sont des composants client : pas de rendu serveur en pratique. L'état vit dans des stores Zustand (auth, catalog, studio, player, theme) ; les appels passent par un client Axios unique (src/services/api.ts) qui envoie le cookie de session (withCredentials) et l'en-tête anti-CSRF X-Requested-With. SessionGate, dans le layout racine, redirige vers /auth sans session ; app/studio/layout.tsx renvoie un apprenant au catalogue. Un 401 efface la session, un 403 affiche « accès refusé » sans déconnecter. L'interface est entièrement en MUI 9 ; le lecteur vidéo est video.js et l'éditeur Markdown @uiw/react-md-editor. Le build Docker produit une sortie standalone, exécutée par un utilisateur non root.