Contact
Vamos trabalhar juntos
GamesUP - Plataforma E-Commerce de Jogos de Tabuleiro com Recomendacoes ML

GamesUP - Plataforma E-Commerce de Jogos de Tabuleiro com Recomendacoes ML

API backend completa para uma plataforma e-commerce de jogos de tabuleiro com motor de recomendacao KNN, seguranca JWT e 81% de cobertura de testes - construida com Spring Boot 3, Python FastAPI e Docker.

Setembro 2024 - Janeiro 2025
~8 semanas de desenvolvimento ativo
Lead Tecnico & Desenvolvedor Solo (Assistido por IA)
Java 17Spring Boot 3.3.4Spring Security 6JWT (HMAC-SHA256)JPA / HibernateMySQL 8.0Python 3.11FastAPIscikit-learn (KNN)Docker ComposeJUnit 5MockitoJaCoCoMavenLombok

Linhas de codigo

32,600

Java + Python

Testes automatizados

364

273 unitarios + 91 integracao

Cobertura de codigo

81%

JaCoCo (97% nos servicos)

Endpoints API

65+

Endpoints REST em 11 controllers

Apresentacao

Definicao e escopo do projeto

GamesUP e uma API backend para uma plataforma e-commerce de jogos de tabuleiro que integra um sistema de recomendacao por aprendizado de maquina baseado no algoritmo K-Nearest Neighbors (KNN). O projeto foi realizado como estudo de caso profissional para uma certificacao de nivel 7 (Expert em Engenharia de Software) concedida pela ESIEA atraves da Visiplus Digital Learning.

A plataforma cobre o ciclo completo de e-commerce: gestao de catalogo de produtos, pedidos multi-linhas com gestao de estoque, autenticacao JWT com controle de acesso baseado em papeis, recomendacoes personalizadas, avaliacoes e classificacoes, e listas de desejos.

Um codigo pre-existente deixado por um estagiario foi avaliado e considerado abaixo dos padroes profissionais. A decisao foi reconstruir todo o backend do zero, aplicando rigorosamente os principios SOLID, arquitetura em camadas e testes abrangentes.

Dominio

E-commerce especializado em jogos de tabuleiro - gestao de catalogo, pedidos, recomendacoes, avaliacoes de usuarios

Usuarios alvo

Compradores de jogos de tabuleiro (B2C) e administradores da plataforma. Frontend (Angular) planejado mas nao incluido nesta fase (entrega somente backend).

Escopo funcional
Catalogo de produtos (CRUD)
Pedidos multi-linhas & estoque
Autenticacao JWT & RBAC
Recomendacoes ML (KNN)
Avaliacoes & classificacoes
Gestao de wishlists
Busca multi-criterios
Orquestracao Docker
System Architecture
3-layer architecture: Presentation (planned), Application (Java + Python), Data (MySQL)
Project Metrics

Objetivos, Contexto, Desafios & Riscos

Visao estrategica e restricoes

Objetivos
  • Reconstruir a API Spring Boot com arquitetura em camadas e principios SOLID
  • Implementar Spring Security 6 com autenticacao JWT e gestao de papeis (ADMIN, CLIENT)
  • Desenvolver um sistema de recomendacao KNN via microsservico Python FastAPI
  • Atingir minimo 70% de cobertura de testes com JaCoCo, JUnit 5 e Mockito
  • Produzir documentacao UML completa (diagramas de classes, componentes, sequencia, arquitetura)
Contexto

O projeto nasceu de uma exigencia de certificacao profissional (ESIEA Nivel 7, Bloco 4 - Concepcao avancada de arquitetura de software). O backend existente gerava bugs recorrentes que impactavam a receita e a experiencia do usuario. Um estagiario havia sido encarregado de criar uma nova API Spring Boot, mas o codigo nao atendia aos padroes de qualidade.

Jose DA COSTA assumiu o projeto com a missao de reconstruir completamente o backend em uma solucao profissional, funcional e escalavel. O projeto foi realizado individualmente ao longo de aproximadamente 8 semanas, com desenvolvimento assistido por IA (Claude Code) para implementacao sob a direcao tecnica e decisoes de arquitetura de Jose.

Desafios

Qualidade arquitetural

