--- title: "GamesUP - Board Game E-Commerce Platform with ML Recommendations" description: "Complete backend API for a board game e-commerce platform with a KNN-based recommendation engine, JWT security, and 81% test coverage - built with Spring Boot 3, Python FastAPI, and Docker." locale: "en" canonical: "https://portfolio.josedacosta.info/en/achievements/gamesup-plateforme-ecommerce-ml" source: "https://portfolio.josedacosta.info/en/achievements/gamesup-plateforme-ecommerce-ml.md" html_source: "https://portfolio.josedacosta.info/en/achievements/gamesup-plateforme-ecommerce-ml" author: "José DA COSTA" date: "2024" type: "achievement" slug: "gamesup-plateforme-ecommerce-ml" tags: ["Java 17", "Spring Boot 3.3.4", "Spring Security 6", "JWT", "JPA/Hibernate", "MySQL 8.0", "Python 3.11", "FastAPI", "scikit-learn", "Docker Compose", "JUnit 5", "Mockito", "JaCoCo"] generated_at: "2026-04-23T15:46:42.265Z" --- # GamesUP - Board Game E-Commerce Platform with ML Recommendations Complete backend API for a board game e-commerce platform with a KNN-based recommendation engine, JWT security, and 81% test coverage - built with Spring Boot 3, Python FastAPI, and Docker. **Date:** September 2024 - January 2025 **Duration:** ~8 weeks of active development **Role:** Technical Lead & Solo Developer (AI-Assisted) **Technologies:** Java 17, Spring Boot 3.3.4, Spring Security 6, JWT, JPA/Hibernate, MySQL 8.0, Python 3.11, FastAPI, scikit-learn, Docker Compose, JUnit 5, Mockito, JaCoCo ### Key Metrics - Lines of Code: **-** - Java + Python - Automated Tests: **-** - 273 unit + 91 integration - Code Coverage: **-** - JaCoCo (97% on services) - API Endpoints: **-** - REST endpoints across 11 controllers ## Presentation _Project definition and scope_ ### Domain E-commerce specialized in board games - catalog management, ordering, recommendations, user reviews ### Target Users Board game buyers (B2C) and platform administrators. Frontend (Angular) planned but not included in this phase (backend-only delivery). **Content:** **GamesUP** is a backend API for a board game e-commerce platform that integrates a **machine learning recommendation system** based on the K-Nearest Neighbors (KNN) algorithm. The project was built as a professional case study for a Level 7 certification (Expert in Software Engineering) delivered by ESIEA through Visiplus Digital Learning. The platform covers the complete e-commerce lifecycle: product catalog management, multi-line ordering with stock management, JWT-based authentication with role-based access control, personalized recommendations, reviews and ratings, and wishlists. A pre-existing codebase left by an intern was evaluated and found to be below professional standards. The decision was made to **rebuild the entire backend from scratch**, applying rigorous SOLID principles, layered architecture, and comprehensive testing. **Domain:** Domain **Target Users:** Target Users **Functional Scope:** Functional Scope **Scope Catalog:** Product Catalog (CRUD) **Scope Orders:** Multi-line Orders & Stock **Scope Auth:** JWT Authentication & RBAC **Scope M L:** ML Recommendations (KNN) **Scope Reviews:** Reviews & Ratings **Scope Wishlist:** Wishlist Management **Scope Search:** Multi-criteria Search **Scope Docker:** Docker Orchestration ## Objectives, Context, Stakes & Risks _Strategic vision and constraints_ ### Context The project originated from a professional certification requirement (ESIEA Level 7, Block 4 - Advanced Software Architecture). The existing backend was generating recurring bugs that impacted revenue and user experience. An intern had been tasked with creating a new Spring Boot API, but the code did not meet quality standards. José DA COSTA took over the project with a mandate to **completely rebuild the backend** into a professional, functional, and scalable solution. The project was carried out individually over approximately 8 weeks, with AI-assisted development (Claude Code) for implementation under José's technical direction and architectural decisions. ### Stake Quality Demonstrate mastery of advanced software design (SOLID, design patterns, layered architecture) through a real-world application ### Stake Innovation Integrate a machine learning recommendation system (KNN) within a classical e-commerce architecture via inter-API communication ### Stake Certification Validate 4 competencies of Block 4 of the RNCP Expert in Software Engineering title (C.14, C.16, C.17, C.18) - Rebuild the Spring Boot API with proper layered architecture and SOLID principles - Implement Spring Security 6 with JWT authentication and role-based access (ADMIN, CLIENT) - Develop a KNN-based recommendation system via a Python FastAPI microservice - Achieve minimum 70% test coverage with JaCoCo, using JUnit 5 and Mockito - Produce complete UML documentation (class, component, sequence, architecture diagrams) **Objectives:** Objectives **Context:** Context **Stakes:** Business Stakes **Stake Quality:** Architectural Quality **Stake Innovation:** Technical Innovation **Stake Certification:** Professional Certification **Risks:** Identified Risks **Risk1 Title:** Intern Code Unusable **Risk1 Desc:** The existing code did not meet quality standards, requiring a full rebuild from scratch. **Risk2 Title:** ML Model Not Trainable **Risk2 Desc:** Insufficient production data for KNN training. Mitigation: functional demo mode with architecture ready for future training. **Risk3 Title:** JWT Security Flaws **Risk3 Desc:** Incorrect JWT implementation could expose the application. Mitigation: rigorous Spring Security 6 + HMAC-SHA256 implementation. **Risk4 Title:** Test Coverage Below 70% **Risk4 Desc:** Systematic testing strategy needed to exceed the JaCoCo threshold of 70% per package. **Risk5 Title:** Inter-API Complexity **Risk5 Desc:** Java-Python communication via RestTemplate required healthchecks and Docker Compose orchestration. ## The Steps - What I Did _Chronological phases and personal contributions_ - Phase 1 - Architecture & UML - Phase 2 - JPA Foundations - Phase 3 - Service Layer with SOLID - Phase 4 - Security & JWT - Phase 5 - REST Controllers & DTOs - Phase 6 - ML Recommendation System - Phase 7 - Testing & Quality **Phase1 Period:** Weeks 1-2 **Phase2 Period:** Weeks 2-3 **Phase3 Period:** Weeks 4-5 **Phase4 Period:** Weeks 5-6 **Phase5 Period:** Week 6 **Phase6 Period:** Week 7 **Phase7 Period:** Week 8 ## The Team - Interactions _Collaboration and stakeholders_ ### Work Method The project illustrates an **"AI-augmented developer"** working model: José played the role of CTO/project director defining objectives, making architecture decisions, identifying problems, and validating deliverables. Claude Code played the role of executing developer, carrying out all technical implementation under José's direction. This approach is consistent with the evolution of the developer profession in the era of generative AI. **Content:** This was an **individual project** carried out with AI-assisted development. José DA COSTA acted as **Technical Lead and Project Director**, responsible for all architectural decisions, quality reviews, requirement analysis, and final deliverable validation. **Claude Code (AI)** served as the implementation partner, executing code under José's direction based on approximately 100 traced prompts across 3 documented prompt files. José identified problems (encoding issues in PHPMyAdmin, documentation inconsistencies), made organizational decisions (folder renaming, file structure conventions), and produced the final Word document for certification submission. The intern's original code was evaluated and entirely replaced - none of the final deliverable contains code from the initial attempt. The intern's contribution was limited to the pedagogical scenario justifying the rebuild. **Team Composition:** Team Composition **Team Jose:** José DA COSTA - Technical direction, piloting, quality review, architecture decisions, manual testing, final document writing **Team A I:** Claude Code (AI) - Implementation of code, tests, documentation, diagrams, Docker configuration **Team Intern:** Intern (anonymous) - Initial developer (code entirely rebuilt) **Stakeholders:** External Stakeholders **Stakeholder Training:** Visiplus Digital Learning - Training organization **Stakeholder Certification:** ESIEA - Certifying institution (Level 7 - Expert in Software Engineering) **Stakeholder Block:** Block 4 - Advanced Software Architecture Design **Work Method:** Work Method ## Results - For Me, For the Project _Measurable outcomes and impact_ **For Project:** For the Project **For Me:** For Me ## The Project Aftermath _What happened after delivery_ **Content:** **Immediate delivery:** The project was submitted as a complete professional case study (PDF, 20+ pages) for the ESIEA Level 7 certification, Block 4 - Advanced Software Architecture Design. The deliverable included the full source code, Docker configuration, UML diagrams, test coverage reports, and a critical reflection document. **Current state:** The backend is functional and deployable via Docker Compose. The ML model operates in demo mode (KNN algorithm implemented but not trained on production data). The Angular frontend mentioned in the architecture remains unbuilt, limiting the demonstrability of the final product to API-level testing. **Long-term perspective:** The architecture decisions (SOLID, layered design, interface-based services) proved their value in terms of testability (81% coverage) and extensibility. The recommendation system was designed with a progressive evolution path: V1 (Java collaborative filtering) -> V2 (Python KNN, ready but untrained) -> V3 (Deep Learning, future). The RecommendationService interface allows swapping implementations without modifying the rest of the codebase. **Repository:** The source code is maintained in a private GitHub repository with a public mirror on GitFront for evaluation purposes. ## Critical Reflection _Honest retrospective analysis_ ### Strength - [object Object] - [object Object] - [object Object] - [object Object] ### Improvement - [object Object] - [object Object] - [object Object] - [object Object] - [object Object] ### Would Do - Adopt TDD (Test-Driven Development) - tests were written after the code in Phase 8, missing early design feedback - Integrate security from Phase 2 instead of Phase 5, avoiding test configuration issues with Spring Security - Write formal user stories with acceptance criteria before implementation - Use MapStruct instead of manual mappers to reduce boilerplate - Add Swagger/OpenAPI documentation for interactive API exploration ### Lesson - SOLID principles are not theoretical - their concrète application measurably improves code quality, testability, and extensibility - Continuous documentation is more effective than end-of-project documentation - writing along the way produces better quality - Tests enable confident evolution - with 81% coverage, refactoring becomes safer - Security must be designed from the start - adding it later creates integration problems (illustrated by controller test failures) - An ML recommendation system can be integrated progressively - the interface pattern allows starting simple and evolving without major refactoring **Strengths:** What Worked Well **Improvements:** What Could Be Improved **Would Do Differently:** What I Would Do Differently **Lessons:** Lasting Lessons