Yovi en español - Equipo 1-B

Purpose/Responsibility: Proporcionar la interfaz gráfica del juego al usuario final. Gestiona el flujo completo de la partida: selección de dificultad y tamaño de tablero, renderizado del tablero triangular YEN, temporizador de turno con movimiento automático al agotarse, y visualización del historial de partidas. La Webapp es una MPA de 4 páginas independientes; Nginx sirve cada fichero HTML directamente sin fallback SPA.

Interface(s): Se comunica exclusivamente con el Users Service mediante fetch nativo (sin librerías HTTP adicionales). No accede directamente a Gamey ni a MongoDB. El JWT se envía en la cabecera Authorization: Bearer <token>.

Quality/Performance Characteristics: El temporizador de turno opera en cliente con setInterval de 1 segundo. El cambio de idioma es instantáneo (< 200ms) sin recarga de página gracias a react-i18next. El modo invitado permite jugar sin registro.

Directory/File Location: webapp/src/

Purpose/Responsibility: Gestionar la autenticación y registro de usuarios, el historial de partidas, el sistema de amigos y la tienda de XP. Actúa como API Gateway entre la webapp y el motor de juego Gamey. Al registrarse, cada usuario recibe un FriendCode único de 6 caracteres (generado con nanoid, alfabeto sin caracteres ambiguos) que permite identificarle para añadirle como amigo.

Interface(s): Expone una API REST en el puerto 3000. Se conecta a MongoDB mediante Mongoose para persistencia y a Gamey (puerto 4000) para toda la lógica de juego.

Quality/Performance Characteristics: Expone métricas en formato Prometheus mediante express-prom-bundle (latencia, método HTTP, código de estado). Soporta HTTPS condicional: si encuentra certificados en /certs/ arranca con HTTPS; si no, con HTTP (útil para CI sin certificados).

Directory/File Location: users/

Purpose/Responsibility: Ejecutar toda la lógica del Juego Y: mantener el estado de cada partida en memoria, validar movimientos, detectar la condición de victoria (conexión de los tres lados del triángulo mediante Union-Find), gestionar el estado del tablero en formato YEN y calcular las respuestas de los bots registrados en el servidor. El codigo contiene varios bots, aunque el arranque HTTP actual registra RandomBot y ProBot. Persiste el historial de partidas y estadísticas en MongoDB.

Interface(s): Expone una API REST en el puerto 4000 con HTTPS obligatorio (Rustls). Recibe y devuelve el estado del tablero en formato YEN (JSON). Incluye documentación OpenAPI generada automáticamente con utoipa, accesible en /swagger-ui.

Quality/Performance Characteristics: Implementado en Rust para máximo rendimiento en el cálculo de los bots Hard (AttackerBot y ProBot), que ejecutan BFS sobre todo el tablero en cada turno. La topología triangular pre-calcula vecinos y regiones en la construcción del tablero, garantizando acceso O(1) durante el juego.

Directory/File Location: gamey/src/

La webapp está organizada en páginas MPA, pantallas de presentación, hooks de lógica y una capa de servicios. Cada página MPA tiene su propio bundle JavaScript compilado por Vite.

El motor de juego Rust está organizado en los siguientes módulos:

Los dos bots de dificultad Hard comparten la utilidad bot_utils.rs y siguen el mismo esquema de evaluación en varias fases:

El modo multijugador actual se apoya en una estrategia separada de la partida contra bot. En la webapp, BotStrategy y MultiplayerStrategy implementan la misma abstraccion GameProvider, de forma que la pantalla de juego puede trabajar con ambos modos sin mezclar toda la logica en el componente visual.

Este diseno deja el tiempo real en users, que ya conoce la identidad del usuario, y conserva en gamey la unica responsabilidad de validar el tablero y detectar el ganador. Es una extension natural del modo contra bot, pero con estado de partida indexado por match_id en lugar de por username.

Es el servidor principal donde ocurre todo lo relativo al backend.

