Contact
Travaillons ensemble
GamesUP - Plateforme E-Commerce de Jeux de Société avec Recommandations ML

GamesUP - Plateforme E-Commerce de Jeux de Société avec Recommandations ML

API backend complète pour une plateforme e-commerce de jeux de société avec moteur de recommandation KNN, sécurité JWT et 81% de couverture de tests - construite avec Spring Boot 3, Python FastAPI et Docker.

Septembre 2024 - Janvier 2025
~8 semaines de développement actif
Lead Technique & Développeur Solo (Assiste par IA)
Java 17Spring Boot 3.3.4Spring Security 6JWT (HMAC-SHA256)JPA / HibernateMySQL 8.0Python 3.11FastAPIscikit-learn (KNN)Docker ComposeJUnit 5MockitoJaCoCoMavenLombok

Lignes de code

32,600

Java + Python

Tests automatises

364

273 unitaires + 91 intégration

Couverture de code

81%

JaCoCo (97% sur les services)

Endpoints API

65+

Endpoints REST sur 11 controllers

Présentation

Définition et périmètre du projet

GamesUP est une API backend pour une plateforme e-commerce de jeux de société qui intégré un système de recommandation par apprentissage automatique base sur l'algorithme K-Nearest Neighbors (KNN). Le projet a été réalisé dans le cadre d'une étude de cas professionnelle pour une certification de niveau 7 (Expert en Ingenierie du Logiciel) delivrée par l'ESIEA via Visiplus Digital Learning.

La plateforme couvre l'ensemble du cycle e-commerce : gestion du catalogue produits, commandes multi-lignes avec gestion des stocks, authentification JWT avec contrôle d'accès base sur les rôles, recommandations personnalisees, avis et notations, et listes de souhaits.

Un code preexistant laisse par un stagiaire a été evalue et juge en dessous des standards professionnels. La décision a été prise de reconstruire entièrement le backend, en appliquant rigoureusement les principes SOLID, une architecture en couches et des tests complets.

Domaine

E-commerce spécialisé dans les jeux de société - gestion de catalogue, commandes, recommandations, avis utilisateurs

Utilisateurs cibles

Acheteurs de jeux de société (B2C) et administrateurs de la plateforme. Frontend (Angular) prévu mais non inclus dans cette phase (livraison backend uniquement).

Périmètre fonctionnel
Catalogue produits (CRUD)
Commandes multi-lignes & stocks
Authentification JWT & RBAC
Recommandations ML (KNN)
Avis & notations
Gestion de wishlists
Recherche multi-critères
Orchestration Docker
System Architecture
3-layer architecture: Presentation (planned), Application (Java + Python), Data (MySQL)
Project Metrics

Objectifs, Contexte, Enjeux & Risques

Vision stratégique et contraintes

Objectifs
  • Reconstruire l'API Spring Boot avec une architecture en couches et les principes SOLID
  • Implementer Spring Security 6 avec authentification JWT et gestion des rôles (ADMIN, CLIENT)
  • Développer un système de recommandation KNN via un microservice Python FastAPI
  • Atteindre minimum 70% de couverture de tests avec JaCoCo, JUnit 5 et Mockito
  • Produire une documentation UML complète (diagrammes de classes, composants, sequence, architecture)
Contexte

Le projet est ne d'une exigence de certification professionnelle (ESIEA Niveau 7, Bloc 4 - Conception avancée de l'architecture de logiciel). Le backend existant generait des dysfonctionnements récurrents impactant le chiffre d'affaires et l'expérience utilisateur. Un stagiaire avait été charge de créer une nouvelle API Spring Boot, mais le code ne respectait pas les standards de qualité.

Jose DA COSTA a repris le projet avec pour mission de reconstruire entièrement le backend en une solution professionnelle, fonctionnelle et evolutive. Le projet a été réalisé individuellement sur environ 8 semaines, avec un développement assisté par IA (Claude Code) pour l'implémentation sous la direction technique et les décisions d'architecture de Jose.

Enjeux

Qualité architecturale

Démontrer la maîtrise de la conception avancée de logiciel (SOLID, design patterns, architecture en couches) à travers une application concrète

Innovation technique