Demonstrar dominio de concepcao avancada de software (SOLID, design patterns, arquitetura em camadas) atraves de uma aplicacao concreta

Inovacao tecnica

Integrar um sistema de recomendacao ML (KNN) em uma arquitetura e-commerce classica via comunicacao inter-API

Certificacao profissional

Validar 4 competencias do Bloco 4 do titulo RNCP Expert em Engenharia de Software (C.14, C.16, C.17, C.18)

Riscos identificados

Codigo do estagiario inutilizavel

O codigo existente nao atendia aos padroes de qualidade, exigindo uma reconstrucao completa.

Modelo ML nao treinavel

Dados de producao insuficientes para treinamento KNN. Mitigacao: modo demo funcional com arquitetura pronta para treinamento futuro.

Falhas de seguranca JWT

Uma implementacao JWT incorreta poderia expor a aplicacao. Mitigacao: implementacao rigorosa de Spring Security 6 + HMAC-SHA256.

Cobertura de testes < 70%

Estrategia de teste sistematica necessaria para superar o limite JaCoCo de 70% por pacote.

Complexidade inter-API

A comunicacao Java-Python via RestTemplate exigiu healthchecks e orquestracao Docker Compose.

Matriz de avaliacao de riscos

As etapas - O que eu fiz

Fases cronologicas e contribuicoes pessoais

Progresso do desenvolvimento em 8 semanas
Phase 1
Fase 1 - Arquitetura & UML
Semanas 1-2
  • Analise de requisitos e identificacao de todas as funcionalidades
  • Concepcao da arquitetura 3 camadas (Apresentacao, Aplicacao, Dados)
  • Criacao de 4 diagramas UML em Draw.io (arquitetura, classes, componentes, sequencia)
  • Selecao da stack tecnica: Spring Boot 3.3.4 + Java 17, MySQL 8.0, Python 3.11 + FastAPI
Phase 2
Fase 2 - Fundamentos JPA
Semanas 2-3
  • Criacao de 10 entidades JPA com anotacoes completas e relacoes bidirecionais
  • Definicao de enumeracoes (Role: CLIENT/ADMIN, PurchaseStatus: 5 estados)
  • Uso de Lombok (@Data, @Builder) para reduzir codigo boilerplate
  • Configuracao do Hibernate com geracao automatica de schema (ddl-auto=update)
Phase 3
Fase 3 - Camada Service com SOLID
Semanas 4-5
  • Implementacao de 11 interfaces de servicos + 11 implementacoes seguindo os 5 principios SOLID
  • Aplicacao de injecao de dependencias por construtor, gestao @Transactional
  • Criacao de excecoes personalizadas (ResourceNotFound, DuplicateResource, InsufficientStock)
  • Documentacao de cada principio SOLID com exemplos concretos do codigo
Phase 4
Fase 4 - Seguranca & JWT
Semanas 5-6
  • Configuracao de Spring Security 6 com filtro JWT personalizado (JwtAuthenticationFilter)
  • Implementacao de geracao/validacao de tokens HMAC-SHA256 via JwtUtil
  • Hashing BCrypt de senhas, @PreAuthorize baseado em papeis
  • Gestao de sessoes stateless com diferenciacao de endpoints publicos/autenticados/admin
Phase 5
Fase 5 - Controllers REST & DTOs
Semana 6
  • Construcao de 11 controllers REST com 65+ endpoints cobrindo todas as funcionalidades de negocio
  • Criacao de 28 DTOs (Request + Response) para isolar entidades da camada de apresentacao
  • Desenvolvimento de 9 mappers para conversao Entity <-> DTO
  • Implementacao do wrapper generico ApiResponse<T> e Bean Validation (@Valid)
Phase 6
Fase 6 - Sistema de recomendacao ML
Semana 7
  • Construcao de filtragem colaborativa lado Java (recomendacoes por compras, jogos similares, tendencias)
  • Criacao do microsservico Python FastAPI com algoritmo KNN do scikit-learn
  • Implementacao da matriz usuario-item com normalizacao StandardScaler
  • Configuracao da comunicacao inter-API via RestTemplate HTTP (sincrono)