Explicación: En este nivel de detalle se observa que el servidor de Node.js funciona como un punto de control. Cuando el usuario solicita su historial, Node no accede a los datos de las partidas directamente; en su lugar, realiza una petición interna al servicio de Rust. Es Rust quien tiene la responsabilidad única de comunicarse con la colección partidas de MongoDB para registrar o recuperar los resultados de los juegos. Esta separación garantiza que la lógica del juego y la gestión de usuarios no interfieran entre sí.

Es el dispositivo (PC o móvil) de la persona que utiliza la aplicación.

Explicación: Al acceder a la web, el navegador descarga la aplicación de React, que se ejecuta íntegramente en el dispositivo del usuario. El sistema utiliza el Estado Local (memoria RAM) para mantener identificada la sesión. Así, cuando el jugador solicita su historial, el código rescata el nombre guardado y construye una petición dinámica hacia el backend de Node.js. Esto permite que el juego sea fluido y que el servidor reciba siempre el contexto necesario para filtrar los datos de la base de datos correctamente.

Es el lugar donde se almacena la información. De esta manera no se perderá la información al reiniciar los contenedores.

Explicación: Se utiliza el servicio gestionado MongoDB Atlas, organizando la información en dos bases de datos independientes (users_db y gamey_db) para cumplir con el patrón Database-per-Service. Al ser un servicio SaaS (Software as a Service), la persistencia, las copias de seguridad y la seguridad de los datos están delegadas al proveedor cloud, eliminando la dependencia de volúmenes locales en nuestro servidor y garantizando que los datos no se pierdan al reiniciar o eliminar los contenedores de Docker.

El proyecto adopta una metodología ágil basada en Scrum. Este enfoque iterativo e incremental permite una adaptación continua a los cambios y una entrega de valor constante. Se realizan reuniones semanales de seguimiento para revisar el progreso, ajustar la planificación y asegurar la alineación del equipo.

La planificación y el seguimiento de las tareas se centralizan en GitHub Projects. Las prioridades se revisan cada semana, quedando documentadas en actas de reunión para garantizar la transparencia y el compromiso del equipo.

La solución se ha diseñado siguiendo una arquitectura de microservicios. Este patrón estructura la aplicación como un conjunto de servicios pequeños, autónomos y débilmente acoplados.

Beneficios Clave:

Se utiliza Docker y Docker Compose para estandarizar los entornos de desarrollo, pruebas y producción. Cada microservicio (Webapp, Users, GameY) se empaqueta en su propio contenedor, asegurando que la aplicación se ejecute de manera consistente independientemente de la máquina anfitriona. Esto elimina el problema de "funciona en mi máquina" y simplifica la configuración inicial para nuevos desarrolladores.

El proyecto implementa prácticas de Integración Continua (CI) y Calidad de Código (CQ) para mantener un alto estándar de desarrollo:

La pantalla de juego no distingue los modos mediante condicionales dispersos, sino mediante estrategias. BotStrategy encapsula el flujo clasico contra IA: reset, movimiento, rendicion y temporizador. MultiplayerStrategy encapsula sockets, desafios, salas, turnos y sincronizacion del tablero. Ambas implementan GameProvider, lo que reduce el acoplamiento de GameScreen y facilita extender modos de juego nuevos.

La autenticacion combina JWT en sessionStorage y cookie token HTTP-only emitida por users. Las peticiones HTTP usan Authorization: Bearer <token> y credentials: include; los sockets se autentican con el token enviado en handshake.auth o con la cookie. Las rutas sensibles de usuarios, amigos, juego e historial usan authMiddleware; el login, registro y logout quedan como rutas publicas o de gestion de sesion.

La solución tiene tres dominios claramente distintos: la interfaz de usuario, la gestión de cuenta/relación social y el motor de juego. Cada uno evoluciona con ritmos diferentes y tiene necesidades técnicas diferentes.

Dividir el sistema en tres bloques: webapp, users y gamey.

Separar estos dominios reduce el acoplamiento y permite que cada parte se diseñe con prioridades distintas. La interfaz necesita rapidez de iteración; users necesita reglas de autenticación, perfil y social; gamey necesita rendimiento, concurrencia y estado de partida. Mezclarlos en una única base técnica habría dificultado el mantenimiento y habría hecho más difícil justificar cambios de alcance distinto.

