yovi_es3a

About arc42

arc42, the template for documentation of software and system architecture.

Template Version 8.2 EN. (based upon AsciiDoc version), January 2023

Created, maintained and © by Dr. Peter Hruschka, Dr. Gernot Starke and contributors. See https://arc42.org.

Note	This version of the template contains some help and explanations. It is used for familiarization with arc42 and the understanding of the concepts. For documentation of your own system you use better the plain version.

1. Introducción

Describes the relevant requirements and the driving forces that software architects and development team must consider. These include

underlying business goals,
essential features,
essential functional requirements,
quality goals for the architecture and
relevant stakeholders and their expectations

Este documento describe la aplicación web YOVI, encargada por la empresa desarrolladora de juegos Micrati. La aplicación permite a sus usuarios jugar a variantes del juego de conexión Y, con la opción de jugar contra bots o contra otros jugadores.

Además, dispone de una API abierta que permite acceder al historial de partida y a las estadísticas de jugador, a través de la misma aplicación web o mediante llamadas a la API.

La aplicación está basada en un sistema de prueba desarrollada por la misma empresa, sobre la que implementamos las funcionalidades necesarias para llevar la aplicación al mercado.

1.1. Resumen de Requisitos

Contents

Short description of the functional requirements, driving forces, extract (or abstract) of requirements. Link to (hopefully existing) requirements documents (with version number and information where to find it).

Motivation

From the point of view of the end users a system is created or modified to improve support of a business activity and/or improve the quality.

Form

Short textual description, probably in tabular use-case format. If requirements documents exist this overview should refer to these documents.

Keep these excerpts as short as possible. Balance readability of this document with potential redundancy w.r.t to requirements documents.

Further Information

See Introduction and Goals in the arc42 documentation.

Los requisitos de alto nivel para la aplicación YOVI son:

Prioridad	Requisito
1	Debe soportar el modo de juego clásico que enfrenta a un jugador con la máquina.
2	Debe estar desplegada en la nube y ser públicamente accesible a través de la web.
3	Debe contar con una interfaz web que permita a los usuarios jugar al juego Y.
4	Debe ofrecer varias estrategias de juego que los usuarios puedan seleccionar junto a un nivel de dificultad para la máquina.
5	Debe proporcionar un sistema de registro y autenticación, que permita a los usuarios consultar sus estadísticas e histórico de participación en el sistema.
6	Debe exponer una API que permita el acceso y la gestión de la información de los usuarios.
7	Debe posibilitar que se juege a través de la API, ya sea para implementaciones públicas o a través de bots.

1.2. Objetivos de Calidad

Contents

The top three (max five) quality goals for the architecture whose fulfillment is of highest importance to the major stakeholders. We really mean quality goals for the architecture. Don’t confuse them with project goals. They are not necessarily identical.

Consider this overview of potential topics (based upon the ISO 25010 standard):

Motivation

You should know the quality goals of your most important stakeholders, since they will influence fundamental architectural decisions. Make sure to be very concrete about these qualities, avoid buzzwords. If you as an architect do not know how the quality of your work will be judged…

Form

A table with quality goals and concrete scenarios, ordered by priorities

Los objetivos de calidad principales para la aplicación YOVI son:

Prioridad	Objetivo	Descripción
Alta	Interoperabilidad	La aplicación web y el módulo Rust deben comunicarse de forma fiable mediante los estados de juego YEN en mensajes JSON.
Alta	Mantenibilidad	La arquitectura debe permitir añadir nuevas estrategias y variantes de juego, además de mejoras en la API sin afectar al núcleo del sistema.
Alta	Fiabilidad	La lógica de juego del módulo Rust debe ofrecer respuestas correctas y consistentes para la evaluación de partidas.
Media	Escalabilidad	El sistema debe soportar múltiples usuarios y bots interactuando con la aplicación de forma simultánea.
Media	Usabilidad	La aplicación debe presentar una interfaz web clara, accesible y fácil de usar.

Prioridad

Objetivo

Descripción

Alta

Interoperabilidad

La aplicación web y el módulo Rust deben comunicarse de forma fiable mediante los estados de juego YEN en mensajes JSON.

Alta

Mantenibilidad

La arquitectura debe permitir añadir nuevas estrategias y variantes de juego, además de mejoras en la API sin afectar al núcleo del sistema.

Alta

Fiabilidad

La lógica de juego del módulo Rust debe ofrecer respuestas correctas y consistentes para la evaluación de partidas.

Media

Escalabilidad

El sistema debe soportar múltiples usuarios y bots interactuando con la aplicación de forma simultánea.

Media

Usabilidad

La aplicación debe presentar una interfaz web clara, accesible y fácil de usar.

1.3. Grupos de Interés

Contents

Explicit overview of stakeholders of the system, i.e. all person, roles or organizations that

should know the architecture
have to be convinced of the architecture
have to work with the architecture or with code
need the documentation of the architecture for their work
have to come up with decisions about the system or its development

Motivation

You should know all parties involved in development of the system or affected by the system. Otherwise, you may get nasty surprises later in the development process. These stakeholders determine the extent and the level of detail of your work and its results.

Form

Table with role names, person names, and their expectations with respect to the architecture and its documentation.

Los grupos de interés en el desarrollo de la aplicación YOVI son:

Grupo	Interés
Usuarios finales	Poder accedar al juego Y con una experiencia atractiva y fluida.
Bots externos	Interactuar con el sistema mediant un API estable y documentado correctamente.
Equipo de desarrollo	Trabajar con una arquitectura clara, modular y mantenible.
Profesores	Verificar la calidad arquitectónica, la documentación y la implementación del sistema.
Micrati	Disponer de un producto que cumpla con los requisitos deseados.

Grupo

Interés

Usuarios finales

Poder accedar al juego Y con una experiencia atractiva y fluida.

Bots externos

Interactuar con el sistema mediant un API estable y documentado correctamente.

Equipo de desarrollo

Trabajar con una arquitectura clara, modular y mantenible.

Profesores

Verificar la calidad arquitectónica, la documentación y la implementación del sistema.

Micrati

Disponer de un producto que cumpla con los requisitos deseados.

2. Restricciones de la Arquitectura

Contents

Any requirement that constraints software architects in their freedom of design and implementation decisions or decision about the development process. These constraints sometimes go beyond individual systems and are valid for whole organizations and companies.

Motivation

Architects should know exactly where they are free in their design decisions and where they must adhere to constraints. Constraints must always be dealt with; they may be negotiable, though.

Form

Simple tables of constraints with explanations. If needed you can subdivide them into technical constraints, organizational and political constraints and conventions (e.g. programming or versioning guidelines, documentation or naming conventions)

Further Information

See Architecture Constraints in the arc42 documentation.

La aplicación YOVI debe cumplir con los estándares siguientes:

La aplicación web y la API deben desarrollarse en TypeScript, mientras que la lógica de juego debe desarrollarse en Rust.
El módulo de lógica de juego debe ofrecer un servicio web básico accesible desde la aplicación web.
Los módulos de aplicación y lógica de juego deben comunicarse a través de mensajes JSON, representando el estado de juego en notación YEN.
La aplicación web debe estar desplegada públicamente y la API documentada, permitiendo la interacción con bots.
La base de código debe mantenerse en un repositorio bien gestionado y se debe cumplir con los plazos de entrega propuestos.

3. Contexto y Alcance

El sistema propuesto forma parte del ecosistema de juegos de la empresa Micrati. Por tanto, deberá poder coexistir e interoperar con otros juegos de navegador dentro del mismo ecosistema. En este caso se provee un servicio de gestión de usuarios (users) que se asume ya existe y es accedido por los demás juegos, pero se proporciona por defecto.

3.1. Contexto de negocio

Actores y sistemas externos principales:

Jugador (usuario principal): interactúa a través del navegador con el módulo webapp para registrarse, autenticarse y jugar.
Administrador (usuario moderador): interactúa con el navegador para gestionar configuración del sistema y moderación de usuarios.
Navegador / Cliente Web: transporte HTTP(S) entre usuario y webapp.
Registro de contenedores: almacena y despliega imágenes Docker del ecosistema.
Persistencia: servicio de base de datos que almacena información de usuarios y registros de partidas (datos de juego, puntuaciones e historial).

3.2. Contexto técnico

Este apartado describe los canales técnicos, protocolos y medios de transmisión utilizados para la interacción entre el sistema y su entorno.

Canales y protocolos previstos:

HTTP/HTTPS (REST + JSON): canal primario entre webapp, users y gamey.
Docker / Docker Compose: empaquetado y orquestación local para desarrollo y pruebas.

Además, también se cuenta con herramientas previstas para métricas, alertas y paneles:

Prometheus (scrape/HTTP): recolecta métricas expuestas por los servicios.
Grafana: visualización y dashboards basados en datos de Prometheus y otras fuentes.

4. Estrategia de la Solución

La solución propuesta se compone de tres subsistemas principales, cada uno con responsabilidades claras, siguiendo un patrón basado en microservicios:

gamey: Backend del juego, implementado en Rust. Responsable del motor de partidas y reglas del juego, con endpoints para manejar partidas.
users: Servicio de gestión de usuarios, implementado en Node.js. Encargado del manejo de usuarios y autenticación.
webapp: Frontend, implementado en React. Implementación de interfaces gráficas de usuario que permiten la comunicación del usuario con el resto de la aplicación.

El sistema está destinado a ser desplegado en un servidor remoto y ser accedido por una dirección IP pública para ser ejecutado desde un navegador, aunque también peuede puede ser desplegado en local empleando Docker con el correspondiente fichero docker-compose.yml.

Se provee de integración con Prometheus y Grafana que provee acceso a logs y métricas sobre el sistema, accesibles desde el módulo users.

5. Building Block View

La vista de bloques muestra la descomposición estática del sistema y sus dependencias principales.

5.1. Whitebox Overall System

Overview Diagram

Motivation

El sistema se descompone en cuatro bloques principales siguiendo una arquitectura de microservicios desacoplados:

webapp: interfaz de usuario
users: microservicio REST
gamey: motor de juego en Rust
Stack de monitorización

Esta separación permite bajo acoplamiento, escalabilidad independiente y separación clara entre lógica de dominio y presentación.

Contained Building Blocks

Name	Responsibility
webapp	Interfaz de usuario desarrollada en React con TypeScript.
users	Microservicio Node.js/Express para gestión de usuarios.
gamey	Motor de juego que implementa la lógica del dominio.
Monitoring Stack	Monitorización con Prometheus y Grafana.

Name

Responsibility

webapp

Interfaz de usuario desarrollada en React con TypeScript.

users

Microservicio Node.js/Express para gestión de usuarios.

gamey

Motor de juego que implementa la lógica del dominio.

Monitoring Stack

Monitorización con Prometheus y Grafana.

Important Interfaces

HTTP REST entre webapp y users (puertos 3000)
WebSocket entre webapp y gamey (puerto 4000)
Endpoint /metrics para Prometheus
Comunicación interna mediante red Docker monitor-net

5.1.1. webapp

Purpose/Responsibility

Gestiona la interacción con el usuario, autenticación (login/registro) y realiza llamadas HTTP al backend y WebSocket al motor de juego.

Interface(s)

POST /createuser - Crear nuevo usuario (a users)
POST /login - Autenticar usuario (a users)
WebSocket /ws (a gamey, puerto 4000)

Directory/File Location

webapp/

5.1.2. users

Purpose/Responsibility

Servicio REST que gestiona el registro, autenticación y almacenamiento de usuarios. Expone métricas del sistema mediante Prometheus.

Interface(s)

POST /createuser - Crear usuario
POST /login - Autenticar usuario
GET / - Listar usuarios
GET /username/:username - Obtener usuario por nombre
GET /:id - Obtener usuario por ID
DELETE /:id - Eliminar usuario
GET /metrics - Métricas de Prometheus

Directory/File Location

users/

5.1.3. gamey

Purpose/Responsibility

Implementa la lógica del juego de Y, incluyendo algoritmos de inteligencia artificial para oponentes computacionales. Funciona como servidor HTTP con soporte WebSocket.

Interface(s)

WebSocket /ws - Comunicación bidireccional de juego (puerto 4000)
GET /status - Health check
GET /bots - Listar bots disponibles
GET /metrics - Métricas de Prometheus
CLI - Línea de comandos para juego local
Biblioteca Rust - API interna reutilizable

Directory/File Location

gamey/

5.1.4. Monitoring Stack

Purpose/Responsibility

Recolecta y visualiza métricas del sistema mediante Prometheus y Grafana.

Interface(s)

Scraping de /metrics desde users y gamey
Dashboards en Grafana (puerto 9091)

Location

docker-compose.yml

5.2. Level 2

5.2.1. White Box webapp

Motivation: Se detalla la estructura interna por ser el punto de entrada del sistema y responsable de la autenticación de usuarios, gestión de sesión y visualización del tablero de juego.

Name	Responsibility
main.tsx	Punto de entrada de la aplicación React.
App.tsx	Componente raíz que gestiona el estado de autenticación.
RegisterForm.tsx	Componente de registro de nuevos usuarios con validación.
LoginForm.tsx	Componente de login de usuarios existentes.
GameBoard.tsx	Componente principal para visualizar y jugar al tablero de juego.
UserStats.tsx	Componente para mostrar estadísticas del usuario.

Name

Responsibility

main.tsx

Punto de entrada de la aplicación React.

App.tsx

Componente raíz que gestiona el estado de autenticación.

RegisterForm.tsx

Componente de registro de nuevos usuarios con validación.

LoginForm.tsx

Componente de login de usuarios existentes.

GameBoard.tsx

Componente principal para visualizar y jugar al tablero de juego.

UserStats.tsx

Componente para mostrar estadísticas del usuario.

5.2.2. White Box users

Motivation: El servicio users es un microservicio REST independiente que gestiona toda la lógica de autenticación y persistencia de usuarios. Su separación permite escalabilidad independiente y reutilización por otros servicios.

Name Responsibility

Name	Responsibility
users-service.js	Punto de entrada. Configura Express, CORS, middleware de métricas y rutas.
user-routes.js	Definición de rutas REST (`/`, `/login`, `/auth`, etc.).
user-controller.js	Controladores que procesan las peticiones HTTP.
user-service.js	Lógica de negocio (validación, autenticación, CRUD).
user-model.js	Esquema Mongoose para la base de datos.
userDB.js	Conexión y operaciones de base de datos.
gestorDBUSER.js	Gestor alternativo para operaciones en base de datos.

users-service.js

Punto de entrada. Configura Express, CORS, middleware de métricas y rutas.

user-routes.js

Definición de rutas REST (/, /login, /auth, etc.).

user-controller.js

Controladores que procesan las peticiones HTTP.

user-service.js

Lógica de negocio (validación, autenticación, CRUD).

user-model.js

Esquema Mongoose para la base de datos.

userDB.js

Conexión y operaciones de base de datos.

gestorDBUSER.js

Gestor alternativo para operaciones en base de datos.

5.2.3. White Box gamey

Motivation: Contiene la lógica más compleja del sistema, implementada en Rust para máximo rendimiento. Está estructurada en módulos claramente separados: lógica de juego (core), estrategias de IA (bot), servidor HTTP (bot_server), interfaz de usuario (cli) y serialización (notation).

Name Responsibility

Name	Responsibility
main.rs	Selección de modo de ejecución (CLI, servidor HTTP en puerto 4000, o humano vs IA).
lib.rs	Organización modular y re-exportación de tipos públicos.
core/	Tipos fundamentales del juego: lógica, coordenadas, movimientos, jugadores.
bot/	Estrategias de inteligencia artificial y decisión de movimientos.
bot_server/	Servidor Axum con WebSocket en `/ws` para comunicación real-time.
cli/	Interfaz de línea de comandos para juego interactivo.
notation/	Formato YEN para serialización de estado de juego.

main.rs

Selección de modo de ejecución (CLI, servidor HTTP en puerto 4000, o humano vs IA).

lib.rs

Organización modular y re-exportación de tipos públicos.

core/

Tipos fundamentales del juego: lógica, coordenadas, movimientos, jugadores.

bot/

Estrategias de inteligencia artificial y decisión de movimientos.

bot_server/

Servidor Axum con WebSocket en /ws para comunicación real-time.

cli/

Interfaz de línea de comandos para juego interactivo.

notation/

Formato YEN para serialización de estado de juego.

5.3. Level 3

5.3.1. White Box core (Núcleo del Juego)

Motivation: El módulo core encapsula toda la lógica fundamental del juego de Y, incluyendo representación del tablero, gestión de estados y detección de victoria.

Name Responsibility

Name	Responsibility
game.rs	Estructura principal `GameY` con estado del juego, validación de movimientos y máquina de estados.
coord.rs	Sistema de coordenadas baricéntricas (x, y, z) para tablero triangular.
movement.rs	Tipos `Movement` (colocación de pieza) y `GameAction` (swap, resign).
player.rs	Tipos `PlayerId` y `Player` para representación de jugadores.
action.rs	Definición de acciones especiales (`Swap`, `Resign`).
player_set.rs	Estructura Union-Find privada para detección eficiente de conectividad.
render_options.rs	Opciones para visualización del tablero.

game.rs

Estructura principal GameY con estado del juego, validación de movimientos y máquina de estados.

coord.rs

Sistema de coordenadas baricéntricas (x, y, z) para tablero triangular.

movement.rs

Tipos Movement (colocación de pieza) y GameAction (swap, resign).

player.rs

Tipos PlayerId y Player para representación de jugadores.

action.rs

Definición de acciones especiales (Swap, Resign).

player_set.rs

Estructura Union-Find privada para detección eficiente de conectividad.

render_options.rs

Opciones para visualización del tablero.

5.3.2. White Box game.rs (Lógica Central)

Motivation: Contiene el núcleo algorítmico del sistema, implementando toda la lógica del juego de Y: validación de movimientos, gestión de estado y detección de victorias mediante Union-Find.

Name Responsibility

