Contact
Let's work together
GamesUP - Board Game E-Commerce Platform with ML Recommendations

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.

September 2024 - January 2025
~8 weeks of active development
Technical Lead & Solo Developer (AI-Assisted)
Java 17Spring Boot 3.3.4Spring Security 6JWT (HMAC-SHA256)JPA / HibernateMySQL 8.0Python 3.11FastAPIscikit-learn (KNN)Docker ComposeJUnit 5MockitoJaCoCoMavenLombok

Lines of Code

32,600

Java + Python

Automated Tests

364

273 unit + 91 integration

Code Coverage

81%

JaCoCo (97% on services)

API Endpoints

65+

REST endpoints across 11 controllers

Presentation

Project definition and scope

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

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).

Functional Scope
Product Catalog (CRUD)
Multi-line Orders & Stock
JWT Authentication & RBAC
ML Recommendations (KNN)
Reviews & Ratings
Wishlist Management
Multi-criteria Search
Docker Orchestration
System Architecture
3-layer architecture: Presentation (planned), Application (Java + Python), Data (MySQL)
Project Metrics

Objectives, Context, Stakes & Risks

Strategic vision and constraints

Objectives
  • 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)
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.

Jose 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 Jose's technical direction and architectural decisions.

Business Stakes

Architectural Quality

Demonstrate mastery of advanced software design (SOLID, design patterns, layered architecture) through a real-world application

Technical Innovation

Integrate a machine learning recommendation system (KNN) within a classical e-commerce architecture via inter-API communication

Professional Certification

Validate 4 competencies of Block 4 of the RNCP Expert in Software Engineering title (C.14, C.16, C.17, C.18)

Identified Risks

Intern Code Unusable

The existing code did not meet quality standards, requiring a full rebuild from scratch.

ML Model Not Trainable

Insufficient production data for KNN training. Mitigation: functional demo mode with architecture ready for future training.

JWT Security Flaws

Incorrect JWT implementation could expose the application. Mitigation: rigorous Spring Security 6 + HMAC-SHA256 implementation.

Test Coverage Below 70%

Systematic testing strategy needed to exceed the JaCoCo threshold of 70% per package.

Inter-API Complexity

Java-Python communication via RestTemplate required healthchecks and Docker Compose orchestration.

Risk Assessment Matrix

The Steps - What I Did

Chronological phases and personal contributions

Development Progress Over 8 Weeks
Phase 1
Phase 1 - Architecture & UML
Weeks 1-2
  • Analyzed requirements and identified all functional features
  • Designed 3-layer architecture (Presentation, Application, Data)
  • Created 4 UML diagrams in Draw.io (architecture, classes, components, sequence)
  • Selected technology stack: Spring Boot 3.3.4 + Java 17, MySQL 8.0, Python 3.11 + FastAPI
Phase 2
Phase 2 - JPA Foundations
Weeks 2-3
  • Created 10 JPA entities with complete annotations and bidirectional relationships
  • Defined enumerations (Role: CLIENT/ADMIN, PurchaseStatus: 5 states)
  • Used Lombok (@Data, @Builder) to reduce boilerplate code
  • Configured Hibernate with automatic schema generation (ddl-auto=update)
Phase 3
Phase 3 - Service Layer with SOLID
Weeks 4-5
  • Implemented 11 service interfaces + 11 implementations following all 5 SOLID principles
  • Applied constructor-based dependency injection, @Transactional management
  • Created custom exceptions (ResourceNotFound, DuplicateResource, InsufficientStock)
  • Documented each SOLID principle with concrète code examples
Phase 4
Phase 4 - Security & JWT
Weeks 5-6
  • Configured Spring Security 6 with custom JWT filter (JwtAuthenticationFilter)
  • Implemented HMAC-SHA256 token generation/validation via JwtUtil
  • BCrypt password hashing, role-based @PreAuthorize on endpoints
  • Stateless session management with public/authenticated/admin-only endpoint differentiation
Phase 5
Phase 5 - REST Controllers & DTOs
Week 6
  • Built 11 REST controllers with 65+ endpoints covering all business features
  • Created 28 DTOs (Request + Response) to isolate entities from the presentation layer
  • Developed 9 mappers for Entity <-> DTO conversion
  • Implemented generic ApiResponse<T> wrapper and Bean Validation (@Valid)