No todas las partes del sistema tienen los mismos requisitos. La UI debe ser rápida de construir y mantener; la capa de integración debe ser flexible; el motor de juego necesita rendimiento y seguridad de memoria.

Usar React + TypeScript + Vite en la webapp, Node.js + TypeScript en users y Rust en gamey.

Esta combinación permite elegir la herramienta más adecuada para cada responsabilidad. React y TypeScript son muy cómodos para construir interfaces reutilizables y tipadas. Node.js encaja bien para exponer APIs REST y coordinar integración. Rust aporta concurrencia y rendimiento en la parte de juego, donde los ciclos de cálculo y la gestión del estado son más sensibles.

El frontend no es una experiencia continua única, sino varios flujos bien diferenciados: inicio, login, registro y juego. Cada uno tiene contexto visual y funcional propio.

Construir la webapp como aplicación multipágina con entradas separadas para index.html, login.html, register.html y game.html.

Este enfoque encaja mejor con el recorrido real del usuario y con la organización del código. Cada flujo arranca en su propia página y carga solo lo que necesita. Así se evita un árbol de navegación excesivamente centralizado y se simplifica el razonamiento sobre el estado de cada pantalla. Además, Vite soporta muy bien múltiples puntos de entrada.

El frontend no debería conocer toda la topología interna del backend. Necesita una base URL estable para autenticación, perfil, relaciones sociales y acciones auxiliares del juego.

Hacer que users actúe como capa pública de integración. La webapp se comunica principalmente con users, y este servicio reenvía a gamey aquello que pertenece al motor de juego.

Centralizar el acceso simplifica el frontend y reduce duplicación de lógica de autenticación, cabeceras y CORS. Además, el dominio de usuario ya concentra identidad, perfil, amigos y compras de XP, por lo que es natural que sea también el punto de entrada para el resto de operaciones visibles para el cliente.

Los datos de usuarios, amigos, credenciales, perfil, historial y resultados de juego tienen ciclos de vida distintos. No todos deben compartir el mismo esquema ni la misma cadencia de cambio.

Usar MongoDB con responsabilidad separada por servicio. users y gamey gestionan sus propios datos y sus propias colecciones, cada uno con su URI de conexión.

Este modelo evita el anti-patrón de base compartida, que suele introducir acoplamiento fuerte entre equipos y servicios. MongoDB, además, encaja bien con el tipo de documentos manejados en la aplicación: perfiles, amistades, partidas y estadísticas.

Las credenciales no pueden almacenarse en claro y el sistema debe autenticar peticiones sin depender de una sesión de servidor tradicional.

Hashear contraseñas con bcryptjs, emitir JWT al iniciar sesión y enviarlo en la cabecera Authorization: Bearer …​. En la webapp, el token se guarda en sessionStorage.

JWT permite una autenticación sin estado en servidor, lo que simplifica escalado y reduce dependencia de una sesión central. bcryptjs protege la contraseña en reposo y el uso de sessionStorage hace que el token desaparezca al cerrar el navegador, algo coherente con el nivel de persistencia que se quería para la sesión activa.

La parte social del proyecto no se limita a una lista de nombres. Se necesitan códigos de amigo, solicitudes pendientes, aceptación/rechazo y perfil público con relación entre usuarios.

Gestionar amigos, friend code, solicitudes y perfil público dentro de users, usando el modelo Friendship y el friendCode como mecanismo de descubrimiento.

Esta decisión mantiene el dominio social donde realmente pertenece: junto a identidad, perfil y credenciales. El friend code permite compartir identidad sin exponer directamente el username, y el flujo de solicitudes se adapta bien a una persistencia documental simple.

La partida necesita baja latencia mientras el usuario juega, pero también hace falta conservar resultados para perfil, historial y métricas.

Mantener el estado activo del juego en memoria dentro de gamey y persistir las partidas finalizadas en MongoDB.

El estado vivo debe ser inmediato para responder a cada movimiento, mientras que el histórico puede almacenarse de forma asíncrona o al cierre de la partida. Esta separación permite optimizar el bucle de juego sin renunciar al análisis posterior. En la práctica, el histórico se guarda con los datos necesarios para consultas de perfil y paginación de partidas.