Name	Responsibility
`GameY` (struct)	Encapsula el estado completo de una partida en progreso.
`board_size` (u32)	Tamaño del tablero triangular (ej: 7).
`board_map` (HashMap)	Mapea coordenadas baricéntricas a (SetIdx, PlayerId) - representa celdas ocupadas.
`history` (Vec)	Historial de movimientos realizados en orden cronológico.
`sets` (Vec<PlayerSet>)	Vector de estructuras Union-Find, una por jugador, para detectar cadenas conectadas.
`available_cells` (Vec<u32>)	Lista de índices de celdas disponibles donde se pueden colocar piezas.
`GameStatus` (enum)	Representa si el juego está `Ongoing` o `Finished` (con ganador).
`Cell` (enum)	Estado de una celda: `Empty` u `Occupied(PlayerId)`.
`check_game_over()`	Método que retorna true si el juego ha terminado.
`add_move()`	Método que valida, aplica y registra un movimiento.

GameY (struct)

Encapsula el estado completo de una partida en progreso.

board_size (u32)

Tamaño del tablero triangular (ej: 7).

board_map (HashMap)

Mapea coordenadas baricéntricas a (SetIdx, PlayerId) - representa celdas ocupadas.

history (Vec)

Historial de movimientos realizados en orden cronológico.

sets (Vec<PlayerSet>)

Vector de estructuras Union-Find, una por jugador, para detectar cadenas conectadas.

available_cells (Vec<u32>)

Lista de índices de celdas disponibles donde se pueden colocar piezas.

GameStatus (enum)

Representa si el juego está Ongoing o Finished (con ganador).

Cell (enum)

Estado de una celda: Empty u Occupied(PlayerId).

check_game_over()

Método que retorna true si el juego ha terminado.

add_move()

Método que valida, aplica y registra un movimiento.

5.3.3. White Box coord.rs (Sistema de Coordenadas)

Motivation: Define el sistema de coordenadas baricéntricas utilizado para ubicar celdas en el tablero triangular. Este sistema es fundamental para la representación del estado del juego.

Name Responsibility

Name	Responsibility
`Coordinates` (struct)	Tupla (x, y, z) con la invariante x + y + z = board_size. Ubicación única de cada celda.
`new()`	Constructor que valida la invariante baricéntrica.
`to_index()`	Convierte coordenadas baricéntricas a índice lineal.
`from_index()`	Convierte índice lineal a coordenadas baricéntricas.

Coordinates (struct)

Tupla (x, y, z) con la invariante x + y + z = board_size. Ubicación única de cada celda.

new()

Constructor que valida la invariante baricéntrica.

to_index()

Convierte coordenadas baricéntricas a índice lineal.

from_index()

Convierte índice lineal a coordenadas baricéntricas.

5.3.4. White Box movement.rs (Tipos de Movimientos)

Motivation: Define los tipos de movimientos que pueden realizarse en el juego, permitiendo operaciones más allá de colocación de piezas (ej: intercambios, abandonos).

Name Responsibility

Name	Responsibility
`Movement` (enum)	Movimiento del juego: `Placement {player, coords}` o `Action {player, action}`.
`GameAction` (enum)	Acción especial: `Swap` (intercambiar colores en movimiento inicial) o `Resign` (abandonar partida).

Movement (enum)

Movimiento del juego: Placement {player, coords} o Action {player, action}.

GameAction (enum)

Acción especial: Swap (intercambiar colores en movimiento inicial) o Resign (abandonar partida).

5.3.5. White Box bot (Inteligencia Artificial)

Motivation: Contiene las estrategias de decisión para jugadores controlados por computadora, permitiendo diferentes niveles de dificultad y estilos de juego.

Name Responsibility

Name	Responsibility
ybot.rs	Interfaz `YBot` trait que define el comportamiento de un bot: `choose_move()`.
strategies/	Directorio con diferentes estrategias implementadas (random, minimax, heurística, etc.).
ybot_registry.rs	Registro de bots disponibles para creación y administración.

ybot.rs

Interfaz YBot trait que define el comportamiento de un bot: choose_move().

strategies/

Directorio con diferentes estrategias implementadas (random, minimax, heurística, etc.).

ybot_registry.rs

Registro de bots disponibles para creación y administración.

5.3.6. White Box bot_server (Servidor WebSocket)

Motivation: Servidor Axum que expone la lógica del juego mediante WebSocket para comunicación real-time con clientes, permitiendo juego multijugador y contra IA.

Name	Responsibility
mod.rs	Configuración del servidor Axum, rutas, y manejadores WebSocket.
choose.rs	Lógica de selección de movimiento del bot y respuesta al cliente.
state.rs	Estado compartido de la aplicación (registro de bots, sesiones).
error.rs	Tipos de error y respuestas HTTP/WebSocket.
version.rs	Gestión de versiones de API.

Name

Responsibility

mod.rs

Configuración del servidor Axum, rutas, y manejadores WebSocket.

choose.rs

Lógica de selección de movimiento del bot y respuesta al cliente.

state.rs

Estado compartido de la aplicación (registro de bots, sesiones).

error.rs

Tipos de error y respuestas HTTP/WebSocket.

version.rs

Gestión de versiones de API.

6. Runtime View

Esta sección describe los escenarios dinámicos arquitectónicamente relevantes del sistema, mostrando cómo interactúan los bloques principales (webapp, users, gamey) durante la ejecución.

Se han seleccionado únicamente escenarios representativos y arquitectónicamente significativos.

6.1. Runtime Scenario 1: Registro de usuario

6.1.1. Descripción del escenario

El usuario accede a la webapp desde el navegador.
Introduce su username y password en el formulario RegisterForm.
El componente RegisterForm ejecuta la función handleSubmit.
La webapp envía una petición HTTP POST a users (ruta /createuser).
El servicio users procesa la petición, cifra la contraseña y almacena el usuario en MongoDB.
users devuelve un mensaje JSON con el resultado (status 201 si es exitoso).
La webapp actualiza su estado interno y almacena el usuario en localStorage.
El mensaje de éxito se muestra en la interfaz.
El usuario es redirigido automáticamente a la pantalla principal.

6.1.2. Diagrama de secuencia

6.1.3. Aspectos arquitectónicamente relevantes

Comunicación síncrona mediante HTTP REST.
Separación clara entre frontend (React/TypeScript) y backend (Node.js/Express).
Gestión asíncrona del estado en React mediante hooks (useState, fetch).
Validación en cliente antes de enviar la petición.
Persistencia de autenticación mediante localStorage.
Cifrado de contraseñas con bcryptjs antes de almacenarlas.
Exposición de métricas Prometheus por parte de users.
Uso de CORS para permitir comunicación entre servicios.

6.2. Runtime Scenario 2: Autenticación de usuario (Login)

6.2.1. Descripción del escenario

El usuario accede a la webapp y ve el formulario de LoginForm.
Introduce su username y password.
El componente LoginForm ejecuta la función handleSubmit.
La webapp envía una petición HTTP POST a users (ruta /login).
El servicio users busca el usuario en MongoDB y verifica la contraseña.
Si la autenticación es exitosa, users devuelve status 200 con los datos del usuario.
La webapp almacena el username en localStorage y actualiza el estado de autenticación.
El usuario accede al tablero de juego y componentes autenticados.

6.2.2. Diagrama de secuencia

6.2.3. Aspectos arquitectónicamente relevantes

Validación de credenciales con bcryptjs.
Persistencia de sesión mediante localStorage.
Manejo de errores de autenticación (status 401).
Separación entre lógica de presentación y de negocio.
No se utilizan sesiones del servidor, sino validación stateless.

6.3. Runtime Scenario 3: Solicitud de movimiento al motor gamey mediante WebSocket

6.3.1. Descripción del escenario

El usuario autenticado accede al componente GameBoard.
El cliente establece una conexión WebSocket a gamey (puerto 4000, ruta /ws).
El usuario coloca una pieza en el tablero mediante interacción con la UI.
El cliente envía el movimiento en formato JSON a través del WebSocket.
gamey recibe el movimiento y valida su legalidad.
Se ejecuta la lógica de actualización del tablero en core/game.rs.
El servidor gamey calcula si hay un ganador (mediante Union-Find).
Se devuelve el estado del juego actualizado (tablero, estado, turno).
Si el modo es PvC (jugador vs computadora), el bot calcula automáticamente su movimiento.
El servidor envía el movimiento del bot al cliente.
La webapp actualiza la visualización del tablero en tiempo real.

6.3.2. Diagrama de secuencia

6.3.3. Aspectos arquitectónicamente relevantes

Comunicación bidireccional en tiempo real mediante WebSocket.
Separación clara entre capa de presentación (React) y lógica de dominio (Rust).
Motor desacoplado: funciona como CLI, servidor HTTP o biblioteca.
Uso de estructuras eficientes (Union-Find para detección de conectividad).
Validación de movimientos en el servidor.
Formato de serialización: YEN (notación de juego).
Escalabilidad: múltiples clientes simultáneos pueden conectarse.

6.4. Runtime Scenario 4: Inicio del sistema mediante Docker Compose

6.4.1. Descripción del escenario