Intégrer un système de recommandation ML (KNN) dans une architecture e-commerce classique via une communication inter-API

Certification professionnelle

Valider 4 compétences du Bloc 4 du titre RNCP Expert en Ingenierie du Logiciel (C.14, C.16, C.17, C.18)

Risques identifies

Code du stagiaire inutilisable

Le code existant ne respectait pas les standards de qualité, nécessitant une refonte complete.

Modèle ML non entrainable

Données de production insuffisantes pour l'entrainement KNN. Attenuation : mode demo fonctionnel avec architecture prete pour un entrainement futur.

Failles de sécurité JWT

Une implémentation JWT incorrecte pourrait exposer l'application. Attenuation : implémentation rigoureuse de Spring Security 6 + HMAC-SHA256.

Couverture de tests < 70%

Stratégie de test systematique nécessaire pour depasser le seuil JaCoCo de 70% par package.

Complexité inter-API

La communication Java-Python via RestTemplate nécessitait des healthchecks et l'orchestration Docker Compose.

Matrice d'évaluation des risques

Les étapes - Ce que j'ai fait

Phases chronologiques et contributions personnelles

Progression du développement sur 8 semaines
Phase 1
Phase 1 - Architecture & UML
Semaines 1-2
  • Analyse des exigences et identification de toutes les fonctionnalités
  • Conception de l'architecture 3 couches (Présentation, Applicative, Données)
  • Création de 4 diagrammes UML en Draw.io (architecture, classes, composants, sequence)
  • Sélection de la stack technique : Spring Boot 3.3.4 + Java 17, MySQL 8.0, Python 3.11 + FastAPI
Phase 2
Phase 2 - Fondations JPA
Semaines 2-3
  • Création de 10 entites JPA avec annotations completes et relations bidirectionnelles
  • Définition des enumerations (Rôle : CLIENT/ADMIN, PurchaseStatus : 5 états)
  • Utilisation de Lombok (@Data, @Builder) pour réduire le code boilerplate
  • Configuration d'Hibernate avec génération automatique du schema (ddl-auto=update)
Phase 3
Phase 3 - Couche Service avec SOLID
Semaines 4-5
  • Implémentation de 11 interfaces de services + 11 implémentations respectant les 5 principes SOLID
  • Application de l'injection de dépendances par constructeur, gestion @Transactional
  • Création d'exceptions personnalisees (ResourceNotFound, DuplicateResource, InsufficientStock)
  • Documentation de chaque principe SOLID avec des exemples concrets du code
Phase 4
Phase 4 - Sécurité & JWT
Semaines 5-6
  • Configuration de Spring Security 6 avec filtre JWT personnalise (JwtAuthenticationFilter)
  • Implémentation de la génération/validation de tokens HMAC-SHA256 via JwtUtil
  • Hashing BCrypt des mots de passe, @PreAuthorize base sur les rôles
  • Gestion de sessions stateless avec differenciation des endpoints publics/authentifies/admin
Phase 5
Phase 5 - Controllers REST & DTOs
Semaine 6
  • Construction de 11 controllers REST avec 65+ endpoints couvrant toutes les fonctionnalités métier
  • Création de 28 DTOs (Request + Response) pour isoler les entites de la couche présentation
  • Développement de 9 mappers pour la conversion Entity <-> DTO
  • Implémentation du wrapper générique ApiResponse<T> et de Bean Validation (@Valid)
Phase 6
Phase 6 - Système de recommandation ML
Semaine 7
  • Construction du filtrage collaboratif côté Java (recommandations par achats, jeux similaires, tendances)
  • Création du microservice Python FastAPI avec algorithme KNN de scikit-learn
  • Implémentation de la matrice utilisateur-item avec normalisation StandardScaler
  • Mise en place de la communication inter-API via RestTemplate HTTP (synchrone)
Phase 7
Phase 7 - Tests & Qualité
Semaine 8
  • Rédaction de 364 tests (273 unitaires + 91 intégration) avec JUnit 5, Mockito, MockMvc
  • Atteinte de 81% de couverture globale (JaCoCo) - 97% sur la couche service
  • Configuration de JaCoCo avec seuil minimum de 70% par package
  • Utilisation de la base H2 en mémoire pour l'exécution isolée des tests