Los servicios están escritos en tecnologías distintas, pero deben intercambiar datos de forma simple y legible. El frontend, además, necesita una API fácil de depurar.

Usar HTTP/JSON como protocolo principal de comunicación entre webapp, users y gamey.

HTTP/JSON encaja con el ecosistema del proyecto, es fácil de observar con herramientas de desarrollo y hace más sencilla la integración entre frontend y backend. El código de la webapp usa fetch, y los servicios internos traducen y reenvían peticiones según corresponda.

La tienda de XP necesitaba una integración de pago sin asumir la responsabilidad de tratar con tarjetas o datos bancarios.

Integrar PayPal con @paypal/react-paypal-js, usando PayPalScriptProvider, PayPalButtons, creación de orden y captura del pago.

La lógica de pago se delega a un proveedor especializado, lo que simplifica el proyecto y reduce el riesgo de seguridad. En la webapp, la tienda se presenta como modal independiente y, tras la captura de la orden, se acreditan los XP mediante el backend.

La interfaz no debe quedar ligada a un único idioma. Además, parte de la información del usuario también condiciona la experiencia lingüística.

Usar i18next y react-i18next para gestionar la interfaz multilingüe, persistiendo el idioma en las preferencias del usuario.

Centralizar las traducciones simplifica mantenimiento y reduce el coste de introducir o corregir textos. El idioma puede cambiarse dinámicamente desde la interfaz, y la preferencia se guarda tanto en perfil como en almacenamiento local para mantener coherencia entre sesiones.

La solución debe poder arrancar igual en varios entornos y reducir al mínimo el típico problema de diferencias entre máquinas.

Usar Docker y Docker Compose para levantar users, webapp, gamey y los servicios de observabilidad. La webapp se construye en multi-stage y se sirve con Nginx, mientras que los certificados locales se generan con mkcert cuando se necesita HTTPS en entorno de desarrollo.

Docker hace el despliegue reproducible y reduce la variabilidad entre entornos. Nginx es una forma simple y robusta de servir la MPA a partir de sus distintos entry points HTML; el try_files que aparece en la configuración actúa solo como respaldo genérico para rutas no resueltas como archivo estático, no como un fallback SPA. mkcert permite probar un entorno seguro sin depender de certificados públicos.

El equipo necesita conocer con claridad los contratos HTTP, tanto para integrar frontend y backend como para revisar manualmente endpoints.

Publicar documentación de APIs con OpenAPI/Swagger en los servicios que exponen endpoints HTTP.

La documentación navegable reduce ambigüedad y facilita comprobar qué parámetros espera cada ruta y qué devuelve. También ayuda a que nuevas personas entiendan el sistema sin tener que inspeccionar todo el código.

Un sistema distribuido necesita algo más que logs: conviene saber qué pasa con latencia, disponibilidad y comportamiento de los servicios.

Instrumentar observabilidad con Prometheus y Grafana, junto con métricas expuestas por users.

Las métricas permiten detectar cuellos de botella y tener una lectura más objetiva de la salud del sistema. En un proyecto con más de un servicio, esto aporta mucho valor por un coste razonable.

La solución tiene bastante lógica repartida entre frontend, backend y motor de juego. Eso hace necesario detectar regresiones de forma temprana.

Usar tests automatizados en las distintas partes del sistema y análisis de calidad con SonarCloud.

Los tests protegen las rutas críticas y la lógica de negocio, y el análisis estático ayuda a vigilar deuda técnica, cobertura y posibles vulnerabilidades. En una arquitectura distribuida, esta capa de calidad es especialmente importante.

Durante el desarrollo, frontend y backend no se sirven necesariamente desde el mismo origen.

Permitir CORS amplio en users durante desarrollo, incluyendo Authorization y los métodos necesarios para las operaciones del proyecto.

La prioridad en esta fase es integrar con rapidez y evitar bloqueos innecesarios mientras se iteran pantallas y servicios.

Se valoró la IA generativa como posible ampliación, pero no forma parte del alcance actual ni resuelve ningún requisito obligatorio del sistema.

No incorporar LLMs en esta versión.

