🎮 Quiz Master - Jeu de Questions Interactif

📋 Description

Quiz Master est une application web interactive de quiz multijoueur. Les utilisateurs peuvent participer à des quiz dans différentes catégories, compétitionner en mode duel, consulter des statistiques détaillées et se classer dans un leaderboard.

Le projet comporte deux briques :

Frontend (vanilla JS, sans dépendance) — jouable seul, persistance en localStorage.
Backend REST (Node/Express + MongoDB, JWT, rate-limiting) — API complète (auth, scores, leaderboard, stats).

⚠️ État actuel : le frontend et le backend sont présents mais pas encore branchés ensemble — le frontend fonctionne en autonome (localStorage). Connecter le frontend à l'API REST est la prochaine étape (voir Roadmap).

Caractéristiques principales

✨ Expérience utilisateur

🎯 Interface moderne et responsive
🌙 Mode sombre/clair
📱 Entièrement compatible mobile
♿ Accessible (WCAG AA)
🔊 Effets sonores optionnels

🎮 Gameplay

👤 Mode solo et mode duel (2 joueurs)
📚 5 catégories de questions (Géographie, Sciences, Art, Histoire, Animaux)
🎓 3 niveaux de difficulté (Facile, Moyen, Difficile)
⏱️ Questions chronométrées
🔀 Mélange aléatoire des questions

📊 Gestion des scores

💾 Persistance locale (localStorage)
🏆 Classement global avec tri par score et temps
📈 Statistiques personnelles détaillées
📥 Export en JSON/CSV
🔍 Filtrage par catégorie, joueur, date

🚀 Installation et Utilisation

Prérequis

Un navigateur web moderne (Chrome, Firefox, Edge, Safari)
JavaScript activé

Installation rapide

Clonez le repository

git clone https://github.com/sfrayan/Quiz-Master.git
cd Quiz-Master

Lancez le frontend (autonome, aucune dépendance)

# Option 1: ouvrir directement index.html
# Option 2: serveur local (recommandé)
python -m http.server 8000
# Puis visitez http://localhost:8000

(Optionnel) Lancez le backend REST

cd backend
cp .env.example .env      # configurez MONGODB_URI + JWT_SECRET
npm install
npm run dev               # http://localhost:5000  (MongoDB requis)

Le frontend n'appelle pas encore cette API (persistance localStorage).

Comment jouer

🏠 Sur la page d'accueil, choisissez Mode Solo ou Mode Duel
👤 Entrez le nom du/des joueur(s)
🎯 Sélectionnez une catégorie de questions
🎓 Choisissez un niveau de difficulté
❓ Répondez aux questions
🏆 Consultez vos résultats et votre classement

📁 Structure du Projet

Quiz-Master/
├── index.html              # Page HTML principale (frontend)
├── data/
│   └── questions.json      # Base de questions (catégorisées)
├── src/
│   ├── js/
│   │   ├── app.js          # Contrôleur principal (logique UI)
│   │   ├── Quiz.js         # Classe Quiz (logique du jeu)
│   │   ├── Storage.js      # Persistance localStorage
│   │   ├── Timer.js        # Chronomètre
│   │   └── Utils.js        # Utilitaires (validation, sanitization…)
│   └── css/                # main.css, responsive.css, timer.css
├── backend/                # API REST (Node/Express + MongoDB) — non branchée au front
│   ├── server.js
│   ├── models/             # User, Game, Score
│   ├── routes/             # auth, questions, scores, leaderboard, stats, users
│   ├── middleware/auth.js  # JWT
│   ├── Dockerfile · docker-compose.yml
│   └── package.json
├── README.md
└── LICENSE

🎨 Architecture Technique

Architecture modulaire

L'application utilise une architecture orientée objet et modulaire :

┌─────────────────────────────────────────┐
│         HTML (index.html)               │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│    app.js (Contrôleur Principal)        │
│  - Gère l'interface utilisateur          │
│  - Coordonne Quiz et Storage             │
│  - Valide les entrées utilisateur        │
└─────────────────────────────────────────┘
         ↙          ↘
┌──────────────┐  ┌──────────────────┐
│  Quiz.js     │  │  Storage.js      │
│  - Logique   │  │  - Persistance   │
│    du jeu    │  │  - Leaderboard   │
│  - Scoring   │  │  - Stats         │
└──────────────┘  └──────────────────┘
         ↓
┌─────────────────────────────────────────┐
│      Utils.js (Utilitaires)             │
│  - Validation, formatage, sanitization  │
│  - Effets sonores, notifications        │
└─────────────────────────────────────────┘

Technologies

Frontend

HTML5, CSS3, JavaScript ES6+ (sans framework ni dépendance)
Persistance : localStorage
Architecture orientée objet / MVC, responsive mobile-first

Backend (REST, indépendant)

Node.js / Express, MongoDB (Mongoose)
Auth JWT (bcrypt), sécurité helmet + express-rate-limit + validator
Conteneurisé (Dockerfile + docker-compose)

🧩 Classes Principales

Quiz.js

Gère la logique du jeu :

const quiz = new Quiz({
  category: 'géographie',      // Catégorie
  difficulty: 'moyen',         // Difficulté
  mode: 'solo',                // solo ou duel
  players: ['Alice'],          // Joueurs
  maxQuestions: 10             // Nombre de questions
});

// Charger les questions
await quiz.loadQuestions(questionsData);

// Démarrer
quiz.start();

// Vérifier une réponse
const isCorrect = quiz.checkAnswer('réponse', 0);

// Résultats
const results = quiz.getResults();

Méthodes principales :

