Korum

Korum est une application de quiz live pensée pour l’enseignement. Son objectif n’est pas seulement de faire répondre vite, mais de rendre visible la compréhension du groupe et de favoriser l’apprentissage entre pairs quand une notion bloque.

Le projet contient une interface enseignant, une interface participant mobile, un mode live projeté, une logique de peer learning, une gestion des quiz/questions et une synchronisation temps réel via WebSocket.

Objectif pédagogique

Korum repose sur un cycle simple :

1. L’enseignant crée un quiz composé de questions à choix multiples.
2. Les participants rejoignent une session live avec un token ou un QR code.
3. La question s’affiche sur l’écran enseignant, puis les réponses apparaissent après un court délai.
4. Les participants répondent sur leur appareil.
5. Si la majorité réussit, les scores sont affichés et le live passe à la question suivante.
6. Si la classe bloque, Korum lance une phase de peer learning : un participant ayant compris peut expliquer, puis le groupe vote/repond a nouveau.

L’idée est de passer d’un quiz purement compétitif à un outil de diagnostic collectif et d’entraide.

Fonctionnalites principales

• Authentification enseignant avec JWT.
• Gestion des utilisateurs.
• Création, édition et soft delete des quiz.
• Création, édition, soft delete et tri manuel des questions.
• Questions avec 2 à 8 réponses possibles.
• Plusieurs bonnes réponses par question.
• Temps de réponse configurable par question.
• Option de mélange des réponses par quiz, y compris lors d’une seconde tentative en live.
• Sessions live cloisonnees par ID unique et token court.
• Page /join pour rejoindre rapidement une session avec un token.
• QR code SVG affiche dans le live enseignant.
• Interface enseignant projetable, avec lobby, plein écran, thèmes jour/nuit et compteur de participants.
• Interface participant adaptée mobile.
• Synchronisation temps réel avec Socket.io.
• Scores progressifs, podium final et animations.
• Tutoriel integre dans l espace enseignant avec option "ne plus afficher".

Architecture

Korum/
  backend/        API Express, Socket.io, PostgreSQL, auth JWT
  frontend/       Vue 3, Vite, Pinia, Tailwind CSS
  doc/            Cahier des charges initial
  docker-compose.yml
  .env.template

Frontend

• Vue 3
• Vite
• Vue Router
• Pinia
• Tailwind CSS
• lucide-vue-next pour les icônes
• qrcode pour la génération de QR SVG
• socket.io-client pour le live

Backend

• Node.js
• Express
• Socket.io
• PostgreSQL via pg
• JWT et bcryptjs
• Swagger UI
• Winston pour les logs

Base de données

Les tables principales sont :

• users : comptes enseignants et utilisateurs applicatifs.
• projects : quiz.
• exercises : questions du quiz.
• quiz_sessions : sessions live.
• answers : réponses historiques des participants.
• comprehension_votes : votes de compréhension en peer learning.

Les suppressions de quiz et de questions sont faites en soft delete via deleted_at, afin de conserver l’historique des sessions et des réponses.

Prérequis

• Docker Desktop
• Docker Compose

Pour un lancement hors Docker :

• Node.js 22 ou compatible
• PostgreSQL 15 ou compatible

Installation rapide avec Docker

1. Copier le fichier d environnement :

cp .env.template .env

Sous PowerShell :

Copy-Item .env.template .env

2. Lancer l application :

docker compose up --build

3. Ouvrir l application :

• Frontend : http://localhost:5180
• API : http://localhost:3100/api
• Swagger : http://localhost:3100/api/docs
• PostgreSQL exposé sur l’hôte : localhost:55432

Compte de démonstration

Un compte enseignant est créé automatiquement par le schéma de base.

• Email : enseignant@korum.local
• Mot de passe : korum-demo

Variables d environnement

Voir .env.template.

Variables principales :

• PORT : port HTTP du backend, par defaut 3100.
• DATABASE_URL : URL PostgreSQL.
• JWT_SECRET : secret de signature JWT.
• JWT_EXPIRES_IN : durée de validité du token.
• FRONTEND_ORIGIN : origine autorisée par CORS.
• VITE_API_URL : URL de l’API utilisée par le frontend.
• VITE_SOCKET_URL : URL Socket.io utilisée par le frontend.

Dans Docker Compose, les ports actuels sont :

• Frontend : 5180
• Backend : 3100
• PostgreSQL : 55432 côté hôte, 5432 côté conteneur

Parcours de test

1. Aller sur http://localhost:5180.
2. Se connecter avec le compte enseignant.
3. Créer un quiz ou ouvrir un quiz existant.
4. Configurer le titre, la description et le mélange des réponses.
5. Ajouter des questions, régler leur temps et cocher une ou plusieurs bonnes réponses.
6. Reordonner les questions par glisser-deposer si necessaire.
7. Lancer le live.
8. Depuis un autre appareil ou onglet, aller sur /join et saisir le token affiche.
9. Répondre aux questions côté participant.
10. Observer les phases côté enseignant : lobby, question, résultats, peer learning, podium final.

