Plateforme pédagogique web pour l'apprentissage du jonglage en contexte scolaire. JuggleFlow propose des parcours progressifs, un catalogue de figures animées, un suivi enseignant en temps réel, un système de gamification (XP, badges, séries) et une conformité RGPD adaptée aux établissements accueillant des mineurs.
L'application fonctionne comme une Progressive Web App (PWA) : elle s'installe sur mobile et reste utilisable hors connexion pendant les séances en salle.
- Fonctionnalités
- Stack technique
- Prérequis
- Installation
- Configuration
- Démarrage
- Comptes de démonstration
- Structure du projet
- Tests
- Stratégie de tests RNCP6
- Déploiement
- Production checklist
- Rôles et parcours utilisateurs
- Conformité RGPD
- Contribuer
- Licence
- Onboarding personnalisé selon le niveau initial (débutant → expert)
- Catalogue de figures avec animations générées par Juggling Lab (notation siteswap)
- Parcours pédagogiques progressifs assignés par l'enseignant
- Suivi de progression par figure (non commencé / en cours / maîtrisé)
- Sessions de pratique chronométrées
- Système de points XP et de rangs (Bronze, Argent, Or)
- Badges de progression (maîtrise, séries, paliers)
- Défi du jour (identique pour tous les élèves d'un même établissement)
- Favoris et ressources pédagogiques (vidéos, exercices, module théorique)
- Mode hors-ligne avec synchronisation différée des mises à jour de progression
- Installation PWA (icône sur l'écran d'accueil, mode standalone)
- Gestion de classes et de groupes colorés (Vert / Orange / Rouge)
- Assignation de parcours à une classe ou individuellement par élève (l'assignation élève est prioritaire sur celle de la classe)
- Tableau de bord : progression moyenne, alertes de blocage par figure
- Fiche individuelle par élève avec historique de progression
- Export CSV de la progression par parcours
- Consultation des ressources pédagogiques
- Gestion des utilisateurs (création, activation/désactivation, réinitialisation de mot de passe)
- Gestion des classes et des établissements
- Gestion des ressources pédagogiques (upload PDF)
- Tableau de bord : statistiques de l'établissement
- Journal d'audit des actions sensibles
- Gestion des licences (plafond de sièges, date d'expiration, édition via l'interface admin)
- Interface RGPD : consentements parentaux, exports CSV/PDF, relance
| Composant | Technologie |
|---|---|
| Monorepo | Nx 22 |
| Frontend | React 19, TypeScript, Tailwind CSS 4, Vite |
| PWA | Workbox (Service Worker, cache offline, sync différée) |
| Backend | Spring Boot 3.4, Java 21 |
| Authentification | JWT (access + refresh token httpOnly), blacklist JTI (Redis recommandé) |
| Base de données | PostgreSQL 17, migrations Flyway |
| Cache / sécurité | Redis 7 (révocation JWT + rate limiting distribués) |
| CI/CD | GitHub Actions (lint, tests, build) |
| Conteneurisation | Docker / Podman (Compose pour le dev local) |
- Node.js 22+ et npm
- Java 21+
- PostgreSQL 17 (local ou via Docker)
- Redis 7 (recommandé, requis en multi-instances)
- Podman ou Docker avec Compose (recommandé pour PostgreSQL, Redis et l’API)
# Cloner le dépôt
git clone https://github.com/votre-org/juggleflow.git
cd juggleflow
# Installer les dépendances Node
npm ciCopier le fichier d'exemple et renseigner les variables obligatoires :
cp apps/backend/.env.example apps/backend/.envOuvrir apps/backend/.env et définir au minimum :
| Variable | Description |
|---|---|
POSTGRES_PASSWORD |
Mot de passe de la base de données |
JWT_SECRET |
Secret JWT (minimum 32 caractères, généré aléatoirement) |
CORS_ALLOWED_ORIGINS |
URL du frontend (ex. https://juggleflow.monecole.fr) |
Toutes les autres variables disposent de valeurs par défaut documentées dans .env.example.
Sécurité — Ne jamais versionner le fichier
.env. Ne jamais utiliser les valeurs par défaut en production.
Les commandes ci-dessous utilisent podman compose ; remplacez par docker compose si vous utilisez Docker Desktop.
# Démarrer PostgreSQL + Redis
podman compose up -d postgres redis
# Démarrer le backend (les migrations Flyway s'exécutent automatiquement)
podman compose up backendL'API est disponible sur http://localhost:8080.
Ce mode ne monte pas le code source dans le conteneur et se rapproche d'un déploiement réel.
Le healthcheck est défini dans compose.prod.yml (Kubernetes utilise des probes).
# Variables minimales (exemples)
export POSTGRES_PASSWORD='change-me'
export JWT_SECRET='change-me-please-generate-a-long-secret-32-chars-minimum'
export CORS_ALLOWED_ORIGINS='http://localhost:4200'
# Podman
podman compose -f compose.prod.yml up -d
# (ou Docker)
docker compose -f compose.prod.yml up -dnpx nx serve frontendL'application est disponible sur http://localhost:4200.
# Créer la base et l'utilisateur PostgreSQL, puis :
cd apps/backend
./mvnw spring-boot:runPour activer les données de démonstration (dev/soutenance uniquement), définir dans .env :
ADMIN_BOOTSTRAP_EMAIL=admin@juggleflow.local
ADMIN_BOOTSTRAP_PASSWORD=<mot-de-passe-complexe>
DEMO_BOOTSTRAP_ENABLED=true
DEMO_BOOTSTRAP_PASSWORD=<mot-de-passe-demo>| Rôle | |
|---|---|
| Administrateur | admin@juggleflow.local |
| Enseignant | marie.dupont@ecole.fr |
| Élève | lucas.martin@ecole.fr |
Ces comptes sont créés uniquement si les variables bootstrap sont définies. Ne jamais activer en production.
Par défaut (sans DEMO_BOOTSTRAP_ENABLED / ADMIN_BOOTSTRAP_*), les comptes sont gérés via l’interface Admin :
- Admin : crée des comptes (élèves / enseignants / administrateurs) via
Admin → Utilisateurs.- Si aucun mot de passe n’est fourni, le serveur en génère un et le renvoie une seule fois.
- Enseignant (Option B) : peut créer un compte élève directement depuis
Enseignant → Élèves(section Créer un élève).- Le mot de passe est généré par le serveur et doit être transmis à l’élève (affiché une seule fois).
- L’élève est rattaché immédiatement à la classe sélectionnée.
juggleflow/
├── apps/
│ ├── frontend/ # PWA React (élève, enseignant, admin)
│ │ ├── src/
│ │ │ ├── api/ # Couche d'appels HTTP + wrappers offline
│ │ │ ├── components/ # Composants réutilisables
│ │ │ ├── pages/ # Pages par rôle (student/, teacher/, admin/)
│ │ │ ├── hooks/ # Hooks React (statut réseau, PWA…)
│ │ │ └── utils/ # Logique métier (offline queue, pathProgress…)
│ │ └── vite.config.mts
│ └── backend/ # API Spring Boot
│ ├── src/main/java/com/juggleflow/backend/
│ │ ├── controller/ # Endpoints REST
│ │ ├── service/ # Logique métier
│ │ ├── model/ # Entités JPA
│ │ ├── dto/ # Objets de transfert
│ │ ├── repository/ # Couche d'accès données (Spring Data)
│ │ └── security/ # JWT, filtres, rate limiting
│ └── src/main/resources/db/migration/ # Migrations Flyway (V1 → V18)
├── docker-compose.yml # Stack dev locale
├── .github/workflows/ci.yml # Pipeline CI
└── nx.json # Configuration Nx
Stratégie détaillée pour le dossier RNCP6 : docs/RNCP6-TESTS.md.
npx nx test frontend # Tests unitaires (Vitest)
npx nx lint frontend # Lint ESLintPrérequis : PostgreSQL (+ Redis si APP_JWT_REVOCATION_STORE=redis / APP_RATE_LIMIT_STORE=redis) et API avec données démo (DEMO_BOOTSTRAP_ENABLED=true).
podman compose up -d postgres redis
podman compose up backend
# autre terminal, à la racine du monorepo
npx playwright install chromium
npm run e2e(docker compose fonctionne de la même façon si vous préférez Docker.)
| Variable | Défaut | Usage |
|---|---|---|
E2E_PASSWORD |
Demo2026! |
Mot de passe comptes @ecole.fr |
E2E_TEACHER_EMAIL |
marie.dupont@ecole.fr |
Enseignant CE1 |
E2E_STUDENT_EMAIL |
lucas.martin@ecole.fr |
Élève |
E2E_ADMIN_EMAIL |
admin@juggleflow.local |
Administrateur |
E2E_ADMIN_PASSWORD |
Admin2026! |
Mot de passe admin (CI : ADMIN_BOOTSTRAP_PASSWORD) |
Scénarios dans apps/frontend/e2e/ : smoke, session (refresh/logout), parcours élève, admin RGPD, parcours enseignant (blocage, CSV, assignation), rate limit API (z-rate-limit.spec.ts, exécuté en dernier).
cd apps/backend
./mvnw test # Tests unitaires et d'intégration (JUnit 5)
./mvnw clean package # Build du JARChaque push sur master et chaque pull request déclenchent lint + tests + build (frontend et backend) et la suite E2E Playwright (PostgreSQL + Redis + bootstrap démo) via GitHub Actions.
| Variable | Valeur recommandée |
|---|---|
JWT_SECRET |
Chaîne aléatoire ≥ 64 caractères (openssl rand -base64 64) |
COOKIE_SECURE |
true (HTTPS obligatoire) |
SWAGGER_ENABLED |
false |
APP_TRUSTED_PROXY |
true si derrière un reverse proxy (nginx, Traefik, AWS ALB) |
CORS_ALLOWED_ORIGINS |
URL de production du frontend uniquement |
DEMO_BOOTSTRAP_ENABLED |
false |
ADMIN_BOOTSTRAP_EMAIL |
Laisser vide après la première initialisation |
Si APP_TRUSTED_PROXY=true, le backend utilise la dernière entrée de X-Forwarded-For pour déterminer l'IP client.
C'est intentionnel : derrière un proxy de confiance qui ajoute sa propre IP en fin de liste, cette valeur correspond à l'IP
TCP vue par le proxy et n'est pas forgeable par un client.
Assure-toi que ton proxy est configuré pour :
- Ajouter
X-Forwarded-For(append) et ne pas accepter une valeur fournie par le client sans la réécrire - Ne définir
APP_TRUSTED_PROXY=trueque si le trafic passe bien par ce proxy (sinonX-Forwarded-Forest forgeable)
npx nx build frontend
# Les fichiers statiques sont générés dans apps/frontend/dist/
# À servir via nginx ou un CDN.Voir PRODUCTION_CHECKLIST.md.
Certains checks (Dependency Review / CodeQL) peuvent nécessiter l'activation de fonctionnalités GitHub côté dépôt :
Settings → Security and analysis → Dependency graph: EnableSettings → Security and analysis → Code scanning: Enable (si disponible)
Si ces fonctionnalités ne sont pas disponibles sur ton plan, la CI reste verte : les workflows exécutent les analyses sans upload des résultats.
L'endpoint /actuator/health est exposé pour les sondes Kubernetes et Docker. Il ne retourne aucune information d'infrastructure.
Élève → Onboarding → Catalogue → Parcours → Session → Badges
Enseignant → Classes → Groupes → Parcours → Suivi élèves → Export CSV
Admin → Utilisateurs → Licences → RGPD → Audit
Le système de groupes colorés (Vert / Orange / Rouge) permet à l'enseignant de segmenter sa classe selon la progression et d'identifier rapidement les élèves en difficulté ou bloqués sur une figure.
JuggleFlow est conçu pour les établissements scolaires accueillant des mineurs :
- Consentement parental requis, versionné et horodaté
- Expiration automatique des consentements (durée configurable, défaut : 1 an scolaire)
- Export des données personnelles au format PDF ou CSV (droit d'accès)
- Suppression et anonymisation via l'interface admin
- Journal d'audit de toutes les actions sensibles (création, réinitialisation de mot de passe, désactivation)
- Aucune donnée partagée avec des tiers
- Créer une branche à partir de
master:git checkout -b feat/ma-fonctionnalite - Suivre les conventions de commit (conventional commits recommandé)
- S'assurer que les tests passent :
npm run testet./mvnw test - Ouvrir une pull request avec une description claire de la modification
MIT — voir LICENSE pour les détails.
JuggleFlow — Projet pédagogique. Animations de jonglage générées par Juggling Lab (logiciel libre, licence GPL).