Pinball Three.js

Ce projet a pour ambition de recréer l'expérience d'un flipper physique à travers une architecture web moderne, distribuée et interactive. L'objectif n'est pas seulement de reproduire un jeu, mais de concevoir un système complet temps réel, combinant :

• Simulation physique 3D
• Communication distribuée (WebSockets + MQTT)
• Intégration IoT
• Expérience utilisateur immersive

Le projet vise à démontrer la capacité à concevoir une architecture logicielle complexe inspirée d'un système réel (flipper mécanique) tout en exploitant les technologies web contemporaines. Ce projet est réalisé dans le cadre validation de la troisième année de Bachelor Développeur Web à HETIC, et s'inscrit dans une démarche d'apprentissage par la pratique, en appliquant les concepts de développement web, d'architecture logicielle et de communication temps réel.

---

Lancer le projet

Ce projet est contenu dans un conteneur Docker. Pour le lancer, utilisez la commande suivante dans le terminal à la racine du projet :

docker compose -f compose.dev.yml up -d

Services principaux disponibles en développement :

• Frontend : http://localhost:5173
• Backend API : http://localhost:3000
• Drizzle Studio backend : localhost:4983
• PostgreSQL : localhost:5432
• Mosquitto : localhost:1883
• Login frontend : http://localhost:5173/login

---

Base de données

La base de données du projet repose sur :

• PostgreSQL
• Drizzle ORM
• Drizzle Studio pour la visualisation en développement

Tables actuellement initialisées :

• users
• accounts
• sessions
• verifications
• games
• scores

Exécuter les migrations en développement

Démarrer les services nécessaires si c'est pas encore fait :

docker compose -f compose.dev.yml up -d postgres backend drizzle-studio

Appliquer les migrations Drizzle depuis le conteneur backend :

docker compose -f compose.dev.yml exec backend pnpm db:migrate

Générer une nouvelle migration

Après modification du schéma dans backend/src/db/schema.ts :

docker compose -f compose.dev.yml exec backend pnpm db:generate
docker compose -f compose.dev.yml exec backend pnpm db:migrate

Accéder à la base avec Drizzle Studio

Ouvrir https://local.drizzle.studio.

Le service drizzle-studio est disponible uniquement en développement. Le port 4983 correspond au backend local utilisé par Drizzle Studio.

Authentification

L'authentification est gérée par Better Auth sur le backend Express.

Fonctionnalités branchées :

• credentials email / mot de passe
• OAuth GitHub
• OAuth Google
• session utilisateur accessible dans le Playfield
• session utilisateur accessible dans le Dashboard

Variables à renseigner dans .env :

• BETTER_AUTH_SECRET
• BETTER_AUTH_URL
• FRONTEND_URL
• FRONTEND_ORIGINS
• GITHUB_CLIENT_ID
• GITHUB_CLIENT_SECRET
• GOOGLE_CLIENT_ID
• GOOGLE_CLIENT_SECRET
• SCORE_CLAIM_MODE
• GLOBAL_API_URL
• BORNE_TOKEN

Le flux QR code avec VPS est détaillé dans docs/score-claim-vps.md.

Production

En production, les migrations sont exécutées par le service migrate avant le démarrage du backend. Il n'y a pas d'interface d'administration de la base exposée.

Commande de déploiement VPS :

docker compose -p flipper-project -f deploy/docker-compose.vps.yml up -d --build

Commande Pour voir si un score à été bien rattaché à un utilisateur :

sudo docker exec pinball-postgres sh -lc 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c "SELECT scr.claim_code, scr.status, scr.user_id, u.email, scr.approved_at FROM score_claim_requests scr LEFT JOIN users u ON u.id = scr.user_id ORDER BY scr.created_at DESC LIMIT 10;"'

Le fichier deploy/docker-compose.yml reste réservé au déploiement du flipper physique via fliphetic.toml. Il build le frontend complet avec VITE_APP_TARGET=flipper par défaut.

---

Tests

Les tests sont situés dans frontend/src/tests/ et s'exécutent depuis le dossier frontend/.

Lancer les tests :

cd frontend
pnpm test

Vérifier la couverture de code (seuil minimum : 80%) :

cd frontend
pnpm coverage

Le rapport de couverture HTML est généré dans frontend/coverage/ (ignoré par git).

Tests backend

Les tests d'intégration backend utilisent une base PostgreSQL jetable créée puis supprimée à chaque suite.

Points de sécurité importants :

• backend/.env.test.local doit définir DATABASE_URL_TEST vers une base d'administration PostgreSQL capable de créer des bases temporaires, typiquement postgres.
• DATABASE_URL dans ce même fichier doit pointer vers une base sandbox dédiée et sans données utiles, jamais vers pinball_db.
• Les détails de configuration sont documentés dans backend/README.md.
• La stratégie de tests du projet est documentée dans docs/strategie-tests.md.

---

Collaborateurs :

• Adrien Allard (Chef de projet)
• Stéphane Descarpentries
• Amaury Sanchez
• Christopher De Pasqual