Live et synchronisation

Le live est pilote par Socket.io.

Chaque session live possede :

• un ID UUID interne ;
• un token court de jointure ;
• une room Socket.io dediee ;
• son etat live courant ;
• sa liste de participants ;
• ses réponses par round.

Les sessions sont cloisonnées : les événements reçus côté frontend sont ignorés s’ils ne correspondent pas à la session active.

Phases principales :

• lobby : attente des participants.
• question : affichage de la question et collecte des réponses.
• results : scores et synthese.
• peer-learning : explication par un participant choisi.
• peer-vote : seconde tentative apres explication.
• teacher-help : reprise par l’enseignant si la compréhension reste insuffisante.
• finished : podium final.

Regles metier importantes

• Impossible de démarrer une question sans participant.
• Le QR code et le token permettent de rejoindre une session en cours.
• Les réponses peuvent être mélangées dans un même live, notamment entre tentative initiale et peer learning.
• Les questions archivées ne sont plus proposées dans les nouveaux lives.
• Les projets archivés ne sont plus visibles ni lançables.
• Les anciennes réponses restent conservées pour l’historique.

Commandes utiles

Docker

docker compose up --build
docker compose up --build -d backend frontend
docker compose logs --tail=100 backend
docker compose logs --tail=100 frontend
docker compose down

Backend

Depuis backend/ :

npm install
npm run dev
npm run start
npm run lint
npm run format

Frontend

Depuis frontend/ :

npm install
npm run dev
npm run build
npm run lint
npm run format

Déploiement PaaS

Le projet est prêt pour un déploiement Node.js sur une plateforme PaaS de type Heroku, Render ou Scalingo.

Le mode PaaS prévu est un déploiement en une seule application :

• le frontend Vue est compilé avec Vite ;
• le backend Express démarre le serveur HTTP ;
• Express sert les fichiers statiques du frontend depuis frontend/dist en production ;
• les appels API utilisent /api ;
• Socket.io utilise l’origine courante du navigateur.

Les fichiers racine utiles au déploiement sont :

• package.json : scripts de build et de démarrage depuis la racine ;
• Procfile : commande web: npm start pour les plateformes compatibles Heroku ;
• backend/src/app.js : service du frontend statique en NODE_ENV=production.

Le backend utilise aussi SSL pour PostgreSQL en production, ce qui convient aux bases managées de type Heroku Postgres.

Variables à configurer sur la plateforme

Variables minimales :

NODE_ENV=production
DATABASE_URL=<url PostgreSQL fournie par la plateforme>
JWT_SECRET=<secret long et aléatoire>
JWT_EXPIRES_IN=24h

Variable recommandée si le frontend et le backend ne sont pas servis par la même origine :

FRONTEND_ORIGIN=https://votre-application.example

Dans le cas standard d’une seule application PaaS qui sert à la fois le frontend et le backend, FRONTEND_ORIGIN peut être omise.

Les variables VITE_API_URL et VITE_SOCKET_URL ne sont pas nécessaires pour ce mode, car le frontend utilise par défaut /api et l’origine courante. Elles restent utiles pour un déploiement séparé frontend/backend.

Exemple Heroku

heroku create korum-demo
heroku addons:create heroku-postgresql:essential-0
heroku config:set NODE_ENV=production
heroku config:set JWT_SECRET="un-secret-long-et-aleatoire"
git push heroku main

Au démarrage, le backend exécute le schéma SQL et crée le compte enseignant de démonstration si nécessaire.

Pour vérifier localement le build PaaS sans Docker :

npm run build
NODE_ENV=production DATABASE_URL=postgresql://user:password@localhost:55432/korum_db JWT_SECRET=dev_secret npm start

API

La documentation Swagger est disponible en local :

http://localhost:3100/api/docs

Routes principales :

• /api/auth : connexion et profil.
• /api/users : gestion des utilisateurs.
• /api/projects : quiz.
• /api/exercises : questions.
• /api/sessions : sessions live et réponses.
• /api/health : état de l’API.

Données de démonstration

Un script de seed existe pour ajouter un vrai quiz de démonstration :

backend/src/db/seed_culture_numerique_ia.sql

Il crée un quiz "Culture numérique et IA" avec des questions prêtes à tester.

État du projet

Korum est un MVP évolutif. Les fondations sont en place pour tester un usage réel en classe :

• création de quiz ;
• lancement de sessions parallèles ;
• participation mobile ;
• peer learning ;
• historique conservé ;
• ergonomie de base côté enseignant.

Les prochaines améliorations naturelles seraient l’export de résultats, un tableau d’analyse post-session, une meilleure gestion des groupes/classes et des tests automatisés plus complets.

Licence

Ce projet est distribué sous licence MIT. Voir le fichier LICENSE.