# Architecture technique — Immbot AI

# Pile retenue

Décisions documentées (hypothèses raisonnables adoptées) :

• SQLite plutôt que PostgreSQL en v1 : un seul professeur héberge la plateforme ; node:sqlite en mode WAL supporte largement une cohorte de cours. Le schéma n'utilise rien d'exclusif à SQLite (migration Postgres documentée). pgvector devient utile au-delà de ~100k fragments — on en est loin.
• Pas de Redis/file de tâches en v1 : l'ingestion (~30 documents LaTeX) prend quelques minutes et tourne comme script ou tâche serveur avec journal de progression en BD.

# Structure du projet

immbot-ai/
├── app/                    # Next.js App Router
│   ├── (public)/           # accueil, connexion, inscription
│   ├── (app)/              # chat, apprendre/*, bibliothèque, paramètres (auth requise)
│   ├── (admin)/admin/*     # tableau de bord professeur
│   └── api/                # routes API (auth, chat SSE, rag, learning, admin, uploads)
├── components/             # UI (ui/ primitives, chat/, learning/, admin/)
├── lib/
│   ├── db/                 # connexion node:sqlite, schéma, migrations, requêtes
│   ├── auth/               # sessions, mots de passe, permissions, rate-limit
│   ├── openrouter/         # registre de modèles, client streaming, coûts, presets
│   ├── rag/                # parseur LaTeX, chunker, embeddings, recherche hybride, citations
│   ├── learning/           # SM-2, maîtrise, quiz adaptatif, examens, plan d'étude, recommandations
│   ├── analytics/          # événements, agrégats anonymisés
│   └── security/           # validation, sanitisation
├── prompts/                # prompts système modulaires versionnés (fichiers .md)
├── scripts/                # setup, dev, build, seed-admin, ingest-courses, reindex, test, verify, backup
├── tests/                  # vitest
├── evaluation/             # jeux de test RAG + rapport
├── docs/                   # la présente documentation
├── data/                   # immbot.db, uploads/, cache modèles (gitignoré)
└── public/                 # logo SVG, actifs

# Flux principaux

# Chat RAG (mode « Cours uniquement »)

1. POST /api/chat (auth + vérification d'accès au cours + budget).
2. Analyse de la question → détection du sujet ; embedding local de la requête.
3. Recherche hybride dans l'espace du cours choisi : FTS5 (BM25) + cosinus, fusion RRF, filtres métadonnées, expansion aux fragments voisins, dédoublonnage → top-k équilibré.
4. Construction du contexte : fragments numérotés [S1]…[Sn] avec métadonnées (séance, diapositive) + prompt système assemblé (base + rag-grounding + citation-policy + cours + mode).
5. Appel OpenRouter en streaming, relayé au client en SSE ; le modèle cite [S3].
6. Post-validation : toute référence [Sx] absente du contexte est neutralisée ; les citations valides sont résolues en objets cliquables (document, séance, diapositive, extrait).
7. Journalisation : jetons, coût, latence, fragments servis (pour l'évaluation RAG).

# Ingestion

scripts/ingest-courses.ts (ou bouton admin) : scan des dossiers de cours → détection de type → somme de contrôle (réingestion incrémentale) → parseur LaTeX (frames beamer numérotées en diapositives, sections, boîtes sémantiques, équations, tableaux) → fragments structurés avec métadonnées complètes → FTS5 + embeddings par lots → rapport (docs/ingestion-report.md + table ingestion_runs).

# Moteur de maîtrise

Chaque interaction évaluable (carte, question de quiz, item d'examen) émet un événement (concept, correct, difficulté, autonomie, confiance) ; la maîtrise par concept est un score composite à décroissance temporelle (voir learning-science-strategy.md), agrégé par thème et cours.

# Performance

RSC par défaut, composants client uniquement où nécessaire (chat, cartes interactives) · embeddings et registre de modèles en cache mémoire avec TTL · requêtes préparées réutilisées · index SQL sur toutes les clés de recherche · streaming immédiat (TTFB < 1 s hors latence modèle).