Se evita añadir complejidad operativa, coste y dependencias externas cuando el sistema ya cubre sus objetivos funcionales con una lógica más predecible.

La documentación debe ser útil tanto para el equipo como para una evaluación externa. Para ello conviene una estructura homogénea.

Usar arc42 como estructura principal de documentación del proyecto.

arc42 facilita entender la solución de forma progresiva: contexto, alcance, decisiones, runtime, despliegue y calidad. Eso hace la documentación más mantenible y más fácil de presentar.

La webapp cuenta con 163 casos de test distribuidos en 22 archivos, cubriendo los componentes, hooks y servicios más críticos del sistema:

El setup global mockea lottie-react y fija el idioma a es para garantizar tests deterministas independientes del entorno.

El backend Node.js cuenta con 39 casos de test en 6 archivos, probando todos los endpoints REST mediante Supertest sin levantar un puerto de red real:

El motor de juego Rust cuenta con 143 tests distribuidos en 5 archivos de integración y tests unitarios inline:

Para la medición de cobertura se utiliza SonarCloud, integrado en el pipeline de CI/CD mediante GitHub Actions. La cobertura se reporta en formato lcov (webapp) y se sube automáticamente en cada push a la rama development.

El Quality Gate exige:

El escenario simula el flujo completo de un usuario jugando una partida:

Los thresholds de aceptación definidos son:

El sistema YoVi supera en ambos escenarios los thresholds de calidad definidos. Con 25 usuarios concurrentes ejecutando flujos completos de partida, el p95 de latencia es de 109ms, muy por debajo del límite de 500ms. Destacablemente, el sistema escala bien bajo pico de carga: el p95 mejora de 116ms a 109ms al pasar de 10 a 25 usuarios, y el throughput aumenta de 8.21 a 11 req/s. El error rate se mantiene en 0% en ambos escenarios.

Esto valida el escenario de calidad SC-09 (acceso concurrente de múltiples usuarios) definido en la sección 10, donde se exigía un error rate < 1% y latencia media < 500ms.

Muestra la tasa de peticiones por segundo (req/s) de cada método HTTP junto con su código de respuesta a lo largo del tiempo. Esto permite identificar de un vistazo qué tipo de operaciones generan más tráfico y detectar anomalías en el comportamiento del servicio mediante un gráfico de áreas apiladas (Stacked Area).

En la muestra obtenida vemos una clara preponderancia de métodos POST-201 (creación de recursos) y OPTIONS-204 (negociación de CORS), lo cual es el comportamiento esperado en una arquitectura donde el frontend React se comunica con APIs protegidas por protocolos de seguridad.

Este panel utiliza una visualización de tipo Bar Gauge para desglosar el volumen de tráfico por cada ruta específica del sistema. Permite validar qué funcionalidades son las más demandadas por los usuarios reales.

Se observa que el endpoint /move es el más visitado, confirmando que la lógica de juego gestionada por el microservicio en Rust es el núcleo de actividad. También se monitorizan correctamente rutas como /login, /history o /friends, permitiendo una trazabilidad completa de la carga entre ambos servicios.

Este panel muestra el número de errores de servidor (códigos HTTP 5xx). Su objetivo es detectar fallos críticos o pánicos en el sistema de forma inmediata.

El panel muestra un 0 constante, indicando que los servidores han sido capaces de manejar la carga sin problemas. Está configurado con umbrales visuales para alertar visualmente si se detectase cualquier excepción no controlada en Node o Rust.

El percentil 95 de latencia nos indica el tiempo de respuesta máximo por debajo del cual se encuentran el 95% de las peticiones. Es la métrica más fiel para medir la fluidez de la experiencia del usuario.

El valor registrado durante las pruebas es de 0.00475 ms. Este resultado es excepcionalmente bajo y demuestra la eficiencia técnica de haber implementado el motor de juego en Rust (Axum), permitiendo procesar movimientos de juego de forma casi instantánea.

Este panel de líneas permite comparar en tiempo real el tráfico que recibe el gamey-service frente al users-service.

Sirve para verificar que la arquitectura de microservicios está equilibrada y que ambos contenedores están reportando métricas correctamente bajo el entorno seguro HTTPS configurado.