El operador ejecuta docker-compose up --build en la raíz del proyecto.
Docker construye las imágenes de webapp, users y gamey.
Se levantan los contenedores correspondientes en orden de dependencias:
- users comienza primero (puerto 3000 interno).
- webapp comienza después, dependiendo de users (puerto 80 interno).
- gamey inicia en paralelo (puerto 4000 interno).
Se crea la red Docker monitor-net para comunicación interna.
users comienza a exponer métricas en /metrics mediante express-prom-bundle.
prometheus comienza a recolectarlas (puerto 9090).
grafana permite visualizar las métricas (puerto 9091, redirecciona a 3000 internamente).
webapp está accesible desde el navegador en localhost (puerto 80).
gamey está accesible desde webapp en host.docker.internal:4000 o mediante nombre de servicio.

6.4.2. Diagrama de secuencia

6.4.3. Aspectos arquitectónicamente relevantes

Infraestructura reproducible e inmutable mediante contenedores.
Aislamiento de servicios mediante red Docker interna.
Monitorización integrada con stack Prometheus + Grafana.
Comunicación segura entre servicios mediante red Docker.
Gestión de dependencias entre servicios (depends_on).
Puertos mapeados para acceso desde el host.
Variables de entorno para configuración dinámica (imagen tags, MONGODB_URI, etc.).

6.5. Runtime Scenario 5: Fallo del servicio users

6.5.1. Descripción del escenario

El usuario intenta registrarse o hacer login.
La webapp envía la petición HTTP a users (puerto 3000).
El servicio users no está disponible (contenedor caído o red inaccesible).
La petición falla por timeout o error de conexión (ERR_CONNECTION_REFUSED).
El componente React captura la excepción en el bloque catch del fetch.
La webapp muestra un mensaje de error al usuario.
Prometheus detiene la recolección de métricas desde users (error en scrape).
Grafana muestra un estado de advertencia (series sin datos).
El usuario no puede acceder a funcionalidades que requieren autenticación.
Las funcionalidades locales de gamey (si están disponibles) siguen siendo accesibles.

6.5.2. Diagrama de secuencia

Sequence Diagram - Users Service Failure

6.5.3. Aspectos arquitectónicamente relevantes

Manejo explícito de errores en React mediante bloques try-catch.
Timeouts configurables en cliente para fallos de red.
Arquitectura desacoplada que evita fallos en cascada.
Detección de fallos mediante monitorización (Prometheus/Grafana).
Degradación elegante: el sistema sigue parcialmente operativo.
Resiliencia: el usuario puede reintentar la operación.
Logs de error para debugging posterior.

6.6. Runtime Scenario 6: Fallo de gamey (Motor de juego)

6.6.1. Descripción del escenario

El usuario autenticado intenta jugar una partida.
La webapp intenta conectarse a gamey mediante WebSocket (puerto 4000).
El servidor gamey no está disponible (contenedor caído).
La conexión WebSocket falla con error de conexión.
La webapp detecta el error en el manejador onError del WebSocket.
Se muestra un mensaje de error al usuario.
Las funcionalidades de registro y login siguen siendo accesibles (independientes de gamey).
El usuario no puede jugar hasta que gamey se recupere.

6.6.2. Diagrama de secuencia

Sequence Diagram - GameY Service Failure

6.6.3. Aspectos arquitectónicamente relevantes

Aislamiento de fallos: el fallo de gamey no afecta a users.
Manejo de reconexión automática mediante WebSocket.
Mensajes de error informativos al usuario.
Monitorización independiente de cada servicio.
Recuperación automática cuando el servicio se reinicia.

7. Vista de Despliegue

Contenido

La vista de despliegue describe:

el mapeo de los bloques de construcción (software) a esos elementos de infraestructura.

A menudo los sistemas se ejecutan en diferentes entornos, por ejemplo entorno de desarrollo, entorno de pruebas y entorno de producción. En tales casos se deben documentar todos los entornos relevantes.

Documenta especialmente una vista de despliegue si tu software se ejecuta como un sistema distribuido con más de un ordenador, procesador, servidor o contenedor, o cuando diseñes y construyas tus propios procesadores y chips de hardware.

Desde una perspectiva de software es suficiente capturar solo aquellos elementos de una infraestructura que son necesarios para mostrar un despliegue de tus bloques de construcción. Los arquitectos de hardware pueden ir más allá y describir la infraestructura con cualquier nivel de detalle que necesiten capturar.

Motivación

El software no se ejecuta sin hardware. Esta infraestructura subyacente puede e influirá en un sistema y/o en algunos conceptos transversales. Por lo tanto, existe la necesidad de conocer la infraestructura.

Forma

Quizá un diagrama de despliegue de más alto nivel ya esté incluido en la sección 3.2 como contexto técnico con tu propia infraestructura como UNA caja negra. En esta sección se puede profundizar en esa caja negra usando diagramas de despliegue adicionales:

UML ofrece diagramas de despliegue para expresar esa vista. Úsalos, probablemente con diagramas anidados, cuando tu infraestructura sea más compleja.
Si tus partes interesadas (stakeholders de hardware) prefieren otro tipo de diagramas en lugar de un diagrama de despliegue, que utilicen cualquiera que pueda mostrar nodos y canales de la infraestructura.

Más Información

Consulta la documentación de arc42 sobre la Vista de Despliegue: Deployment View.

7.1. Infraestructura Nivel 1

Describe (usualmente en una combinación de diagramas, tablas y texto):

distribución de un sistema a múltiples ubicaciones, entornos, ordenadores, procesadores, …, así como las conexiones físicas entre ellos
justificaciones o motivaciones importantes para esta estructura de despliegue
características de calidad y/o rendimiento de esta infraestructura
mapeo de artefactos de software a elementos de esta infraestructura

Para múltiples entornos o despliegues alternativos, por favor copia y adapta esta sección de arc42 para todos los entornos relevantes.

Motivación

El sistema se desplegará en la nube de Oracle que conectará con una Base de Datos creada en MongoDB por distintas motivaciones:

Escalabilidad Automática: Oracle permite escalar según la carga de usuarios sin intervención manual.
Seguridad: Oracle proporciona cifrado de datos.
Flexibilidad: MongoDB es ideal ya que las entidades cambiaran con el tiempo.
Polimorfismo Sencillo: MongoDB permite modelas fácilmente el cambio entre entidades.
Rendimiento Excelente: MongoDB es óptimo para registros rápidos de eventos e interacciones frecuentes.

Características de Calidad y/o Rendimiento

En esencia las características principales que se consigan al desplegar son:

Escalabilidad
Rendimiento
Seguridad
Eficiencia

Mapeo de Bloques de Construcción a Infraestructura

En el estado actual del proyecto, el despliegue de la aplicación se realiza mediante la infraestructura proporcionada por GitHub, concretamente a través de GitHub Actions y el sistema de Releases.

Proceso de despliegue

Se accede al repositorio del proyecto en Github, en la sección de código.
Desde la interfaz del repositorio, se navega a la sección de Releases.
Se crea una nueva release, lo que implica: — Crear una nueva etiqueta (tag) asociada a una versión del proyecto. — Definir un título, y, opcionalmente, una descripción de los cambios. — Seleccionar la rama sobre la que se desea realizar el despliegue.
En caso de tratarse de una versión no definitiva, se marca como pre-release, indicando que es una versión de pruebas.
Una vez creada la release, se inicia automáticamente el proceso de despliegue medainte workflows definidos en Github Actions.
El sistema ejecuta las tareas necesarias (compilación, tests, empaquetado y despliegue).
Si el proceso finaliza correctamente, la aplicación queda accesible a través del enlace generado, disponible en la sección de Actions o asociado a la propia release.

Este enfoque permite automatizar completamente el despliegue, garantizando consistencia entre versiones y facilitando la integración continua y entrega continua.

Mapeo conceptual

Repositorio Github → Código fuentre de la aplicación.
Github Actions → Ejecución de pipelines de despliegue.
Releases → Versionado y activación del proceso de despliegue.
Infraestructura en la nuve (Oracle) → Entorno final donde se ejecuta la aplicación.
MongoDB → Sistema de almacenamiento de datos persistentes.

Este modelo permite desacoplar el desarrollo de despliegue, facilitando la evolución del sistema y asegurando trazabilidad entre versiones desplegadas.

8. Conceptos Transversales

Contenido

Esta sección describe normas generales, ideas de solución y regulaciones principales que son relevantes en múltiples partes (= transversales) de tu sistema. Tales conceptos suelen estar relacionados con varios bloques de construcción. Pueden incluir muchos temas diferentes, como

modelos, especialmente modelos del dominio
patrones de arquitectura o de diseño
reglas para el uso de tecnologías específicas
decisiones principales, a menudo técnicas, de carácter general (= transversal)
reglas de implementación

Motivación

Los conceptos forman la base de la integridad conceptual (consistencia, homogeneidad) de la arquitectura. Por lo tanto, son una contribución importante para lograr las cualidades internas de tu sistema.

Algunos de estos conceptos no pueden asignarse a bloques de construcción individuales, por ejemplo seguridad o protección.

Forma

La forma puede variar:

documentos de concepto con cualquier tipo de estructura
extractos de modelos transversales o escenarios usando notaciones de las vistas de arquitectura
implementaciones de ejemplo, especialmente para conceptos técnicos
referencias al uso típico de frameworks estándar (por ejemplo, usar Hibernate para el mapeo objeto/relacional)

Estructura

Una posible (pero no obligatoria) estructura para esta sección podría ser:

Conceptos de dominio
Conceptos de experiencia de usuario (UX)
Conceptos de seguridad y protección
Patrones de arquitectura y de diseño
“Bajo el capó”
Conceptos de desarrollo
Conceptos operativos

Nota: puede ser difícil asignar conceptos individuales a un tema específico de esta lista.

Posibles temas para conceptos transversales

Más Información

Consulta Concepts en la documentación de arc42.

8.1. Concepto de Dominio

Usuarios: Tendrán nombre, nombre de usuario, contraseña, además de las estadísticas que irán variando según usen YOVI. Representan a los usuarios reales.
Bots: En caso de que un usuario no juegue contra otra persona real, jugará contra un bot, que tendrá nombre y dificultad.
JuegosY: Juego principal, con modo, jugadores y un resultado que se dará una vez su estado sea finalizado.
Partidas: Representa las partidas jugadas para facilitar el estado de la aplicación.

8.2. Conceptos de Experiencia de Usuario

La experiencia de usuario se centra en ofrecer una interfaz web clara, accesible y atractiva que permita a los jugadores interactuar de forma fluida con el "Juego Y". El sistema prioriza la facilidad de uso mediante un diseño intuitivo, asegurando que tanto el registro como la participación en las distintas modalidades de juego sean procesos sencillos y directos.

8.3. Conceptos de Seguridad

La seguridad de la aplicación se basa actualmente en el aislamiento de componentes mediante una arquitectura de microservicios y el uso de variables de entorno para proteger credenciales sensibles. El proyecto integra además análisis de calidad continuo en su flujo de desarrollo y planea implementar un sistema centralizado de autenticación para gestionar el acceso de forma segura.

8.4. Conceptos de Arquitectura

La arquitectura de la aplicación se basa en un sistema de microservicios independientes que desacoplan la interfaz web, el servicio de gestión de usuarios y el motor de lógica de juego desarrollado en Rust. Estos componentes interactúan mediante el intercambio de mensajes JSON y están contenedorizados con Docker para garantizar un despliegue consistente, escalable y reproducible en la nube.

8.5. Conceptos de Desarrollo

El desarrollo de la aplicación se fundamenta en un ciclo de integración y despliegue continuos (CI/CD) que prioriza el testing automatizado y el análisis de calidad con SonarCloud. Todo el proceso se apoya en la contenedorización con Docker y flujos de trabajo en GitHub Actions para asegurar entregas rápidas, consistentes y reproducibles en cualquier entorno.

9. Decisiones de Arquitectura

Contenido

Decisiones de arquitectura importantes, costosas, a gran escala o arriesgadas, incluyendo las justificaciones. Con “decisiones” nos referimos a seleccionar una alternativa basándose en criterios dados.

Por favor, usa tu criterio para decidir si una decisión de arquitectura debe documentarse aquí en esta sección central o si es mejor documentarla de forma local (por ejemplo, dentro de la plantilla de caja blanca de un bloque de construcción).

Evita la redundancia. Haz referencia a la sección 4, donde ya capturaste las decisiones más importantes de tu arquitectura. :contentReference[oaicite:0]{index=0}

Motivación

Los interesados (stakeholders) de tu sistema deben poder comprender y reconstruir tus decisiones. :contentReference[oaicite:1]{index=1}

Forma

Varias opciones posibles:

ADR (Architecture Decision Record, Registro de Decisión de Arquitectura) para cada decisión importante :contentReference[oaicite:2]{index=2}
Lista o tabla, ordenada por importancia y consecuencias :contentReference[oaicite:3]{index=3}
Más detallado en forma de secciones separadas por cada decisión :contentReference[oaicite:4]{index=4}

Más Información

Consulta Architecture Decisions en la documentación de arc42. Allí encontrarás enlaces y ejemplos sobre los ADR. :contentReference[oaicite:5]{index=5}

9.1. Máquina Ubuntu en la Nube de Oracle

Se ha decidido desplegar YOVI mediante una Máquina Ubuntu en la Nube de Oracle por distintas motivaciones:

Estabilidad: Ubuntu es conocida por ser una distribución robusta ampliamente usada en entornos de producción.
Compatabilidad: A sabiendas que el proyecto desarrollo comprenderá de alguna que otra API, esta decisión minimizará problemas de compatibilidad ya que una gran parte de estos microservicios funcionan de forma óptima en Ubuntu.
Costes: Las máquinas Linux en Oracle al no incluir licencias adicionales resultan más baratas que otro tipo de máquinas.
Control: Una máquina virtual Ubuntu permite instalar software personalizado además de ofrecer control total del sistema operativo.

Las consecuencias que se pueden llegar a dar son las siguientes:

Mayor Responsabilidad Operativa: Al tener control total del sistema operativo, la administración recae sobre el equipo.
Seguridad: La gestión de la seguridad recae sobre los desarrolladores.

9.2. Base de Datos en MongoDB

Se ha decidido desarrollar la Base de Datos mediante MongoDB por distintas motivaciones:

Flexibilidad: MongoDB es ideal para modelos que evolucionan, contienen relaciones flexibles o estructuras variables, como es el caso.
Alto Rendimiento: MongoDB está optimizado para sistemas en tiempo real.
Resilencia Integrada: Los Backups son automáticos

Las consecuencias que se pueden llegar a dar son las siguientes:

Riesgo de Desestructuración: En caso de diseñar incorrectamente la Base de Datos, la flexibilidad se convertirá en un problema ya que generará documentos inconsistentes.

9.3. Arquitectura de Microservicios Políglota

Motivación: Separar la lógica de negocio y gestión de usuarios (Node.js) del motor de juego de alto rendimiento (Rust). Rust ofrece seguridad de memoria y velocidad para las reglas del juego, mientras que Node.js permite un desarrollo rápido del servicio de usuarios.
Consecuencias: Aumenta la complejidad del despliegue y la comunicación entre servicios, pero permite escalar cada componente de forma independiente.

9.4. Contenedorización con Docker y Docker Compose

Motivación: Garantizar que la aplicación funcione exactamente igual en desarrollo, testing y producción (Oracle Cloud). Facilita el despliegue de toda la infraestructura (servicios, base de datos, monitoreo) con un solo comando.
Consecuencias: requiere gestionar imágenes y volúmenes, además de una ligera sobrecarga de recursos en comparación con ejecuciones nativas.

9.5. Uso de Vite + React + TypeScript para el Frontend

Motivación: Vite ofrece tiempos de compilación extremadamente rápidos. TypeScript proporciona seguridad de tipos, reduciendo errores en tiempo de ejecución y mejorando la mantenibilidad del código a largo plazoñ
Consecuencias: Curva de aprendizaje inicial para TypeScript y necesidad de configurar tipos para librerías externas.

9.6. Estrategia de CI/CD con Github Actions y SonarCloud

Motivación: Automatizar las pruebas y el despliegue para detectar errores pronto. SOnarCloud asegura que el código mantenga estándares de calidad y seguridad antes de ser integrado.
Consecuencais: El flujo de desarrollo depende de la disponibilidad de estos servicios externos y los tiempos de ejecución de los workflows.

9.7. Observabilidad con Prometheus y Grafana

Motivación: Tener visibilidad en tiempo real sobre el estasdo de los servicios y el uso de recursos. Permite identificar cuellos de botella o fallos en producción de manera proactiva.
Consecuencias: añade componentes adicionales a la arquitectura que deben ser configurados y mantenidos (exportadores de métricas, almacenamientos de datos).

10. Testing

10.1. Introducción

Este documento describe la estrategia de testing de YOVI y los mecanismos utilizados para validar calidad, estabilidad y rendimiento del sistema.

La aplicación está compuesta por:

Motor de juego en Rust (gamey)
Servicio de usuarios en Node.js (users)
Aplicación web en React (webapp)
Pruebas de carga con Gatling

10.1.1. Objetivos

Verificar el correcto funcionamiento del sistema
Detectar errores de forma temprana
Validar integración entre componentes
Medir rendimiento bajo carga
Automatizar pruebas mediante CI/CD

10.2. Estructura del Testing

10.2.1. Directorios principales

yovi_es3a/
├── gamey/tests/
├── users/__tests__/
├── webapp/__tests__/
├── testCarga/
└── docs/TESTING.adoc

10.2.2. Herramientas utilizadas

Herramienta	Componente	Uso
Cargo Test	gamey	Tests unitarios Rust
Vitest	users, webapp	Tests unitarios e integración
Supertest	users	Testing de APIs REST
Playwright	webapp	Tests E2E
Gatling	testCarga	Tests de carga
SonarQube	Todos	Calidad y cobertura
GitHub Actions	Todos	Automatización CI/CD

Herramienta

Componente

Uso

Cargo Test

gamey

Tests unitarios Rust

Vitest

users, webapp

Tests unitarios e integración

Supertest

users

Testing de APIs REST

Playwright

webapp

Tests E2E