Data Model (11 Tables)
Entity-Relationship diagram - 11 tables including game_authors join table
KNN Recommendation Pipeline
K-Nearest Neighbors recommendation pipeline: user-item matrix, cosine similarity, neighbor selection, personalized output
Docker Infrastructure
4 containers on games-up-network: MySQL, Spring Boot API, FastAPI ML, PHPMyAdmin

Les acteurs - Les interactions

Collaboration et parties prenantes

Il s'agissait d'un projet individuel réalisé avec un développement assisté par IA. Jose DA COSTA a agi en tant que Lead Technique et Directeur de Projet, responsable de toutes les décisions d'architecture, revues qualité, analyse des exigences et validation du livrable final.

Claude Code (IA) a servi de partenaire d'implémentation, executant le code sous la direction de Jose sur la base d'environ 100 prompts traces dans 3 fichiers documentes. Jose a identifié les problèmes (problèmes d'encodage dans PHPMyAdmin, incohérences de documentation), pris les décisions organisationnelles (renommage de dossiers, conventions de structure de fichiers) et produit le document Word final pour la soumission à la certification.

Le code original du stagiaire a été evalue et entièrement remplace - aucun élément du livrable final ne contient de code de la tentative initiale. La contribution du stagiaire se limité au scénario pedagogique justifiant la refonte.

Composition de l'équipe

Jose DA COSTA

Jose DA COSTA - Direction technique, pilotage, revue qualité, décisions d'architecture, tests manuels, rédaction du document final

Claude Code (AI)

Claude Code (IA) - Implémentation du code, tests, documentation, diagrammes, configuration Docker

Stagiaire (anonyme) - Développeur initial (code entièrement reconstruit)

Parties prenantes externes

Visiplus Digital Learning - Organisme de formation

ESIEA - Institution certificatrice (Niveau 7 - Expert en Ingenierie du Logiciel)

Bloc 4 - Conception avancée de l'architecture de logiciel

Methode de travail

Le projet illustre un mode de travail "développeur augmente par IA" : Jose a joue le rôle de CTO/directeur de projet definissant les objectifs, prenant les décisions d'architecture, identifiant les problèmes et validant les livrables. Claude Code a joue le rôle de développeur executant, realisant l'intégralité de l'implémentation technique sous la direction de Jose. Cette approche est cohérente avec l'évolution du métier de développeur à l'ere de l'IA generative.

Distribution de l'effort de développement

Les résultats - Pour moi, pour le projet

Résultats mesurables et impact

Pour le projet
  • Remplacement complet d'un backend obsolete et buggue par une solution professionnelle
  • 65+ endpoints REST couvrant toutes les fonctionnalités métier e-commerce
  • Double système de recommandation : filtrage collaboratif Java + microservice KNN Python
  • Architecture prete pour la production, déployable via Docker Compose avec healthchecks
  • Jeu de données massif (~12 000 enregistrements : 30 categories, 100 éditeurs, centaines de jeux)
  • 42 fichiers de documentation totalisant des milliers de lignes + 16 diagrammes Draw.io
Pour moi
  • Approfondissement de l'expertise en architecture Spring Boot 3 + Spring Security 6
  • Première expérience pratique d'intégration ML (KNN) dans un contexte backend
  • Maîtrise du pattern Interface + Implémentation applique systématiquement sur 11 services
  • Validation du workflow "développeur augmente par IA" pour des projets complexes (~100 prompts traces)
  • Production d'une étude de cas professionnelle de 20+ pages démontrant la compétence architecturale
  • Renforcement de la compréhension des principes SOLID par l'application pratique documentee
Distribution des tests
Couverture de code par package (%)
Couches d'architecture (nombre de composants)

Les lendemains du projet

Ce qui s'est passe après la livraison

Livraison immédiate : Le projet a été soumis sous forme d'étude de cas professionnelle complète (PDF, 20+ pages) pour la certification ESIEA Niveau 7, Bloc 4 - Conception avancée de l'architecture de logiciel. Le livrable comprenait le code source complet, la configuration Docker, les diagrammes UML, les rapports de couverture de tests et un document de réflexion critique.

État actuel : Le backend est fonctionnel et déployable via Docker Compose. Le modèle ML fonctionne en mode demo (algorithme KNN implémenté mais non entraine sur des données de production). Le frontend Angular mentionne dans l'architecture resté à construire, ce qui limité la demonstrabilite du produit final aux tests au niveau API.

Perspective à long terme : Les décisions d'architecture (SOLID, conception en couches, services basés sur des interfaces) ont prouve leur valeur en termes de testabilité (81% de couverture) et d'extensibilite. Le système de recommandation a été conçu avec un chemin d'évolution progressive : V1 (filtrage collaboratif Java) -> V2 (KNN Python, pret mais non entraine) -> V3 (Deep Learning, futur). L'interface RecommendationService permet de changer d'implémentation sans modifier le reste du code.

Depot : Le code source est maintenu dans un depot GitHub prive avec un miroir public sur GitFront pour évaluation.

Mon regard critique

Analyse rétrospective honnete

Ce qui a bien fonctionne

Architecture SOLID rigoureuse

Application systematique des 5 principes SOLID (documentée avec exemples concrets dans PRINCIPES_SOLID.md) conferant au projet une maintenabilité et extensibilite remarquables. Le pattern Controller > Service (Interface) > ServiceImpl > Repository est applique sans exception.

Couverture de tests elevee (81%)

Avec 364 tests et 81% de couverture globale (97% sur la couche service critique), le projet dépassé largement l'objectif de 70%. Stratégie de test mature : tests unitaires isoles avec Mockito, tests d'intégration avec MockMvc, pattern AAA systematique.

Sécurité de niveau professionnel

JWT stateless avec HMAC-SHA256, BCrypt avec salt automatique, contrôle d'accès base sur les rôles (RBAC), endpoints differencies (publics, authentifies, admin uniquement), filtre de sécurité personnalise, sessions stateless.

Documentation exhaustive

42 fichiers Markdown totalisant des milliers de lignes, 8 diagrammes Draw.io avec exports PNG, une étude de cas PDF complète de 20+ pages et un document de réflexion critique de 884 lignes. Chaque aspect du projet est documente.

Ce qui aurait pu être ameliore

Pas de frontend

Le projet livré uniquement l'API backend. Le frontend Angular prévu n'a pas été réalisé, limitant la capacité a démontrer le produit complet.

Pas de pipeline CI/CD

Pas d'intégration continue configurée (GitHub Actions, GitLab CI). Les builds et tests sont manuels, ce qui est un risque pour la maintenance qualité à long terme.

Modèle ML non entraine

Le service Python FastAPI fonctionne uniquement en mode demo. L'algorithme KNN est implémenté mais non entraine faute de données de production.

Optimisations de performance manquantes

Pas de cache Redis, pas de pagination sur les endpoints de liste, problèmes potentiels de requetes N+1 avec les relations JPA.

Secret JWT en dur

Le secret JWT est en clair dans application.properties. En production, il devrait être externalise dans des variables d'environnement ou un gestionnaire de secrets.

Ce que je ferais différemment
  • Adopter le TDD (Test-Driven Development) - les tests ont été ecrits après le code en Phase 8, manquant le feedback de design précoce
  • Intégrer la sécurité des la Phase 2 au lieu de la Phase 5, evitant les problèmes de configuration des tests avec Spring Security
  • Rediger des user stories formelles avec critères d'acceptation avant l'implémentation
  • Utiliser MapStruct au lieu de mappers manuels pour réduire le boilerplate
  • Ajouter la documentation Swagger/OpenAPI pour une exploration interactive de l'API
Leçons durables
  • Les principes SOLID ne sont pas theoriques - leur application concrète amélioré considérablement la qualité, la testabilité et l'extensibilite du code
  • La documentation continue est plus efficace que la documentation en fin de projet - rediger au fur et à mesure produit une meilleure qualité
  • Les tests permettent une évolution sereine - avec 81% de couverture, le refactoring devient plus sur
  • La sécurité doit être conçue des le départ - l'ajouter après coup créé des problèmes d'intégration (illustre par les échecs de tests de controllers)
  • Un système de recommandation ML peut être intégré progressivement - le pattern interface permet de commencer simple et d'évoluer sans refonte majeure