Phase 7
Fase 7 - Testes & Qualidade
Semana 8
  • Escrita de 364 testes (273 unitarios + 91 integracao) com JUnit 5, Mockito, MockMvc
  • Atingimento de 81% de cobertura global (JaCoCo) - 97% na camada de servicos
  • Configuracao do JaCoCo com limite minimo de 70% por pacote
  • Uso de banco H2 em memoria para execucao isolada de testes
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

Os atores - As interacoes

Colaboracao e partes interessadas

Este foi um projeto individual realizado com desenvolvimento assistido por IA. Jose DA COSTA atuou como Lead Tecnico e Diretor de Projeto, responsavel por todas as decisoes de arquitetura, revisoes de qualidade, analise de requisitos e validacao do entregavel final.

Claude Code (IA) serviu como parceiro de implementacao, executando codigo sob a direcao de Jose com base em aproximadamente 100 prompts rastreados em 3 arquivos documentados. Jose identificou problemas (problemas de codificacao no PHPMyAdmin, inconsistencias na documentacao), tomou decisoes organizacionais (renomeacao de pastas, convencoes de estrutura de arquivos) e produziu o documento Word final para submissao a certificacao.

O codigo original do estagiario foi avaliado e inteiramente substituido - nenhum elemento do entregavel final contem codigo da tentativa inicial. A contribuicao do estagiario limita-se ao cenario pedagogico que justifica a reconstrucao.

Composicao da equipe

Jose DA COSTA

Jose DA COSTA - Direcao tecnica, pilotagem, revisao de qualidade, decisoes de arquitetura, testes manuais, redacao do documento final

Claude Code (AI)

Claude Code (IA) - Implementacao do codigo, testes, documentacao, diagramas, configuracao Docker

Estagiario (anonimo) - Desenvolvedor inicial (codigo inteiramente reconstruido)

Partes interessadas externas

Visiplus Digital Learning - Organizacao de formacao

ESIEA - Instituicao certificadora (Nivel 7 - Expert em Engenharia de Software)

Bloco 4 - Concepcao avancada de arquitetura de software

Metodo de trabalho

O projeto ilustra um modo de trabalho "desenvolvedor aumentado por IA": Jose desempenhou o papel de CTO/diretor de projeto definindo objetivos, tomando decisoes de arquitetura, identificando problemas e validando entregaveis. Claude Code desempenhou o papel de desenvolvedor executor, realizando toda a implementacao tecnica sob a direcao de Jose. Esta abordagem e coerente com a evolucao da profissao de desenvolvedor na era da IA generativa.

Distribuicao do esforco de desenvolvimento

Os resultados - Para mim, para o projeto

Resultados mensuraveis e impacto

Para o projeto
  • Substituicao completa de um backend obsoleto e com bugs por uma solucao profissional
  • 65+ endpoints REST cobrindo todas as funcionalidades de negocio e-commerce
  • Sistema duplo de recomendacao: filtragem colaborativa Java + microsservico KNN Python
  • Arquitetura pronta para producao, implantavel via Docker Compose com healthchecks
  • Conjunto de dados massivo (~12.000 registros: 30 categorias, 100 editoras, centenas de jogos)
  • 42 arquivos de documentacao totalizando milhares de linhas + 16 diagramas Draw.io
Para mim
  • Aprofundamento da expertise em arquitetura Spring Boot 3 + Spring Security 6
  • Primeira experiencia pratica de integracao ML (KNN) em contexto backend
  • Dominio do padrao Interface + Implementation aplicado sistematicamente em 11 servicos
  • Validacao do workflow "desenvolvedor aumentado por IA" para projetos complexos (~100 prompts rastreados)
  • Producao de um estudo de caso profissional de 20+ paginas demonstrando competencia arquitetural
  • Fortalecimento da compreensao dos principios SOLID pela aplicacao pratica documentada
Distribuicao dos testes
Cobertura de codigo por pacote (%)
Camadas de arquitetura (quantidade de componentes)

Os desdobramentos do projeto

O que aconteceu apos a entrega

Entrega imediata: O projeto foi submetido como estudo de caso profissional completo (PDF, 20+ paginas) para a certificacao ESIEA Nivel 7, Bloco 4 - Concepcao avancada de arquitetura de software. O entregavel incluiu o codigo-fonte completo, configuracao Docker, diagramas UML, relatorios de cobertura de testes e um documento de reflexao critica.