Gatling

testCarga

Tests de carga

SonarQube

Todos

Calidad y cobertura

GitHub Actions

Todos

Automatización CI/CD

10.3. Testing del Motor de Juego (gamey)

10.3.1. Visión General

El motor de juego está desarrollado en Rust y utiliza cargo test.

Se validan reglas del juego, movimientos, detección de victoria, persistencia y servidor de bots.

10.3.2. Categorías de Tests

Categoría	Descripción
Inicialización	Creación correcta del tablero y estado inicial
Flujo de juego	Turnos, movimientos válidos y ocupación
Victoria	Detección de conexión de tres lados
Errores	Jugadas inválidas y turnos incorrectos
Persistencia	Guardado y carga en formato YEN
Coordenadas	Conversión índice ↔ coordenadas
Bot Server	Endpoints HTTP/WebSocket

Categoría

Descripción

Inicialización

Creación correcta del tablero y estado inicial

Flujo de juego

Turnos, movimientos válidos y ocupación

Victoria

Detección de conexión de tres lados

Errores

Jugadas inválidas y turnos incorrectos

Persistencia

Guardado y carga en formato YEN

Coordenadas

Conversión índice ↔ coordenadas

Bot Server

Endpoints HTTP/WebSocket

10.3.3. Ejecución

cd gamey
cargo test
cargo llvm-cov

10.4. Testing del Servicio de Usuarios (users)

10.4.1. Visión General

El servicio de usuarios en Node.js utiliza Vitest y Supertest para validar lógica interna y endpoints REST.

10.4.2. Categorías de Tests

Categoría	Descripción
Registro	Alta de usuarios y validación de datos
Login	Credenciales correctas e incorrectas
CRUD	Operaciones básicas sobre usuarios
Seguridad	Hash de contraseñas y tokens
Validación	Emails y contraseñas válidas
Manejo de errores	Respuestas ante entradas inválidas

Categoría

Descripción

Registro

Alta de usuarios y validación de datos

Credenciales correctas e incorrectas

CRUD

Operaciones básicas sobre usuarios

Seguridad

Hash de contraseñas y tokens

Validación

Emails y contraseñas válidas

Manejo de errores

Respuestas ante entradas inválidas

10.4.3. Ejecución

cd users
npm test
npm run test:coverage

10.5. Testing del Frontend (webapp)

10.5.1. Visión General

El frontend desarrollado en React + TypeScript utiliza Vitest para tests unitarios y Playwright para pruebas End-to-End.

10.5.2. Categorías de Tests

Categoría	Descripción
Componentes	Renderizado y props
Formularios	Inputs y validaciones
Navegación	Cambio entre páginas
Integración	Comunicación con backend
Juego	Renderizado del tablero e interacción
E2E	Login y flujo completo de partida

Categoría

Descripción

Componentes

Renderizado y props

Formularios

Inputs y validaciones

Navegación

Cambio entre páginas

Integración

Comunicación con backend

Juego

Renderizado del tablero e interacción

E2E

10.5.3. Ejecución

cd webapp
npm test
npm run test:coverage
npx playwright test

10.6. Testing de Carga (Gatling)

10.6.1. Visión General

Gatling se utiliza para simular múltiples usuarios concurrentes y medir rendimiento del sistema.

10.6.2. Proceso de ejecución

Inicio de Gatling desde el entorno de desarrollo
Uso del modo Recorder para capturar tráfico real
Simulación de acciones principales:
- Registro de usuario
- Inicio de sesión
Generación automática del script
Ajuste manual del escenario:
- Incremento de usuarios
- Repeticiones
- Parámetros de carga
Ejecución de la simulación

10.6.3. Escenarios evaluados

Escenario	Descripción
Login concurrente	Varias autenticaciones simultáneas
Registro concurrente	Creación simultánea de usuarios
Carga progresiva	Incremento gradual de usuarios
Estrés	Alta concurrencia sostenida

Escenario

Descripción

Varias autenticaciones simultáneas

Registro concurrente

Creación simultánea de usuarios

Carga progresiva

Incremento gradual de usuarios

Estrés

Alta concurrencia sostenida

10.6.4. Métricas analizadas

Tiempo de respuesta medio
Percentiles p95 / p99
Throughput
Solicitudes exitosas/fallidas
Estabilidad del sistema

10.6.5. Resultados: Escenario Base (10 usuarios)

Métricas generales

Tasa de éxito: 100%
Errores KO: 0
Duración aproximada: 10 segundos
Pico máximo: 10 peticiones/segundo
Respuestas rápidas concentradas en ~73 ms
Algunos picos aislados entre 542 ms y 1000+ ms

Rendimiento por endpoint

Endpoint	Peticiones	Mínimo	p50	p95	Máximo	Media
Login	10	166 ms	734 ms	1240 ms	1240 ms	693 ms
Register	10	67 ms	71 ms	83 ms	83 ms	72 ms

Endpoint

Peticiones

Mínimo

p50

p95

Máximo

Media

166 ms

734 ms

1240 ms

693 ms

67 ms

71 ms

83 ms