loadQuestions() - Charge les questions
checkAnswer() - Valide une réponse
nextQuestion() - Passe à la question suivante
getResults() - Retourne les résultats
getTypeStatistics() - Stats par type de question

Storage.js

Gère la persistance des données :

const storage = new Storage();

// Sauvegarder un score
storage.saveScore({
  playerName: 'Alice',
  category: 'géographie',
  score: 42,
  time: 120,
  difficulty: 'moyen'
});

// Récupérer le leaderboard
const leaderboard = storage.getLeaderboard(50);

// Statistiques d'un joueur
const stats = storage.getPlayerStats('Alice');

// Exporter en CSV
const csv = storage.exportScoresCSV();

Méthodes principales :

saveScore() - Enregistre un score (validé)
getScores() - Récupère les scores avec filtres
getLeaderboard() - Classement général
getPlayerStats() - Stats personnelles
getCategoryStats() - Stats par catégorie
exportScoresCSV() - Export en CSV

Utils.js

Fonctions utilitaires :

// Validation
const validation = Utils.validatePlayerName('Alice');
if (!validation.valid) console.error(validation.error);

// Formatage
Utils.formatTime(125);                      // "02:05"
Utils.formatDate('2026-01-24');             // "24/01/2026 10:34"

// Sanitization
const safe = Utils.sanitizeInput(userInput);

// Notifications
Utils.showNotification('Bravo !', 'success');

// Effets sonores
Utils.playSound('correct');  // "correct", "wrong", "complete"

💾 Format des Données

Questions (questions.json)

{
  "categories": {
    "géographie": {
      "name": "Géographie",
      "emoji": "🌍",
      "questions": [
        {
          "id": "geo_1",
          "type": 1,
          "difficulty": "facile",
          "question": "...",
          "options": ["Oui", "Non"],
          "answer": "Non",
          "explanation": "..."
        }
      ]
    }
  }
}

Scores (localStorage)

{
  "scores": [
    {
      "id": 1705967452000,
      "playerName": "Alice",
      "category": "géographie",
      "score": 42,
      "time": 120,
      "difficulty": "moyen",
      "date": "2026-01-24T09:30:52.000Z",
      "timestamp": 1705967452000
    }
  ],
  "settings": {
    "theme": "light",
    "sound": true,
    "difficulty": "all"
  }
}

🔐 Sécurité

✅ Sanitization : Toutes les entrées utilisateur sont nettoyées (XSS protection)
✅ Validation : Validation stricte des noms et des réponses
✅ Storage : Pas de données sensibles, localStorage uniquement
✅ HTTPS : Compatible avec les sites HTTPS/HTTP

♿ Accessibilité

L'application respecte WCAG 2.1 niveau AA :

🎨 Contraste de couleur ≥ 4.5:1
⌨️ Navigation complète au clavier
🔊 Indicateurs visuels et auditifs
📱 Cibles tactiles ≥ 44px
🎬 Respect des préférences de mouvement réduit
📱 Mode contraste élevé supporté

📊 Statistiques et Analytics

L'application collecte et affiche :

📈 Nombre total de parties jouées
🎯 Points cumulés
⏱️ Temps moyen par partie
📚 Répartition par catégorie
👤 Meilleur score personnel
🏆 Classement global
📊 Taux de précision par type de question

🚀 Améliorations Futures (Roadmap)

Court terme (v2.1)

Indicateur de progrès pendant le chargement
Animations de réponse correcte/incorrecte
Système de achievements/badges
Questions supplémentaires (50+ de plus)

Moyen terme (v3.0)

Backend Node.js + MongoDB (présent)
Authentification JWT (présent côté backend)
Brancher le frontend sur l'API REST (scores/leaderboard serveur au lieu de localStorage)
Parties en ligne multijoueur
Mode équipe/ligue

Long terme (v4.0)

🤝 Contribution

Les contributions sont bienvenues ! Voici comment participer :

Fork le repository
Créez une branche (git checkout -b feature/amazing-feature)
Commitez vos changements (git commit -m 'Add amazing feature')
Poussez (git push origin feature/amazing-feature)
Ouvrez une Pull Request

Guidelines

Respectez le style de code existant
Testez votre code
Ajoutez des commentaires pour le code complexe
Mettez à jour la documentation

📝 Changelog

v2.0 (2026-01-24)

✨ Architecture complètement refactorisée
🎨 Nouveau design moderne avec dark mode
💾 localStorage pour persistance
📱 Responsive design mobile-first
♿ Accessibilité WCAG AA
📊 Système de statistiques avancé
🔒 Validation et sanitization strictes
📖 Documentation complète

v1.0 (2024)

🎮 Version initiale
✅ Mode solo et duel
📚 5 catégories
🏆 Classement simple

📄 License

Ce projet est licensé sous la Licence MIT - consultez le fichier LICENSE pour plus de détails.

👨‍💻 Auteur

SAID FARAH Rayan - GitHub

📞 Support

Pour toute question ou problème :

🐛 Ouvrez une Issue
📧 Contactez l'auteur

🙏 Remerciements

Merci à tous les contributeurs et à la communauté pour leur soutien !

Fait avec ❤️ en 2026

Name		Name	Last commit message	Last commit date
Latest commit History 42 Commits
backend		backend
data		data
src		src
.gitignore		.gitignore
BACKEND_SETUP.md		BACKEND_SETUP.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
GETTING_STARTED.md		GETTING_STARTED.md
IMPLEMENTATION_ROADMAP.md		IMPLEMENTATION_ROADMAP.md
README.md		README.md
index.html		index.html

Folders and files

Latest commit

History

Repository files navigation