Estado atual: O backend e funcional e implantavel via Docker Compose. O modelo ML opera em modo demo (algoritmo KNN implementado mas nao treinado com dados de producao). O frontend Angular mencionado na arquitetura permanece nao construido, limitando a demonstrabilidade do produto final a testes no nivel da API.

Perspectiva a longo prazo: As decisoes de arquitetura (SOLID, design em camadas, servicos baseados em interfaces) provaram seu valor em termos de testabilidade (81% de cobertura) e extensibilidade. O sistema de recomendacao foi projetado com um caminho de evolucao progressiva: V1 (filtragem colaborativa Java) -> V2 (KNN Python, pronto mas nao treinado) -> V3 (Deep Learning, futuro). A interface RecommendationService permite trocar implementacoes sem modificar o restante do codigo.

Repositorio: O codigo-fonte e mantido em um repositorio GitHub privado com um mirror publico no GitFront para avaliacao.

Meu olhar critico

Analise retrospectiva honesta

O que funcionou bem

Arquitetura SOLID rigorosa

Aplicacao sistematica dos 5 principios SOLID (documentada com exemplos concretos em PRINCIPES_SOLID.md) conferindo ao projeto forte manutenibilidade e extensibilidade. O padrao Controller > Service (Interface) > ServiceImpl > Repository e aplicado sem excecao.

Alta cobertura de testes (81%)

Com 364 testes e 81% de cobertura global (97% na camada de servicos critica), o projeto supera amplamente o objetivo de 70%. Estrategia de teste madura: testes unitarios isolados com Mockito, testes de integracao com MockMvc, padrao AAA sistematico.

Seguranca de nivel profissional

JWT stateless com HMAC-SHA256, BCrypt com salt automatico, controle de acesso baseado em papeis (RBAC), endpoints diferenciados (publicos, autenticados, somente admin), filtro de seguranca personalizado, sessoes stateless.

Documentacao exaustiva

42 arquivos Markdown totalizando milhares de linhas, 8 diagramas Draw.io com exportacoes PNG, um estudo de caso PDF completo de 20+ paginas e um documento de reflexao critica de 884 linhas. Cada aspecto do projeto e documentado.

O que poderia ser melhorado

Sem frontend

O projeto entrega apenas a API backend. O frontend Angular planejado nao foi implementado, limitando a capacidade de demonstrar o produto completo.

Sem pipeline CI/CD

Sem integracao continua configurada (GitHub Actions, GitLab CI). Builds e testes sao manuais, o que e um risco para a manutencao da qualidade a longo prazo.

Modelo ML nao treinado

O servico Python FastAPI funciona apenas em modo demo. O algoritmo KNN e implementado mas nao treinado por falta de dados de producao.

Otimizacoes de performance ausentes

Sem cache Redis, sem paginacao nos endpoints de lista, problemas potenciais de consultas N+1 com relacoes JPA.

Segredo JWT fixo no codigo

O segredo JWT esta em texto plano no application.properties. Em producao, deveria ser externalizado para variaveis de ambiente ou um gerenciador de segredos.

O que eu faria diferente
  • Adotar TDD (Test-Driven Development) - os testes foram escritos apos o codigo na Fase 8, perdendo feedback de design precoce
  • Integrar seguranca desde a Fase 2 em vez da Fase 5, evitando problemas de configuracao de testes com Spring Security
  • Escrever user stories formais com criterios de aceitacao antes da implementacao
  • Usar MapStruct em vez de mappers manuais para reduzir boilerplate
  • Adicionar documentacao Swagger/OpenAPI para exploracao interativa da API
Licoes duradouras
  • Os principios SOLID nao sao teoricos - sua aplicacao concreta melhora consideravelmente a qualidade, testabilidade e extensibilidade do codigo
  • Documentacao continua e mais eficaz que documentacao no final do projeto - escrever ao longo do caminho produz melhor qualidade
  • Testes permitem evolucao segura - com 81% de cobertura, refatoracao se torna mais segura
  • Seguranca deve ser projetada desde o inicio - adiciona-la depois cria problemas de integracao (ilustrado pelas falhas nos testes de controllers)
  • Um sistema de recomendacao ML pode ser integrado progressivamente - o padrao interface permite comecar simples e evoluir sem refatoracao major