Phase 6
Phase 6 - ML Recommendation System
Week 7
  • Built Java-side collaborative filtering (purchase-based recommendations, similar games, trending)
  • Created Python FastAPI microservice with scikit-learn KNN algorithm
  • Implemented user-item matrix with StandardScaler normalization
  • Set up inter-API communication via RestTemplate HTTP (synchronous)
Phase 7
Phase 7 - Testing & Quality
Week 8
  • Wrote 364 tests (273 unit + 91 integration) using JUnit 5, Mockito, MockMvc
  • Achieved 81% global coverage (JaCoCo) - 97% on service layer
  • Configured JaCoCo with 70% minimum threshold per package
  • Used H2 in-memory database for isolated test execution
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

The Team - Interactions

Collaboration and stakeholders

This was an individual project carried out with AI-assisted development. Jose 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 Jose's direction based on approximately 100 traced prompts across 3 documented prompt files. Jose 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

Jose DA COSTA

Jose DA COSTA - Technical direction, piloting, quality review, architecture decisions, manual testing, final document writing

Claude Code (AI)

Claude Code (AI) - Implementation of code, tests, documentation, diagrams, Docker configuration

Intern (anonymous) - Initial developer (code entirely rebuilt)

External Stakeholders

Visiplus Digital Learning - Training organization

ESIEA - Certifying institution (Level 7 - Expert in Software Engineering)

Block 4 - Advanced Software Architecture Design

Work Method

The project illustrates an "AI-augmented developer" working model: Jose 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 Jose's direction. This approach is consistent with the evolution of the developer profession in the era of generative AI.

Development Effort Distribution

Results - For Me, For the Project

Measurable outcomes and impact

For the Project
  • Complete replacement of an obsolete, bug-ridden backend with a professional solution
  • 65+ REST endpoints covering all e-commerce business features
  • Dual recommendation system: Java collaborative filtering + Python KNN microservice
  • Production-ready architecture deployable via Docker Compose with healthchecks
  • Massive seed dataset (~12,000 records across 30 categories, 100 publishers, hundreds of games)
  • 42 documentation files totaling thousands of lines + 16 Draw.io diagrams
For Me
  • Deepened expertise in Spring Boot 3 + Spring Security 6 architecture
  • First hands-on experience with ML integration (KNN) in a backend context
  • Mastered the Interface + Implementation pattern applied systematically across 11 services
  • Validated the "AI-augmented developer" workflow for complex projects (~100 prompts traced)
  • Produced a 20+ page professional case study demonstrating architecture competency
  • Strengthened understanding of SOLID principles through practical, documented application
Test Distribution
Code Coverage by Package (%)
Architecture Layers (Component Count)

The Project Aftermath

What happened after delivery

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

What Worked Well

Rigorous SOLID Architecture

Systematic application of all 5 SOLID principles (documented with concrète examples in PRINCIPES_SOLID.md) gave the project strong maintainability and extensibility. The Controller > Service (Interface) > ServiceImpl > Repository pattern was applied without exception.

High Test Coverage (81%)

With 364 tests and 81% global coverage (97% on the critical service layer), the project exceeded the 70% target. Mature test strategy: isolated unit tests with Mockito, integration tests with MockMvc, systematic AAA pattern.

Professional-Grade Security

JWT stateless with HMAC-SHA256, BCrypt with automatic salt, role-based access control (RBAC), differentiated endpoints (public, authenticated, admin-only), custom security filter, stateless sessions.

Thorough Documentation

42 Markdown files totaling thousands of lines, 8 Draw.io diagrams with PNG exports, a 20+ page case study PDF, and an 884-line critical reflection document. Every aspect of the project is documented.

What Could Be Improved

No Frontend

The project delivers only the backend API. The planned Angular frontend was not implemented, limiting the ability to demonstrate the full product.

No CI/CD Pipeline

No continuous integration setup (GitHub Actions, GitLab CI). Builds and tests are manual, which is a risk for long-term quality maintenance.

ML Model Not Trained

The FastAPI Python service works only in demo mode. The KNN algorithm is implemented but not trained due to lack of production data.

Missing Performance Optimizations

No Redis cache, no pagination on list endpoints, potential N+1 query issues with JPA relationships.

Hardcoded JWT Secret

The JWT secret is in plaintext in application.properties. In production, it should be externalized to environment variables or a secrets manager.

What I Would Do Differently
  • 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
Lasting Lessons
  • 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