72 ms

]["Grafica de resultados Gatling 10 usuarios"

Análisis

El sistema respondió correctamente sin errores. El endpoint register mostró excelente rendimiento y login fue claramente más costoso.

10.6.6. Resultados: Escenario Alta Carga (100 usuarios)

Métricas generales

Total de peticiones: 200
100 login + 100 register
Tasa de éxito: 100%
Errores KO: 0
Tiempo medio global: 4723 ms

Distribución observada

~100 peticiones por debajo de 800 ms
~100 peticiones por encima de 1200 ms

Rendimiento por endpoint

Endpoint	Peticiones	Mínimo	p50	p95	Máximo	Media
Login	100	4700 ms	8300 ms	14200 ms	14200 ms	8300 ms
Register	100	84 ms	78 ms	870 ms	870 ms	104 ms

Endpoint

Peticiones

Mínimo

p50

p95

Máximo

Media

100

4700 ms

8300 ms

14200 ms

8300 ms

100

84 ms

78 ms

870 ms

104 ms

]["Grafica de resultados Gatling 100 usuarios"

Análisis

Existe una diferencia crítica entre endpoints:

register mantiene tiempos excelentes incluso bajo carga.
login se degrada severamente al aumentar concurrencia.

]["Numero de peticiones por segundo y respuestas por segundo"

10.6.7. Ejecución

cd testCarga
./mvnw gatling:test

10.7. Integración Continua (CI/CD)

10.7.1. Automatización

GitHub Actions ejecuta pruebas automáticamente en cada push y pull request.

10.7.2. Flujo

Instalación de dependencias
Ejecución de tests Rust
Ejecución de tests Node.js
Cobertura de código
Tests de carga
Análisis con SonarQube

10.7.3. Quality Gate

Estado: PASSED (All conditions passed)

Métrica	Objetivo	Resultado Actual
Cobertura	≥ 80%	85.6%
Duplicación	≤ 3%	2.1%
Vulnerabilidades	0	Rating A

Métrica

Objetivo

Resultado Actual

Cobertura

≥ 80%

85.6%

Duplicación

≤ 3%

2.1%

Vulnerabilidades

Rating A

10.7.4. Snapshot de Calidad (SonarQube)

Categoría	Calificación (Rating)
Security Rating	A
Security Hotspots	E
Reliability (Fiabilidad)	A
Maintainability (Mantenibilidad)	A

Categoría

Calificación (Rating)

Security Rating

Security Hotspots

Reliability (Fiabilidad)

Maintainability (Mantenibilidad)

11. Requisitos de calidad

11.1. Árbol de calidad

11.2. Escenarios de calidad

ID Atributo (Rama) Escenario / Descripción (Hoja)

ID	Atributo (Rama)	Escenario / Descripción (Hoja)
ESC-F1	Funcionalidad	El juego funciona correctamente: El sistema permite a los usuarios desarrollar una partida completa, aplicando todas las reglas del juego de principio a fin sin bloqueos ni errores lógicos en el motor.
ESC-F2	Funcionalidad	Cumplimiento de la notación YEN: Cuando el estado de la partida cambia, el motor (Rust) lo serializa y el backend lo transmite garantizando el cumplimiento estricto de la notación YEN, rechazando cualquier estado malformado.
ESC-R1	Rendimiento	Tiempo de respuesta de jugada: La comunicación entre el frontend, el API de usuarios y el motor del juego procesa y devuelve la jugada al usuario en menos de 1 segundo bajo condiciones normales de red.
ESC-R2	Rendimiento	Eficiencia de concurrencia: El uso del motor en Rust permite procesar de forma simultánea múltiples solicitudes de jugadas de distintas partidas activas sin que el tiempo de respuesta se degrade de forma notable.
ESC-S1	Seguridad	Validación de entradas del API: El backend realiza una validación estricta de todos los datos recibidos. Si un cliente envía datos malformados o jugadas ilegales, la solicitud es rechazada de forma segura (ej. HTTP 400).
ESC-S2	Seguridad	Aislamiento y Proxy inverso: La arquitectura garantiza que los puertos internos de la aplicación y la base de datos no sean accesibles directamente desde el exterior, utilizando Nginx como proxy inverso para enrutar el tráfico de forma segura.
ESC-D1	Disponibilidad	Accesibilidad web pública: La aplicación web es accesible desde internet mediante una IP/URL pública, permitiendo a los usuarios conectarse y jugar sin interrupciones.
ESC-D2	Disponibilidad	Tolerancia a fallos y reinicio rápido: Gracias al despliegue contenedorizado (`docker-compose`), si uno de los servicios (ej. el backend o la base de datos) sufre una caída inesperada, el sistema es capaz de reiniciarlo rápidamente para minimizar el tiempo de inactividad.
ESC-M1	Mantenibilidad	Separación clara frontend/backend/motor: La arquitectura orientada a servicios permite que un desarrollador actualice la interfaz de usuario (`webapp`) sin necesidad de modificar o recompilar el estricto motor de reglas (`gamey`).
ESC-M2	Mantenibilidad	Monitorización de código con SonarQube: El código fuente se somete a análisis estático mediante SonarQube, lo que permite detectar "code smells", medir la cobertura de pruebas y controlar la deuda técnica antes de cada integración.

ESC-F1

Funcionalidad

El juego funciona correctamente: El sistema permite a los usuarios desarrollar una partida completa, aplicando todas las reglas del juego de principio a fin sin bloqueos ni errores lógicos en el motor.

ESC-F2

Funcionalidad

Cumplimiento de la notación YEN: Cuando el estado de la partida cambia, el motor (Rust) lo serializa y el backend lo transmite garantizando el cumplimiento estricto de la notación YEN, rechazando cualquier estado malformado.

ESC-R1

Rendimiento

Tiempo de respuesta de jugada: La comunicación entre el frontend, el API de usuarios y el motor del juego procesa y devuelve la jugada al usuario en menos de 1 segundo bajo condiciones normales de red.

ESC-R2

Rendimiento

Eficiencia de concurrencia: El uso del motor en Rust permite procesar de forma simultánea múltiples solicitudes de jugadas de distintas partidas activas sin que el tiempo de respuesta se degrade de forma notable.

ESC-S1

Seguridad

Validación de entradas del API: El backend realiza una validación estricta de todos los datos recibidos. Si un cliente envía datos malformados o jugadas ilegales, la solicitud es rechazada de forma segura (ej. HTTP 400).

ESC-S2

Seguridad

Aislamiento y Proxy inverso: La arquitectura garantiza que los puertos internos de la aplicación y la base de datos no sean accesibles directamente desde el exterior, utilizando Nginx como proxy inverso para enrutar el tráfico de forma segura.

ESC-D1

Disponibilidad

Accesibilidad web pública: La aplicación web es accesible desde internet mediante una IP/URL pública, permitiendo a los usuarios conectarse y jugar sin interrupciones.

ESC-D2

Disponibilidad

Tolerancia a fallos y reinicio rápido: Gracias al despliegue contenedorizado (docker-compose), si uno de los servicios (ej. el backend o la base de datos) sufre una caída inesperada, el sistema es capaz de reiniciarlo rápidamente para minimizar el tiempo de inactividad.

ESC-M1

Mantenibilidad

Separación clara frontend/backend/motor: La arquitectura orientada a servicios permite que un desarrollador actualice la interfaz de usuario (webapp) sin necesidad de modificar o recompilar el estricto motor de reglas (gamey).

ESC-M2

Mantenibilidad

Monitorización de código con SonarQube: El código fuente se somete a análisis estático mediante SonarQube, lo que permite detectar "code smells", medir la cobertura de pruebas y controlar la deuda técnica antes de cada integración.

12. Riesgos y deuda técnica

Contents

A list of identified technical risks or technical debts, ordered by priority

12.1. Riesgos

Riesgo Descripción Impacto Probabilidad Mitigación

Riesgo	Descripción	Impacto	Probabilidad	Mitigación
Complejidad tecnológica (Rust + Node/TS + React)	El uso combinado de lenguajes de sistemas estrictos (Rust para el motor) y lenguajes web (TypeScript/Node) requiere distintos paradigmas. Esto eleva la curva de aprendizaje y dificulta que un desarrollador Full-Stack pueda resolver bugs transversales rápidamente.	Alto	Media	Fomentar la revisión de código cruzada (Code Reviews) y mantener las interfaces (API REST / Notación YEN) estrictamente documentadas.
Orquestación y Despliegue (Docker / Nginx)	El sistema depende de múltiples contenedores (webapp, users, gamey, db) orquestados por `docker-compose` y enrutados por Nginx. Una mala configuración en las redes de Docker o en el proxy inverso puede dejar el sistema inaccesible o exponer puertos internos.	Alto	Baja	Mantener los archivos `docker-compose.yml` y `nginx.conf` bajo control de versiones estricto, usar `.env` para secretos y realizar pruebas de despliegue en entornos locales (`docker-compose.dev.yml`).
Sincronización del estado del juego (Notación YEN)	El estado del juego viaja desde el motor en Rust hasta el frontend pasando por el backend de usuarios. Cualquier fallo en el parseo o validación estricta de la notación YEN puede corromper la partida de los jugadores.	Alto	Media	Implementar validaciones robustas en la entrada del API y tests unitarios exhaustivos en el motor de Rust que verifiquen casos límite de la notación YEN.
Uso de base de datos no relacional (MongoDB)	Al ser una base de datos orientada a documentos (schema-less), MongoDB no impone integridad referencial estricta (como las claves foráneas en SQL). Si la lógica del backend falla al gestionar relaciones (ej. entre usuarios y sus historiales de partidas), se pueden generar datos huérfanos o estados inconsistentes.	Alto	Media	Forzar esquemas estrictos y validaciones a nivel de aplicación (ej. usando un ODM como Mongoose en el servicio `users`) y gestionar respaldos periódicos del volumen local de la base de datos (`dataBaseFiles`).
Reducción de la capacidad operativa (Salida de un miembro)	Al ser un equipo reducido de 5 personas donde todos los miembros participan en todas las áreas del proyecto (full-stack), la salida de un integrante no genera silos de conocimiento bloqueantes, pero aumenta considerablemente la carga de trabajo del resto. Esto reduciría la velocidad de desarrollo, alargando el tiempo necesario para lanzar nuevas versiones (releases).	Medio	Baja	Ajustar ágilmente el alcance (scope) de las iteraciones si se reduce el equipo, automatizar el mayor número de tareas posibles (CI/CD) para ahorrar tiempo y mantener un ritmo de trabajo sostenible para evitar el agotamiento (burnout) del resto.

Complejidad tecnológica (Rust + Node/TS + React)

El uso combinado de lenguajes de sistemas estrictos (Rust para el motor) y lenguajes web (TypeScript/Node) requiere distintos paradigmas. Esto eleva la curva de aprendizaje y dificulta que un desarrollador Full-Stack pueda resolver bugs transversales rápidamente.

Alto

Media

Fomentar la revisión de código cruzada (Code Reviews) y mantener las interfaces (API REST / Notación YEN) estrictamente documentadas.

Orquestación y Despliegue (Docker / Nginx)

El sistema depende de múltiples contenedores (webapp, users, gamey, db) orquestados por docker-compose y enrutados por Nginx. Una mala configuración en las redes de Docker o en el proxy inverso puede dejar el sistema inaccesible o exponer puertos internos.

Alto

Baja

Mantener los archivos docker-compose.yml y nginx.conf bajo control de versiones estricto, usar .env para secretos y realizar pruebas de despliegue en entornos locales (docker-compose.dev.yml).

Sincronización del estado del juego (Notación YEN)

El estado del juego viaja desde el motor en Rust hasta el frontend pasando por el backend de usuarios. Cualquier fallo en el parseo o validación estricta de la notación YEN puede corromper la partida de los jugadores.

Alto

Media

Implementar validaciones robustas en la entrada del API y tests unitarios exhaustivos en el motor de Rust que verifiquen casos límite de la notación YEN.

Uso de base de datos no relacional (MongoDB)

Al ser una base de datos orientada a documentos (schema-less), MongoDB no impone integridad referencial estricta (como las claves foráneas en SQL). Si la lógica del backend falla al gestionar relaciones (ej. entre usuarios y sus historiales de partidas), se pueden generar datos huérfanos o estados inconsistentes.

Alto

Media

Forzar esquemas estrictos y validaciones a nivel de aplicación (ej. usando un ODM como Mongoose en el servicio users) y gestionar respaldos periódicos del volumen local de la base de datos (dataBaseFiles).

Reducción de la capacidad operativa (Salida de un miembro)

Al ser un equipo reducido de 5 personas donde todos los miembros participan en todas las áreas del proyecto (full-stack), la salida de un integrante no genera silos de conocimiento bloqueantes, pero aumenta considerablemente la carga de trabajo del resto. Esto reduciría la velocidad de desarrollo, alargando el tiempo necesario para lanzar nuevas versiones (releases).

Medio

Baja

Ajustar ágilmente el alcance (scope) de las iteraciones si se reduce el equipo, automatizar el mayor número de tareas posibles (CI/CD) para ahorrar tiempo y mantener un ritmo de trabajo sostenible para evitar el agotamiento (burnout) del resto.

12.2. Deuda técnica

Deuda técnica Descripción Impacto Probabilidad Mitigación

Deuda técnica	Descripción	Impacto	Probabilidad	Mitigación
Code Smells y métricas de SonarQube	Al utilizar herramientas de análisis estático (configuradas en `sonar-project.properties`), se acumula deuda técnica visible (code smells, código duplicado o complejidad ciclomática alta) en los repositorios de TypeScript/JavaScript.	Medio	Alta	Establecer umbrales de calidad (Quality Gates) en el CI/CD y dedicar tiempo en cada sprint para resolver las advertencias de SonarQube antes de integrar código.
Cobertura de Tests End-to-End (E2E)	Dada la arquitectura de microservicios, mantener pruebas funcionales automáticas que crucen desde el frontend (`webapp`), pasen por el API (`users`) y lleguen al motor (`gamey`) requiere un esfuerzo continuo. Las interfaces cambian y los flujos pueden romperse.	Alto	Alta	Mantener y ampliar la cobertura de pruebas de integración y E2E utilizando Cucumber (BDD/Gherkin) y Playwright (actualmente configurados en el proyecto) para automatizar los flujos críticos de interacción del usuario en la interfaz web.
Pruebas de Carga y Rendimiento (Gatling)	Al ser un juego multijugador orquestado en contenedores, existe la deuda técnica de validar cómo se comporta el sistema bajo alta concurrencia. Actualmente el límite real de usuarios simultáneos sin degradación es desconocido.	Alto	Alta	Implementar escenarios de estrés utilizando Gatling. Se aprovechará su Recorder y su DSL basado en Scala/JVM para simular múltiples partidas concurrentes y descubrir cuellos de botella reales en la infraestructura.
Gestión básica de autenticación / Sesiones	La implementación inicial de la autenticación puede carecer de mecanismos avanzados (refresco de tokens automáticos, invalidación de sesiones al cambiar roles, etc.), limitando la escalabilidad de seguridad.	Medio	Media	Refactorizar el módulo de `users` para estandarizar el uso de JWT de corta duración y asegurar que los secretos solo residan en las variables de entorno (`.env`).

Code Smells y métricas de SonarQube

Al utilizar herramientas de análisis estático (configuradas en sonar-project.properties), se acumula deuda técnica visible (code smells, código duplicado o complejidad ciclomática alta) en los repositorios de TypeScript/JavaScript.

Medio

Alta

Establecer umbrales de calidad (Quality Gates) en el CI/CD y dedicar tiempo en cada sprint para resolver las advertencias de SonarQube antes de integrar código.

Cobertura de Tests End-to-End (E2E)

Dada la arquitectura de microservicios, mantener pruebas funcionales automáticas que crucen desde el frontend (webapp), pasen por el API (users) y lleguen al motor (gamey) requiere un esfuerzo continuo. Las interfaces cambian y los flujos pueden romperse.

Alto

Alta

Mantener y ampliar la cobertura de pruebas de integración y E2E utilizando Cucumber (BDD/Gherkin) y Playwright (actualmente configurados en el proyecto) para automatizar los flujos críticos de interacción del usuario en la interfaz web.

Pruebas de Carga y Rendimiento (Gatling)

Al ser un juego multijugador orquestado en contenedores, existe la deuda técnica de validar cómo se comporta el sistema bajo alta concurrencia. Actualmente el límite real de usuarios simultáneos sin degradación es desconocido.

Alto

Alta

Implementar escenarios de estrés utilizando Gatling. Se aprovechará su Recorder y su DSL basado en Scala/JVM para simular múltiples partidas concurrentes y descubrir cuellos de botella reales en la infraestructura.

Gestión básica de autenticación / Sesiones

La implementación inicial de la autenticación puede carecer de mecanismos avanzados (refresco de tokens automáticos, invalidación de sesiones al cambiar roles, etc.), limitando la escalabilidad de seguridad.

Medio

Media

Refactorizar el módulo de users para estandarizar el uso de JWT de corta duración y asegurar que los secretos solo residan en las variables de entorno (.env).

13. Glossary

Contents

The most important domain and technical terms that your stakeholders use when discussing the system.

You can also see the glossary as source for translations if you work in multi-language teams.

Motivation

You should clearly define your terms, so that all stakeholders

have an identical understanding of these terms
do not use synonyms and homonyms

Form

A table with columns <Term> and <Definition>.

Potentially more columns in case you need translations.

Further Information

See Glossary in the arc42 documentation.

Term	Definition
JSON	Formato ligero de intercambio de datos basado en texto, estructurado en pares de clave-valor y listas. Es ampliamente utilizado para la comunicación entre servicios web y se emplea en el proyecto para el intercambio de datos entre el frontend, el backend y el motor del juego.
Notación YEN	Formato especifico de mensajes JSON que permite representar la situación de una partida del juego Y en un instante de tiempo. Ejemplo de la notación: {"size": 4, "turn": "R", "players": [ "B", "R"], "layout": "B/.B/RB./B..R"}
API	Interfaz de Programación de Aplicaciones (Application Programming Interface). Conjunto de reglas y protocolos que permiten la comunicación entre diferentes componentes de software. En el proyecto, se refiere a las interfaces que permiten la interacción entre el frontend, el backend y el motor del juego.
Bots	Programas de software que realizan tareas automatizadas. En el contexto del proyecto, se refiere a los programas que pueden jugar al juego Y de manera autónoma, utilizando la API para interactuar con el motor del juego.
Microservicio REST	Arquitectura de software que divide una aplicación en pequeños servicios independientes que se comunican a través de HTTP. En el proyecto, se refiere a la estructura del backend, donde cada servicio se encarga de una funcionalidad específica y se comunica con los demás a través de la API REST.
Frontend	Parte de la aplicación con la que los usuarios interactúan directamente. En el proyecto, se refiere a la interfaz gráfica que permite a los jugadores interactuar con el juego Y, enviar comandos y recibir información sobre el estado del juego.
Backend	Parte de la aplicación que maneja la lógica de negocio, el procesamiento de datos y la comunicación con el motor del juego. En el proyecto, se refiere a los servicios que gestionan las partidas, procesan los movimientos de los jugadores y mantienen el estado del juego.
Motor del juego	Componente central del sistema que implementa las reglas del juego Y, procesa los movimientos de los jugadores y determina el estado del juego. En el proyecto, se refiere al software que ejecuta la lógica del juego y proporciona la funcionalidad necesaria para que los jugadores puedan interactuar con él a través de la API.
Unit Test	Prueba de una unidad individual.
Integration Test	Prueba entre componentes.
E2E Test	Flujo completo de usuario.
Coverage	Porcentaje cubierto por tests.
Gatling	Herramienta de carga.
YEN	Formato de persistencia del juego.
CI/CD	Integración y despliegue continuo.

Term

Definition

JSON

Formato ligero de intercambio de datos basado en texto, estructurado en pares de clave-valor y listas. Es ampliamente utilizado para la comunicación entre servicios web y se emplea en el proyecto para el intercambio de datos entre el frontend, el backend y el motor del juego.

Notación YEN

Formato especifico de mensajes JSON que permite representar la situación de una partida del juego Y en un instante de tiempo. Ejemplo de la notación: {"size": 4, "turn": "R", "players": [ "B", "R"], "layout": "B/.B/RB./B..R"}

API

Interfaz de Programación de Aplicaciones (Application Programming Interface). Conjunto de reglas y protocolos que permiten la comunicación entre diferentes componentes de software. En el proyecto, se refiere a las interfaces que permiten la interacción entre el frontend, el backend y el motor del juego.

Bots

Programas de software que realizan tareas automatizadas. En el contexto del proyecto, se refiere a los programas que pueden jugar al juego Y de manera autónoma, utilizando la API para interactuar con el motor del juego.

Microservicio REST

Arquitectura de software que divide una aplicación en pequeños servicios independientes que se comunican a través de HTTP. En el proyecto, se refiere a la estructura del backend, donde cada servicio se encarga de una funcionalidad específica y se comunica con los demás a través de la API REST.

Frontend

Parte de la aplicación con la que los usuarios interactúan directamente. En el proyecto, se refiere a la interfaz gráfica que permite a los jugadores interactuar con el juego Y, enviar comandos y recibir información sobre el estado del juego.

Backend

Parte de la aplicación que maneja la lógica de negocio, el procesamiento de datos y la comunicación con el motor del juego. En el proyecto, se refiere a los servicios que gestionan las partidas, procesan los movimientos de los jugadores y mantienen el estado del juego.

Motor del juego

Componente central del sistema que implementa las reglas del juego Y, procesa los movimientos de los jugadores y determina el estado del juego. En el proyecto, se refiere al software que ejecuta la lógica del juego y proporciona la funcionalidad necesaria para que los jugadores puedan interactuar con él a través de la API.

Unit Test

Prueba de una unidad individual.

Integration Test

Prueba entre componentes.

E2E Test

Flujo completo de usuario.

Coverage

Porcentaje cubierto por tests.

Gatling

Herramienta de carga.

YEN

Formato de persistencia del juego.

CI/CD

Integración y despliegue continuo.