Yovi en español - Equipo 1-B

About arc42

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

Template Version 8.2 EN. (based upon AsciiDoc version), Febrero 2026

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 y Objetivos

El proyecto yovi_es1b es una iniciativa llevada a cabo en la Universidad de Oviedo, dentro del marco de la asignatura de Ingeniería del Software. El propósito es desarrollar, integrar y desplegar una versión digital del juego de estrategia abstracta "Juego Y" (Game of Y).

El equipo comprometido con este desarrollo está formado por:

Diego Abeijon Rodriguez
Hugo Tejedor Arcoitza
Nahiara Sanchez Garcia
Eva Menéndez Hernández
Moisés Montes Iglesias

En la aplicación, los usuarios podrán jugar al "Juego Y" en dos modalidades principales: enfrentamiento contra otro jugador (local) o contra un Bot (IA), haciendo uso de un núcleo lógico preexistente.

1.1. Visión General de los Requisitos

La funcionalidad principal se basa en la integración de componentes y la correcta ejecución del juego.

Requisitos Funcionales Clave

Modos de Juego: Soporte para partidas Humano vs Humano y Humano vs Bot.
Integración del Núcleo: La aplicación utiliza una librería externa (Kernel) para la validación de movimientos y detección de victoria, asegurando que las reglas oficiales se cumplen estrictamente.
Interfaz de Usuario: Visualización clara del tablero triangular, permitiendo interactuar con las celdas para colocar fichas de manera intuitiva.
Despliegue y Ejecución: El sistema está configurado para iniciarse correctamente en los entornos de laboratorio, gestionando las dependencias necesarias automáticamente.
Ciclo de la Partida: Gestión completa del flujo de juego: inicio, turnos alternos, detección de fin de partida y opción de reinicio.

1.2. Objetivos de Calidad

Los objetivos de calidad se centran en la arquitectura de integración y la facilidad de puesta en marcha del software.

Prioridad	Meta de Calidad	Escenario
1	Desplegabilidad (Deployability)	El proyecto debe poder clonarse y ejecutarse en los equipos del laboratorio con una configuración mínima, evitando errores de rutas o dependencias faltantes.
2	Interoperabilidad	La interfaz gráfica debe comunicarse con el núcleo lógico (backend/kernel) sin errores de formato, respetando la API proporcionada.
3	Usabilidad	Un jugador nuevo debe poder identificar fácilmente de quién es el turno, dónde puede colocar una ficha y si ha ganado o perdido, sin consultar un manual.
4	Mantenibilidad	La arquitectura debe separar claramente el código de la vista del código de la lógica, facilitando futuras actualizaciones del núcleo o cambios en la interfaz.

Prioridad

Meta de Calidad

Escenario

Desplegabilidad (Deployability)

El proyecto debe poder clonarse y ejecutarse en los equipos del laboratorio con una configuración mínima, evitando errores de rutas o dependencias faltantes.

Interoperabilidad

La interfaz gráfica debe comunicarse con el núcleo lógico (backend/kernel) sin errores de formato, respetando la API proporcionada.

Usabilidad

Un jugador nuevo debe poder identificar fácilmente de quién es el turno, dónde puede colocar una ficha y si ha ganado o perdido, sin consultar un manual.

Mantenibilidad

La arquitectura debe separar claramente el código de la vista del código de la lógica, facilitando futuras actualizaciones del núcleo o cambios en la interfaz.

1.3. Stakeholders

Personas y roles involucrados en el desarrollo y evaluación del sistema.

Rol/Nombre	Contacto	Expectativas
Equipo de desarrollo	Diego Abeijon, Hugo Tejedor, Nahiara Sanchez, Eva Menéndez, Moisés Montes	Integrar correctamente el sistema, documentar la arquitectura (arc42) y superar la evaluación de la asignatura mediante un despliegue exitoso.
Usuarios Finales	Jugadores del Juego Y	Una experiencia de juego fluida, poder jugar contra la máquina o un amigo sin que la aplicación se cierre inesperadamente.
Evaluadores (Profesores)	Jose Emilio Labra Gayo, Pablo González, Irene Cid Rico, Diego Martín Fernández	Verificar que el despliegue es reproducible, que se respeta la arquitectura propuesta y que la documentación refleja fielmente el sistema construido.

Rol/Nombre

Contacto

Expectativas

Equipo de desarrollo

Diego Abeijon, Hugo Tejedor, Nahiara Sanchez, Eva Menéndez, Moisés Montes

Integrar correctamente el sistema, documentar la arquitectura (arc42) y superar la evaluación de la asignatura mediante un despliegue exitoso.

Usuarios Finales

Jugadores del Juego Y

Una experiencia de juego fluida, poder jugar contra la máquina o un amigo sin que la aplicación se cierre inesperadamente.

Evaluadores (Profesores)

Jose Emilio Labra Gayo, Pablo González, Irene Cid Rico, Diego Martín Fernández

Verificar que el despliegue es reproducible, que se respeta la arquitectura propuesta y que la documentación refleja fielmente el sistema construido.

2. Restricciones Arquitectónicas

En este apartado se describen los límites que condicionan las decisiones de diseño e implementación del equipo de desarrollo. Estos factores son innegociables y deben ser respatados por todo el equipo durante el desarrollo.

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.

2.1. Restricciones Técnicas

Restricción	Explicación
Multilenguaje	Obligación de usar TypeScript para la aplicación Web (Frontend/API) y Rust para el módulo de lógica de juego.
Comunicación JSON/YEN	El intercambio de datos entre los subsistemas debe realizarse exclusivamente mediante mensajes JSON, siguiendo la notación YEN.
Contenerización	El sistema debe administrarse mediante Docker, asegurando el funcionamiento en entornos aislados de ambos subsistemas (Web y Rust).
Despliegue Web	La aplicación debe ser accesible públicamente a través de una URL, es decir, debe estar desplegada en la nube.
Interfaz de servicios	El módulo Rust debe exponer una interfaz de servicio web básica para ser invocado por la aplicación principal.

Restricción

Explicación

Multilenguaje

Obligación de usar TypeScript para la aplicación Web (Frontend/API) y Rust para el módulo de lógica de juego.

Comunicación JSON/YEN

El intercambio de datos entre los subsistemas debe realizarse exclusivamente mediante mensajes JSON, siguiendo la notación YEN.

Contenerización

El sistema debe administrarse mediante Docker, asegurando el funcionamiento en entornos aislados de ambos subsistemas (Web y Rust).

Despliegue Web

La aplicación debe ser accesible públicamente a través de una URL, es decir, debe estar desplegada en la nube.

Interfaz de servicios

El módulo Rust debe exponer una interfaz de servicio web básica para ser invocado por la aplicación principal.

2.2. Restricciones Organizativas

Restricción	Explicación
Curva de aprendizaje	El equipo debe adquirir competencias en Rust, Node.js y React de forma simultánea al desarrollo, ya que son tecnologías que no han empleado con anterioridad.
Plazos	Entrega sujeta al calendario establecido por la empresa de desarrollo de juegos Micrati.
Criterios de Calidad	Es obligatorio cumplir con niveles mínimos de cobertura de pruebas (Unitarias, Integración, E2E y Carga).

Restricción

Explicación

Curva de aprendizaje

El equipo debe adquirir competencias en Rust, Node.js y React de forma simultánea al desarrollo, ya que son tecnologías que no han empleado con anterioridad.

Plazos

Entrega sujeta al calendario establecido por la empresa de desarrollo de juegos Micrati.

Criterios de Calidad

Es obligatorio cumplir con niveles mínimos de cobertura de pruebas (Unitarias, Integración, E2E y Carga).

2.3. Convenciones y Normas

Restricción	Explicación
Estándar arc42	La documentación técnica debe seguir la estructura y apartados del modelo arc42.
Notación de Coordenadas	El tablero de juego debe representarse mediante coordenadas baricéntricas (x, y, z) o índices secuenciales.
Gestión de Git	Uso obligatorio de issues, pull request con revisión de código y registro de decisiones arquitectónicas (ADR).
Observabilidad	El sistema debe incluir mecanismos de monitorización y disponibilidad.
Wiki y Gestión de Equipo	Se mantendrá una wiki en GitHub con las actas de las reuniones semanales realizadas por el equipo de desarrollo. Además, se incluirán apartados para desarrollar las decisiones tomadas y otros aspectos relevantes del desarrollo.

Restricción

Explicación

Estándar arc42

La documentación técnica debe seguir la estructura y apartados del modelo arc42.

Notación de Coordenadas

El tablero de juego debe representarse mediante coordenadas baricéntricas (x, y, z) o índices secuenciales.

Gestión de Git

Uso obligatorio de issues, pull request con revisión de código y registro de decisiones arquitectónicas (ADR).

Observabilidad

El sistema debe incluir mecanismos de monitorización y disponibilidad.

Wiki y Gestión de Equipo

Se mantendrá una wiki en GitHub con las actas de las reuniones semanales realizadas por el equipo de desarrollo. Además, se incluirán apartados para desarrollar las decisiones tomadas y otros aspectos relevantes del desarrollo.

3. Contexto y Alcance

Contents

Context and scope - as the name suggests - delimits your system (i.e. your scope) from all its communication partners (neighboring systems and users, i.e. the context of your system). It thereby specifies the external interfaces.

If necessary, differentiate the business context (domain specific inputs and outputs) from the technical context (channels, protocols, hardware).

Motivation

The domain interfaces and technical interfaces to communication partners are among your system’s most critical aspects. Make sure that you completely understand them.

Form

Various options:

Context diagrams
Lists of communication partners and their interfaces.

Further Information

See Context and Scope in the arc42 documentation.

3.1. Contexto de Negocio

El sistema YOVI es una plataforma de juegos basada en el "Juego Y" que permite la competición entre humanos y agentes automáticos (bots).

Socio de comunicación Entradas Salidas

Socio de comunicación	Entradas	Salidas
Usuario (Jugador)	Registro de cuenta, selección de variantes de juego (Classic, Master Y, etc.), elección de estrategia/dificultad y ejecución de movimientos.	Visualización del tablero, historial de participación, estadísticas de victorias/derrotas y posición en el ranking.
Bots Externos	Peticiones a través del método `play` enviando el estado del tablero en notación YEN.	Respuesta con el próximo movimiento calculado por el sistema en notación YEN.
Administrador	Configuración de parámetros del sistema y monitorización de métricas.	Información sobre disponibilidad del sistema y registros de actividad.

Usuario (Jugador)

Registro de cuenta, selección de variantes de juego (Classic, Master Y, etc.), elección de estrategia/dificultad y ejecución de movimientos.

Visualización del tablero, historial de participación, estadísticas de victorias/derrotas y posición en el ranking.

Bots Externos

Peticiones a través del método play enviando el estado del tablero en notación YEN.

Respuesta con el próximo movimiento calculado por el sistema en notación YEN.

Administrador

Configuración de parámetros del sistema y monitorización de métricas.

Información sobre disponibilidad del sistema y registros de actividad.

3.2. Contexto Técnico

La arquitectura se basa en la interoperabilidad entre un ecosistema web y un motor de lógica de alto rendimiento, comunicados mediante mensajes JSON.

Interfaz	Canal / Protocolo	Descripción
Web Frontend	HTTPS / TypeScript	Interfaz pública para usuarios humanos, con soporte para diversos tamaños de tablero.
External API	REST / JSON	API documentada para que bots externos interactúen con el sistema y accedan a datos de juego.
Game Logic Service	HTTP / JSON (YEN)	Servicio interno desarrollado en Rust que valida estados de partida y genera sugerencias de movimientos.

Interfaz

Canal / Protocolo

Descripción

Web Frontend

HTTPS / TypeScript

Interfaz pública para usuarios humanos, con soporte para diversos tamaños de tablero.

External API

REST / JSON

API documentada para que bots externos interactúen con el sistema y accedan a datos de juego.

Game Logic Service

HTTP / JSON (YEN)

Servicio interno desarrollado en Rust que valida estados de partida y genera sugerencias de movimientos.

Mapeo de Entradas/Salidas: * Gestión de Juego: El frontend TypeScript delega la verificación de victorias y la generación de jugadas de la máquina al módulo Rust. * Notación YEN: Todos los componentes técnicos utilizan el formato JSON YEN para representar el layout del tablero y el estado de los players.

4. Estrategia de Solución

4.1. Introducción

El proyecto yovi_es1b ha sido diseñado empleando una arquitectura modular y distribuida, en el que tenemos diferenciado la UI o interfaz de usuario, la lógica de negocio y el motor del juego, además de una aplicación web. Esta separación, va a permitir un desarrollo incremental, facilitando mantenimiento y escalabilidad del sistema. Las decisiones se han tomado teniendo en cuenta los objetivos de calidad que se mencionarán más adelante.

4.2. Decisiones arquitectónicas claves

Descomposición de alto nivel

Webapp: Aplicación frontend
Users Service: Servicio backend para gestión de usuarios
GameY: Motor de juego y servicio de bots implementado en Rust Esta separación de responsabilidades reduce el acoplamiento, mejora mantenibilidad, y permite escalar o sustituir componentes sin que genere problemas en otras partes del sistema.

Decisiones tecnológicas

Frontend: React + Vite + TypeScript. Utilizados ya que son un buen soporte de herramientas y permite interfaces interactivas y fáciles de mantener
Backend: Node.js + Express. Son simples y útiles para APIs REST sencillas
Motor de juego: Rust + Cargo. Buen rendimiento, muy seguro y una buena gestión de concurrencia. Estas son características importantes para un motor de juego.
Uso de contenedores: Docker y Docker Compose. Simplifican instalación, ejecución y pruebas del sistema

Decisiones relacionadas con atributos de calidad

Mantenibilidad: Empleamos código separado en módulos, separación de responsabilidades y uso de pruebas automáticas
Escalabilidad: Nuestros servicios se pueden ir actualizando y mejorando de forma independiente
Portabilidad: El uso de Docker, nos permite ejecutar el sistema en varios entornos
Calidad del código: SonarCloud y CodeScene ayudan a mantener el código limpio, seguro y fácil de mantener, asegurando que sigan estándares de calidad. Son herramientas que se utilizan para vigilar el código de forma automática mientras se desarrolla.

Decisiones organizativas

Utilizamos GitHub como flujo de trabajo, que nos permite integrar de forma continua los nuevos cambios que hemos realizado y un despliegue automático
El desarrollo del proyecto es de forma incremental, trabajando desde la misma base y desde la cual, partimos cada uno con la parte que se nos sea asignada
La asignación se realiza distribuyendo el trabajo en componentes, y cada grupo formado internamente, se encarga del componente que se le asigne
Empleamos arc42, junto a AsciiDoc y PlantUML para que la documentación se genere de forma automátrica, incluyendo diagramas. Así el código y la documentación se mantienen sincronizadas, y el despliegue automático de GitHub Pages, facilita la disponibilidad y portabilidad de la documentación

Contents

A short summary and explanation of the fundamental decisions and solution strategies, that shape system architecture. It includes

technology decisions
decisions about the top-level decomposition of the system, e.g. usage of an architectural pattern or design pattern
decisions on how to achieve key quality goals
relevant organizational decisions, e.g. selecting a development process or delegating certain tasks to third parties.

Motivation

These decisions form the cornerstones for your architecture. They are the foundation for many other detailed decisions or implementation rules.

Form

Keep the explanations of such key decisions short.

Motivate what was decided and why it was decided that way, based upon problem statement, quality goals and key constraints. Refer to details in the following sections.

Further Information

See Solution Strategy in the arc42 documentation.

5. Vista de Bloques de Construcción

Content

The building block view shows the static decomposition of the system into building blocks (modules, components, subsystems, classes, interfaces, packages, libraries, frameworks, layers, partitions, tiers, functions, macros, operations, data structures, …) as well as their dependencies (relationships, associations, …)

This view is mandatory for every architecture documentation. In analogy to a house this is the floor plan.

Motivation

Maintain an overview of your source code by making its structure understandable through abstraction.

This allows you to communicate with your stakeholder on an abstract level without disclosing implementation details.

Form

The building block view is a hierarchical collection of black boxes and white boxes (see figure below) and their descriptions.

Level 1 is the white box description of the overall system together with black box descriptions of all contained building blocks.

Level 2 zooms into some building blocks of level 1. Thus it contains the white box description of selected building blocks of level 1, together with black box descriptions of their internal building blocks.

Level 3 zooms into selected building blocks of level 2, and so on.

Further Information

See Building Block View in the arc42 documentation.

5.1. Caja Blanca del Sistema General

Here you describe the decomposition of the overall system using the following white box template. It contains

an overview diagram
a motivation for the decomposition
black box descriptions of the contained building blocks. For these we offer you alternatives:
- use one table for a short and pragmatic overview of all contained building blocks and their interfaces
- use a list of black box descriptions of the building blocks according to the black box template (see below). Depending on your choice of tool this list could be sub-chapters (in text files), sub-pages (in a Wiki) or nested elements (in a modeling tool).
(optional:) important interfaces, that are not explained in the black box templates of a building block, but are very important for understanding the white box. Since there are so many ways to specify interfaces why do not provide a specific template for them. In the worst case you have to specify and describe syntax, semantics, protocols, error handling, restrictions, versions, qualities, necessary compatibilities and many things more. In the best case you will get away with examples or simple signatures.

Motivation: La aplicación YGame permite jugar al juego de conexión Y online contra distintos bots con diferentes niveles de dificultad. Gestiona el registro y autenticación de usuarios, guarda el historial de partidas y ofrece una interfaz web accesible desde el navegador.
Bloques de Construcción de Contenidos

Nombre	Descripción
Usuario	Usuario de la aplicación que interactúa con ella a través del navegador web.
Webapp	Interfaz gráfica SPA (Single Page Application) construida con React, Vite y TypeScript. Gestiona las pantallas de inicio, registro, login y partida. Renderiza el tablero triangular en formato YEN, controla el temporizador de turno y se comunica con el backend mediante llamadas REST.
Users	Servicio backend construido con Node.js y Express. Gestiona el registro y autenticación de usuarios, el historial de partidas y actúa de intermediario entre la webapp y el motor de juego Gamey. Expone métricas para Prometheus.
Gamey	Motor de juego implementado en Rust. Implementa la lógica completa del juego Y sobre un tablero triangular con coordenadas trilineales (x,y,z). Expone una API REST para gestionar partidas y ofrece tres niveles de bot: RandomBot (fácil), BlockerBot (medio) y ProBot (difícil).
MongoDB	Base de datos NoSQL que almacena los usuarios registrados y el historial de partidas, utilizada tanto por el servicio Users como por Gamey.
Prometheus	Sistema de monitorización que recolecta métricas del servicio Users.
Grafana	Plataforma de visualización que muestra los dashboards con las métricas recogidas por Prometheus.

Nombre

Descripción

Usuario

Usuario de la aplicación que interactúa con ella a través del navegador web.

Webapp

Interfaz gráfica SPA (Single Page Application) construida con React, Vite y TypeScript. Gestiona las pantallas de inicio, registro, login y partida. Renderiza el tablero triangular en formato YEN, controla el temporizador de turno y se comunica con el backend mediante llamadas REST.

Users

Servicio backend construido con Node.js y Express. Gestiona el registro y autenticación de usuarios, el historial de partidas y actúa de intermediario entre la webapp y el motor de juego Gamey. Expone métricas para Prometheus.

Gamey

Motor de juego implementado en Rust. Implementa la lógica completa del juego Y sobre un tablero triangular con coordenadas trilineales (x,y,z). Expone una API REST para gestionar partidas y ofrece tres niveles de bot: RandomBot (fácil), BlockerBot (medio) y ProBot (difícil).

MongoDB

Base de datos NoSQL que almacena los usuarios registrados y el historial de partidas, utilizada tanto por el servicio Users como por Gamey.

Prometheus

Sistema de monitorización que recolecta métricas del servicio Users.

Grafana

Plataforma de visualización que muestra los dashboards con las métricas recogidas por Prometheus.

Important Interfaces

Interfaz Entre Descripción

Interfaz	Entre	Descripción
REST `/reset`	Webapp → Users	Inicia o reinicia una partida con el tamaño de tablero y dificultad seleccionados. Devuelve el estado inicial del tablero en formato YEN.
REST `/move`	Webapp → Users	Envía el índice de celda elegida por el jugador. El servicio lo reenvía a Gamey, que responde con el nuevo estado del tablero tras el movimiento del jugador y la respuesta del bot.
REST `/surrender`	Webapp → Users	Registra la rendición del jugador y actualiza el historial de partidas en MongoDB.
REST `/history`	Webapp → Users	Consulta el historial de partidas del usuario autenticado almacenado en MongoDB.
REST `/difficulties`	Webapp → Users	Devuelve la lista de dificultades disponibles (Easy, Medium, Hard).
REST `/play`	Users → Gamey	Reenvía los movimientos al motor de juego Rust, que ejecuta la lógica del tablero y devuelve el nuevo estado YEN junto con el resultado (ganador o partida en curso).

REST /reset

Webapp → Users

Inicia o reinicia una partida con el tamaño de tablero y dificultad seleccionados. Devuelve el estado inicial del tablero en formato YEN.

REST /move

Webapp → Users

Envía el índice de celda elegida por el jugador. El servicio lo reenvía a Gamey, que responde con el nuevo estado del tablero tras el movimiento del jugador y la respuesta del bot.

REST /surrender

Webapp → Users

Registra la rendición del jugador y actualiza el historial de partidas en MongoDB.

REST /history

Webapp → Users

Consulta el historial de partidas del usuario autenticado almacenado en MongoDB.

REST /difficulties

Webapp → Users

Devuelve la lista de dificultades disponibles (Easy, Medium, Hard).

REST /play

Users → Gamey

Reenvía los movimientos al motor de juego Rust, que ejecuta la lógica del tablero y devuelve el nuevo estado YEN junto con el resultado (ganador o partida en curso).

Insert your explanations of black boxes from level 1:

If you use tabular form you will only describe your black boxes with name and responsibility according to the following schema:

Name	Responsibility
<black box 1>	<Text>
<black box 2>	<Text>

Name

Responsibility

<black box 1>

<Text>

<black box 2>

<Text>

If you use a list of black box descriptions then you fill in a separate black box template for every important building block. Its headline is the name of the black box.

5.1.1. Webapp

Here you describe <black box 1> according the the following black box template:

Purpose/Responsibility
Interface(s), when they are not extracted as separate paragraphs. This interfaces may include qualities and performance characteristics.
(Optional) Quality-/Performance characteristics of the black box, e.g.availability, run time behavior, ….
(Optional) directory/file location
(Optional) Fulfilled requirements (if you need traceability to requirements).
(Optional) Open issues/problems/risks

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.

Interface(s): Se comunica exclusivamente con el servicio Users mediante peticiones HTTP REST. No accede directamente a Gamey ni a MongoDB.

Quality/Performance Characteristics: Aplicación SPA que no requiere recarga de página. El temporizador de turno opera en cliente con intervalos de 1 segundo.

Directory/File Location: webapp/src/

5.1.2. Users

Purpose/Responsibility: Gestionar la autenticación y registro de usuarios, el historial de partidas y actuar como API Gateway entre la webapp y el motor de juego Gamey.

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

Quality/Performance Characteristics: Expone métricas en formato Prometheus para monitorización en tiempo real mediante Grafana.

Directory/File Location: users/

5.1.3. Gamey

Purpose/Responsibility: Ejecutar toda la lógica del juego Y: validar movimientos, detectar la condición de victoria (conexión de los tres lados del triángulo), gestionar el estado del tablero en formato YEN y calcular las respuestas de los bots.

Interface(s): Expone una API REST en el puerto 3000 (mapeado al 4000 en Docker). Recibe y devuelve el estado del tablero en formato YEN (JSON).

Quality/Performance Characteristics: Implementado en Rust para máximo rendimiento en el cálculo de movimientos del ProBot, que usa BFS con potencial exponencial.

Directory/File Location: gamey/src/

5.2. Nivel 2

Here you can specify the inner structure of (some) building blocks from level 1 as white boxes.

You have to decide which building blocks of your system are important enough to justify such a detailed description. Please prefer relevance over completeness. Specify important, surprising, risky, complex or volatile building blocks. Leave out normal, simple, boring or standardized parts of your system

5.2.1. White Box Webapp

…describes the internal structure of building block 1.

La webapp está organizada en pantallas independientes gestionadas por un router interno en App.tsx:

Componente Descripción

Componente	Descripción
`HomeScreen`	Pantalla inicial con acceso a registro e inicio de sesión.
`RegisterScreen`	Formulario de registro de nuevos usuarios.
`LoginScreen`	Formulario de autenticación de usuarios existentes.
`GameScreen`	Pantalla principal de juego. Renderiza el tablero triangular YEN, muestra el temporizador de turno con barra de progreso, y gestiona las acciones de reiniciar, rendirse, cambiar dificultad/tamaño y consultar historial.
`App.tsx`	Componente raíz. Contiene toda la lógica de estado: gestión de turnos, temporizador automático (60s/30s/15s según dificultad), comunicación con el backend y navegación entre pantallas.

HomeScreen

Pantalla inicial con acceso a registro e inicio de sesión.

RegisterScreen

Formulario de registro de nuevos usuarios.

LoginScreen

Formulario de autenticación de usuarios existentes.

GameScreen

Pantalla principal de juego. Renderiza el tablero triangular YEN, muestra el temporizador de turno con barra de progreso, y gestiona las acciones de reiniciar, rendirse, cambiar dificultad/tamaño y consultar historial.

App.tsx

Componente raíz. Contiene toda la lógica de estado: gestión de turnos, temporizador automático (60s/30s/15s según dificultad), comunicación con el backend y navegación entre pantallas.

5.2.2. White Box Gamey

…describes the internal structure of building block 2.

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

Módulo Descripción

Módulo	Descripción
`core/game.rs`	Estado principal de la partida (`GameY`). Gestiona el tablero, el turno actual, el historial de movimientos y la condición de victoria.
`core/topology/`	Implementación de la topología triangular. Pre-calcula vecinos y regiones para cada celda usando coordenadas trilineales (x+y+z = size-1).
`core/coord.rs`	Sistema de coordenadas trilineales con conversión a/desde índice lineal.
`bot/random.rs`	Bot fácil: elige una celda vacía aleatoriamente.
`bot/blocker_bot.rs`	Bot medio: prioriza bloquear los movimientos del oponente.
`bot/pro_bot.rs`	Bot difícil: usa BFS para calcular distancias a los tres lados y puntúa cada celda con potencial exponencial, bonificación de centralidad y conectividad.
`notation/yen.rs`	Serialización/deserialización del formato YEN (JSON con layout triangular separado por `/`).
`bot_server/`	Servidor HTTP Axum que expone la API REST del motor de juego.

core/game.rs

Estado principal de la partida (GameY). Gestiona el tablero, el turno actual, el historial de movimientos y la condición de victoria.

core/topology/

Implementación de la topología triangular. Pre-calcula vecinos y regiones para cada celda usando coordenadas trilineales (x+y+z = size-1).

core/coord.rs

Sistema de coordenadas trilineales con conversión a/desde índice lineal.

bot/random.rs

Bot fácil: elige una celda vacía aleatoriamente.

bot/blocker_bot.rs

Bot medio: prioriza bloquear los movimientos del oponente.

bot/pro_bot.rs

Bot difícil: usa BFS para calcular distancias a los tres lados y puntúa cada celda con potencial exponencial, bonificación de centralidad y conectividad.

notation/yen.rs

Serialización/deserialización del formato YEN (JSON con layout triangular separado por /).

bot_server/

Servidor HTTP Axum que expone la API REST del motor de juego.

5.2.3. White Box Users

…describes the internal structure of building block 3.

Módulo Descripción

Módulo	Descripción
`users-service.js`	Servicio principal Express. Define los endpoints REST, gestiona la conexión a MongoDB y reenvía las peticiones de juego a Gamey.
`models/user.js`	Modelo Mongoose para usuarios y historial de partidas.
`monitoring/prometheus`	Configuración de Prometheus para recolección de métricas.
`monitoring/grafana`	Dashboards de Grafana para visualización de métricas.

users-service.js

Servicio principal Express. Define los endpoints REST, gestiona la conexión a MongoDB y reenvía las peticiones de juego a Gamey.

models/user.js

Modelo Mongoose para usuarios y historial de partidas.

monitoring/prometheus

Configuración de Prometheus para recolección de métricas.

monitoring/grafana

Dashboards de Grafana para visualización de métricas.

5.3. Nivel 3

Here you can specify the inner structure of (some) building blocks from level 2 as white boxes.

When you need more detailed levels of your architecture please copy this part of arc42 for additional levels.

5.3.1. White Box ProBot (bot/pro_bot.rs)

Specifies the internal structure of building block x.1.

El ProBot implementa la estrategia más avanzada en varias fases:

Fase Descripción

Fase	Descripción
Cálculo de distancias	Para cada jugador ejecuta BFS desde cada uno de los tres lados del tablero, calculando el coste mínimo de conexión. Pasar por una celda propia cuesta 0, por una vacía cuesta 1 y por una del oponente cuesta 2.
Potencial exponencial	Convierte distancias en puntuación con la fórmula `1000 / (d⁴ + 1)`, haciendo que la urgencia crezca exponencialmente al acercarse a un lado.
Puntuación final	Combina: potencial del oponente (×15) + potencial propio (×1) + bonificación de centralidad + bonificación de conectividad (+15 si conecta ≥2 fichas propias) + bloqueo crítico (+1000 si bloquea ≥2 fichas del oponente).
Selección	Elige la celda vacía con mayor puntuación total.

Cálculo de distancias

Para cada jugador ejecuta BFS desde cada uno de los tres lados del tablero, calculando el coste mínimo de conexión. Pasar por una celda propia cuesta 0, por una vacía cuesta 1 y por una del oponente cuesta 2.

Potencial exponencial

Convierte distancias en puntuación con la fórmula 1000 / (d⁴ + 1), haciendo que la urgencia crezca exponencialmente al acercarse a un lado.

Puntuación final

Combina: potencial del oponente (×15) + potencial propio (×1) + bonificación de centralidad + bonificación de conectividad (+15 si conecta ≥2 fichas propias) + bloqueo crítico (+1000 si bloquea ≥2 fichas del oponente).

Selección

Elige la celda vacía con mayor puntuación total.

5.3.2. White Box Topología Triangular (core/topology/)

Specifies the internal structure of building block x.2.

Elemento Descripción

Elemento	Descripción
`TriangularTopology`	Pre-calcula en construcción la lista de adyacencia y las regiones (lados A, B, C) de cada celda para acceso O(1) durante el juego.
Coordenadas trilineales	Cada celda se identifica por (x,y,z) donde x+y+z = size-1. Los tres lados del triángulo corresponden a x=0, y=0 y z=0 respectivamente.
`GameEngine`	Motor genérico parametrizado con la topología. Gestiona el estado de las celdas y detecta la victoria mediante Union-Find sobre los tres lados.

TriangularTopology

Pre-calcula en construcción la lista de adyacencia y las regiones (lados A, B, C) de cada celda para acceso O(1) durante el juego.

Coordenadas trilineales

Cada celda se identifica por (x,y,z) donde x+y+z = size-1. Los tres lados del triángulo corresponden a x=0, y=0 y z=0 respectivamente.

GameEngine

Motor genérico parametrizado con la topología. Gestiona el estado de las celdas y detecta la victoria mediante Union-Find sobre los tres lados.

5.3.3. White Box Temporizador de turno (App.tsx)

Specifies the internal structure of building block y.1.

Elemento Descripción

Elemento	Descripción
`TURN_TIME_LIMIT`	Constante que define el límite en segundos por dificultad: Easy=60s, Medium=30s, Hard=15s.
`startTurnTimer()`	Arranca un intervalo de 1 segundo que decrementa `turnTimeLeft`. Al llegar a 0 llama a `triggerAutoMove()`.
`stopTurnTimer()`	Detiene el intervalo activo y resetea `turnTimeLeft` a null. Se invoca al hacer clic en una celda, rendirse, salir o terminar la partida.
`triggerAutoMove()`	Selecciona una celda vacía aleatoria del layout actual y ejecuta la misma lógica que `handleCellClick()`, usando refs para evitar problemas de stale closure con el estado de React.

TURN_TIME_LIMIT

Constante que define el límite en segundos por dificultad: Easy=60s, Medium=30s, Hard=15s.

startTurnTimer()

Arranca un intervalo de 1 segundo que decrementa turnTimeLeft. Al llegar a 0 llama a triggerAutoMove().

stopTurnTimer()

Detiene el intervalo activo y resetea turnTimeLeft a null. Se invoca al hacer clic en una celda, rendirse, salir o terminar la partida.

triggerAutoMove()

Selecciona una celda vacía aleatoria del layout actual y ejecuta la misma lógica que handleCellClick(), usando refs para evitar problemas de stale closure con el estado de React.

6. Vista de Ejecución

6.1. Escenario de Registro de Usuario

This scenario describes how a new user registers in the application. The Webapp captures the data and communicates with the Users Service to store the information.

Notably: The separation between the frontend (Webapp) and the backend (Users Service) allows the logic to be decoupled.
API Usage: The Users Service exposes a REST API on port 3000.

6.2. Escenario de Inicialización de Partida

El motor de Rust ahora mantiene un estado persistente durante la partida. Este escenario es crucial porque es donde el servidor "elige" su personalidad.

Consistencia: Una vez elegida la dificultad, el bot asignado no cambia hasta que se reinicie el tablero.
Estado compartido: Se utiliza un AppState con Arc<Mutex<String>> para recordar el bot activo.

6.3. Escenario de Turno de Juego y Persistencia

Este escenario ilustra el ciclo de vida de un movimiento. El motor de Rust no solo calcula la respuesta, sino que detecta el final de la partida y persiste el resultado.

Inteligencia: El motor delega la jugada al bot guardado en el active_bot.
Persistencia: Al detectar un ganador, el servicio de Rust se comunica directamente con MongoDB.

7. Vista de despliegue

Content

The deployment view describes:

technical infrastructure used to execute your system, with infrastructure elements like geographical locations, environments, computers, processors, channels and net topologies as well as other infrastructure elements and
mapping of (software) building blocks to that infrastructure elements.

Often systems are executed in different environments, e.g. development environment, test environment, production environment. In such cases you should document all relevant environments.

Especially document a deployment view if your software is executed as distributed system with more than one computer, processor, server or container or when you design and construct your own hardware processors and chips.

From a software perspective it is sufficient to capture only those elements of an infrastructure that are needed to show a deployment of your building blocks. Hardware architects can go beyond that and describe an infrastructure to any level of detail they need to capture.

Motivation

Software does not run without hardware. This underlying infrastructure can and will influence a system and/or some cross-cutting concepts. Therefore, there is a need to know the infrastructure.

Form

Maybe a highest level deployment diagram is already contained in section 3.2. as technical context with your own infrastructure as ONE black box. In this section one can zoom into this black box using additional deployment diagrams:

UML offers deployment diagrams to express that view. Use it, probably with nested diagrams, when your infrastructure is more complex.
When your (hardware) stakeholders prefer other kinds of diagrams rather than a deployment diagram, let them use any kind that is able to show nodes and channels of the infrastructure.

Further Information

See Deployment View in the arc42 documentation.

7.1. Infraestructura de Nivel 1

Describe (usually in a combination of diagrams, tables, and text):

distribution of a system to multiple locations, environments, computers, processors, .., as well as physical connections between them
important justifications or motivations for this deployment structure
quality and/or performance features of this infrastructure
mapping of software artifacts to elements of this infrastructure

For multiple environments or alternative deployments please copy and adapt this section of arc42 for all relevant environments.

En este apartado se describe la infraestructura global de YOVI, destacando el uso de contenedores para gestionar la heterogeneidad tecnológica del proyecto (Node.js y Rust) y la persistencia de datos.

Motivación

La infraestructura se basa en la contenerización con Docker para resolver la necesidad de ejecutar dos entornos distintos (Node.js y Rust). El despliegue en la nube garantiza que la aplicación sea accesible publicamente, cumpliendo con el requisito de disponibilidad para usuarios y bots externos. Así, una parte se encarga de la web y los usuarios (Node.js) y otra exclusivamente de las reglas del juego (Rust).

Características de Calidad y Rendimiento

Rapidez: Al tener la lógica del juego en Rust, las jugadas se calculan de manera casi inmediata.
Fiabilidad: Como se usan contenedores, el sistema funcionará igual de bien en los ordenadores donde se desarrolla que en los del servidor final.
Seguridad: Los datos viajan protegidos por internet para mantener las partidas privadas.

Mapeo de piezas a la infraestructura

¿Qué se ha programado?	¿Dónde se ejecuta?
La interfaz Web	En el ordenador o móvil donde la persona juega.
La API y gestión de usuarios	En el contenedor principal del servidor.
Las reglas y estrategias del juego	En el contenedor principal de Rust.
El historial de partidas	En el servidor de base de datos.

¿Qué se ha programado?

¿Dónde se ejecuta?

La interfaz Web

En el ordenador o móvil donde la persona juega.

La API y gestión de usuarios

En el contenedor principal del servidor.

Las reglas y estrategias del juego

En el contenedor principal de Rust.

El historial de partidas

En el servidor de base de datos.

7.2. Infraestructura de Nivel 2

Here you can include the internal structure of (some) infrastructure elements from level 1.

Please copy the structure from level 1 for each selected element.

7.2.1. Servidor en la Nube (Docker Host)

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

7.2.2. Cliente

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.

7.2.3. Base de Datos (Persistencia)

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 un motor de base de datos MongoDB que organiza la información en colecciones independientes: los perfiles de usuario (gestionados por Node.js) y el historial de juegos (registrado por Rust). Mediante un volumen persistente de Docker, los datos se sincronizan directamente con el disco duro del servidor. Esto garantiza que, aunque el contenedor de la base de datos se detenga o se actualice, la información de las partidas y las cuentas de usuario permanezca segura y disponible, funcionando como un almacenamiento externo permanente.

8. 8. Conceptos transversales

8.1. 8.1. Gestión de Proyecto

8.1.1. Metodología de desarrollo

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.

8.1.2. Tareas y prioridades

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.

8.2. 8.2. Arquitectura y patrones de diseño

8.2.1. Arquitectura de Microservicios

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:

Escalabilidad: Permite escalar componentes individuales según la demanda.
Mantenibilidad: Facilita la comprensión, el desarrollo y el despliegue independiente de cada servicio.
Flexibilidad Tecnológica: Posibilita el uso de diferentes tecnologías o lenguajes para cada servicio si fuera necesario.

8.3. 8.3. Entorno de Desarrollo y Despliegue

8.3.1. Contenerización con Docker

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.

8.4. 8.4. Calidad y Automatización

8.4.1. Integración Continua y Calidad de Código (CI/CQ)

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

GitHub Actions: Se utilizan flujos de trabajo automatizados para ejecutar pruebas y verificar la integridad del código en cada push o pull request.
SonarQube / SonarCloud: Se integra el análisis estático de código para detectar bugs, vulnerabilidades de seguridad y deuda técnica de manera temprana.

9. Decisiones de Arquitectura

9.1. Lenguaje de programación

9.1.1. Contexto

Necesitamos un motor de juego con buen rendimiento y seguridad de memoria, y al mismo tiempo una capa web para interacción rápida y desarrollo de interfaz.

9.1.2. Decisión

Usar Rust para el motor del juego (gamey) y JavaScript/TypeScript (Node.js) para el servicio users y TypeScript + React para el frontend (Vite).

9.1.3. Consecuencias

Beneficios:

Alto rendimiento y seguridad en el motor (Rust): evita problemas de memoria y mejora la latencia.
Desarrollo rápido y ecosistema web (Node/React/TypeScript): facilita iteración en frontend y servicios HTTP.
Interoperabilidad clara: API REST expuestos por cada servicio.

Desventajas:

Curva de aprendizaje y complejidad operativa por el stack poliglota (Rust + Node + TS).
Mayor complejidad en CI/build (compilar Rust y bundles JS) y en la orquestación.
Desconocimiento por parte del equipo del lenguaje Rust.

9.2. Base de datos

9.2.1. Contexto

Se requiere persistencia para usuarios y registros de partidas; se valora flexibilidad de esquema y facilidad de integración con Node.js.

9.2.2. Decisión

Usar MongoDB como base de datos principal; users usa Mongoose y el servicio Rust puede escribir registros de partidas en Mongo cuando corresponda.

9.2.3. Consecuencias

Beneficios:

Esquema flexible para usuarios y partidas, lo que facilita evolucionar el modelo de datos.
Integración sencilla con Node.js (Mongoose) y despliegue con Docker.

Desventajas:

No es relacional por diseño: operaciones transaccionales complejas requieren atención o soluciones adicionales.
Riesgos de diseño incorrecto de índices y consultas (posibles problemas de rendimiento si no se indexa adecuadamente).
Desconocimiento por parte del equipo de MongoDB.

9.3. Frontend (React)

9.3.1. Contexto

Necesitamos una SPA con navegación por pantallas y una experiencia interactiva fluida para el juego.

9.3.2. Decisión

Usar React + TypeScript con Vite como bundler y desarrollo local.

9.3.3. Consecuencias

Beneficios:

Desarrollo rápido de UIs reusables y tipadas.
Ecosistema amplio (testing, linters, herramientas) y buen soporte para Vite.

Desventajas:

Dependencia de tooling (Vite, ESLint, etc.) y necesidad de mantener configuración.

9.4. Microservicios

9.4.1. Contexto

Queremos separar responsabilidades (UI, gestión de usuarios, motor del juego) y facilitar despliegues independientes.

9.4.2. Decisión

Arquitectura de microservicios ligeros: webapp, users, gamey (Rust). Comunicación mediante HTTP/REST; orquestación con docker-compose en desarrollo.

9.4.3. Consecuencias

Beneficios:

Despliegue y escalado independientes por componente.
Claridad en responsabilidades y menor acoplamiento lógico.

Desventajas:

Mayor complejidad en integración, testing e implementación CI/CD.
Latencia de red entre servicios y necesidad de gestionar variables de entorno y descubrimiento.

9.5. Docker

9.5.1. Contexto

Necesitamos reproducibilidad en entornos de desarrollo y despliegue local sencillo.

9.5.2. Decisión

Usar Docker y docker-compose para orquestar los servicios en desarrollo.

9.5.3. Consecuencias

Beneficios:

Entornos reproducibles y aislamientos por servicio.
Facilita pruebas locales.

Desventajas:

Consumo de recursos en máquinas locales.

9.6. LLMs empleados

9.6.1. Contexto

Valoramos la posibilidad de usar modelos de lenguaje para IA, pero no es un requisito actual.

9.6.2. Decisión

No integrar LLMs; las IAs del juego son bots heurísticos implementados en gamey.

9.6.3. Consecuencias

Beneficios:

Arquitectura más simple y sin dependencias a servicios de LLM.

Desventajas:

Menor capacidad para comportamientos avanzados sin diseñar heurísticas más complejas.

9.7. Plantilla Arc42

9.7.1. Contexto

Necesitamos una estructura clara para la documentación arquitectónica que sea comprensible por el equipo y terceros.

9.7.2. Decisión

Adoptar la plantilla arc42 para organizar la documentación (carpeta docs/).

9.7.3. Consecuencias

Beneficios:

Estructura estándar y reconocible para documentar decisiones, vistas y riesgos.

Desventajas:

Trabajo adicional para mantener documentación al día.

9.8. Observabilidad / Monitoring

9.8.1. Contexto

Se requiere visibilidad mínima del comportamiento del servicio (métricas de disponibilidad y latencia).

9.8.2. Decisión

Exponer métricas desde users con express-prom-bundle (Prometheus) y provisionar dashboards de Grafana (configuración en users/monitoring).

9.8.3. Consecuencias

Beneficios:

Métricas simples disponibles para alertas y diagnóstico.

Desventajas:

Infra adicional a desplegar y mantener (Prometheus/Grafana).

9.9. Seguridad / Autenticación

9.9.1. Contexto

Las contraseñas de usuario deben almacenarse de forma segura.

9.9.2. Decisión

Hashear contraseñas con bcryptjs en users. Actualmente no hay sessions implementados; añadir autenticación basada en tokens queda como mejora pendiente.

9.9.3. Consecuencias

Beneficios:

Contraseñas no se almacenan en texto plano; protección básica frente a fugas.

Desventajas:

Falta de mecanismo de autorización (tokens/sesiones) que limite recursos protegidos; requiere trabajo futuro.

9.10. CI / Calidad

9.10.1. Contexto

Mantener calidad del código y detectar regresiones tempranamente.

9.10.2. Decisión

Usar linting, tests locales (Vitest en servicios JS/TS) y configuración de Sonar (archivo sonar-project.properties) para facilitar análisis de calidad.

9.10.3. Consecuencias

Beneficios:

Detectar errores y antipatróns temprano; control de calidad.

Desventajas:

Requiere mantenimiento de reglas y tiempo de ejecución adicional en pipelines.

Contents

Important, expensive, large scale or risky architecture decisions including rationales. With "decisions" we mean selecting one alternative based on given criteria.

Please use your judgement to decide whether an architectural decision should be documented here in this central section or whether you better document it locally (e.g. within the white box template of one building block).

Avoid redundancy. Refer to section 4, where you already captured the most important decisions of your architecture.

Motivation

Stakeholders of your system should be able to comprehend and retrace your decisions.

Form

Various options:

ADR (Documenting Architecture Decisions) for every important decision
List or table, ordered by importance and consequences or:
more detailed in form of separate sections per decision

Further Information

See Architecture Decisions in the arc42 documentation. There you will find links and examples about ADR.

10. Requisitos de Calidad

Content

This section contains all quality requirements as quality tree with scenarios. The most important ones have already been described in section 1.2. (quality goals)

Here you can also capture quality requirements with lesser priority, which will not create high risks when they are not fully achieved.

Motivation

Since quality requirements will have a lot of influence on architectural decisions you should know for every stakeholder what is really important to them, concrete and measurable.

Further Information

See Quality Requirements in the arc42 documentation.

10.1. Árbol de calidad

Content

The quality tree (as defined in ATAM – Architecture Tradeoff Analysis Method) with quality/evaluation scenarios as leafs.

Motivation

The tree structure with priorities provides an overview for a sometimes large number of quality requirements.

Form

The quality tree is a high-level overview of the quality goals and requirements:

tree-like refinement of the term "quality". Use "quality" or "usefulness" as a root
a mind map with quality categories as main branches

In any case the tree should include links to the scenarios of the following section.

10.2. Escenarios de calidad

Contents

Concretization of (sometimes vague or implicit) quality requirements using (quality) scenarios.

These scenarios describe what should happen when a stimulus arrives at the system.

For architects, two kinds of scenarios are important:

Usage scenarios (also called application scenarios or use case scenarios) describe the system’s runtime reaction to a certain stimulus. This also includes scenarios that describe the system’s efficiency or performance. Example: The system reacts to a user’s request within one second.
Change scenarios describe a modification of the system or of its immediate environment. Example: Additional functionality is implemented or requirements for a quality attribute change.

Motivation

Scenarios make quality requirements concrete and allow to more easily measure or decide whether they are fulfilled.

Especially when you want to assess your architecture using methods like ATAM you need to describe your quality goals (from section 1.2) more precisely down to a level of scenarios that can be discussed and evaluated.

Form

Tabular or free form text.

10.2.1. Escenarios de uso

ID	Escenario	Estímulo	Respuesta esperada del sistema
SC-01	Respuesta del bot en dificultad difícil	El jugador realiza un movimiento en un tablero de tamaño 12x12x12 con el ProBot activo.	El motor Gamey calcula y devuelve el movimiento del bot en menos de 2 segundos, actualizándose el tablero en la webapp sin demora visible.
SC-02	Timeout de turno en dificultad Hard	El jugador no realiza ningún movimiento durante 15 segundos en dificultad Hard.	El sistema selecciona automáticamente una celda vacía aleatoria en nombre del jugador, y reinicia el temporizador para el siguiente turno.
SC-03	Aviso visual de tiempo agotándose	Quedan 5 segundos o menos en el temporizador de turno del jugador.	La barra de progreso cambia de azul a rojo y el contador de segundos parpadea para alertar al jugador de que debe actuar con urgencia.
SC-04	Registro de nuevo usuario	Un usuario rellena el formulario de registro con nombre y contraseña válidos.	El servicio Users crea el usuario en MongoDB y redirige automáticamente a la pantalla de juego en menos de 1 segundo.
SC-05	Consulta del historial de partidas	El jugador pulsa el botón "Historial" durante una partida.	La webapp solicita al backend el historial y muestra una tabla con fecha, rival, tamaño de tablero, dificultad y resultado de cada partida previa en menos de 2 segundos.
SC-06	Rendición del jugador	El jugador pulsa el botón "Rendirse" durante una partida en curso.	El sistema detiene el temporizador, registra la derrota en el historial de MongoDB y muestra el modal de resultado indicando "Has perdido".
SC-07	Cambio de dificultad durante la partida	El jugador cambia la dificultad de Easy a Hard desde el menú de la partida.	El sistema reinicia el tablero con la nueva dificultad, arranca el temporizador con el nuevo límite (15 segundos) y muestra el mensaje "Dificultad cambiada a Hard".
SC-08	Cambio de tamaño de tablero	El jugador selecciona un tablero de 12x12x12 desde el tamaño por defecto (6x6x6).	La webapp solicita un nuevo tablero al backend, lo renderiza correctamente con 78 celdas y reinicia el temporizador sin perder la dificultad seleccionada.
SC-09	Acceso concurrente de múltiples usuarios	Diez usuarios distintos inician sesión y juegan simultáneamente.	Cada sesión es independiente; el estado de la partida de un usuario no interfiere con el de los demás y el servicio Users responde correctamente a todas las peticiones.
SC-10	Condición de victoria	Un jugador conecta los tres lados del tablero triangular con sus fichas.	El motor Gamey detecta la victoria, detiene el juego, el temporizador se para y la webapp muestra el modal "Has ganado" o "Ha ganado el bot" según corresponda.

Escenario

Estímulo

Respuesta esperada del sistema

SC-01

Respuesta del bot en dificultad difícil

El jugador realiza un movimiento en un tablero de tamaño 12x12x12 con el ProBot activo.

El motor Gamey calcula y devuelve el movimiento del bot en menos de 2 segundos, actualizándose el tablero en la webapp sin demora visible.

SC-02

Timeout de turno en dificultad Hard

El jugador no realiza ningún movimiento durante 15 segundos en dificultad Hard.

El sistema selecciona automáticamente una celda vacía aleatoria en nombre del jugador, y reinicia el temporizador para el siguiente turno.

SC-03

Aviso visual de tiempo agotándose

Quedan 5 segundos o menos en el temporizador de turno del jugador.

La barra de progreso cambia de azul a rojo y el contador de segundos parpadea para alertar al jugador de que debe actuar con urgencia.

SC-04

Registro de nuevo usuario

Un usuario rellena el formulario de registro con nombre y contraseña válidos.

El servicio Users crea el usuario en MongoDB y redirige automáticamente a la pantalla de juego en menos de 1 segundo.

SC-05

Consulta del historial de partidas

El jugador pulsa el botón "Historial" durante una partida.

La webapp solicita al backend el historial y muestra una tabla con fecha, rival, tamaño de tablero, dificultad y resultado de cada partida previa en menos de 2 segundos.

SC-06

Rendición del jugador

El jugador pulsa el botón "Rendirse" durante una partida en curso.

El sistema detiene el temporizador, registra la derrota en el historial de MongoDB y muestra el modal de resultado indicando "Has perdido".

SC-07

Cambio de dificultad durante la partida

El jugador cambia la dificultad de Easy a Hard desde el menú de la partida.

El sistema reinicia el tablero con la nueva dificultad, arranca el temporizador con el nuevo límite (15 segundos) y muestra el mensaje "Dificultad cambiada a Hard".

SC-08

Cambio de tamaño de tablero

El jugador selecciona un tablero de 12x12x12 desde el tamaño por defecto (6x6x6).

La webapp solicita un nuevo tablero al backend, lo renderiza correctamente con 78 celdas y reinicia el temporizador sin perder la dificultad seleccionada.

SC-09

Acceso concurrente de múltiples usuarios

Diez usuarios distintos inician sesión y juegan simultáneamente.

Cada sesión es independiente; el estado de la partida de un usuario no interfiere con el de los demás y el servicio Users responde correctamente a todas las peticiones.

SC-10

Condición de victoria

Un jugador conecta los tres lados del tablero triangular con sus fichas.

El motor Gamey detecta la victoria, detiene el juego, el temporizador se para y la webapp muestra el modal "Has ganado" o "Ha ganado el bot" según corresponda.

10.2.2. Escenarios de cambio

ID Escenario Cambio Respuesta esperada del sistema

ID	Escenario	Cambio	Respuesta esperada del sistema
SC-C01	Añadir un nuevo nivel de dificultad	Se implementa un nuevo bot con dificultad "Expert" en el módulo `bot/` de Gamey.	El nuevo bot se registra en `ybot_registry.rs` y aparece automáticamente en el endpoint `/difficulties`. La webapp lo muestra en el modal de selección sin necesidad de modificar el frontend.
SC-C02	Cambio en el tiempo límite por dificultad	Se decide reducir el tiempo de Hard de 15 a 10 segundos.	Solo es necesario modificar la constante `TURN_TIME_LIMIT` en `App.tsx`. El resto del sistema (temporizador, barra de progreso, movimiento automático) se adapta automáticamente al nuevo valor.
SC-C03	Caída del servicio Gamey	El contenedor Gamey deja de responder durante una partida en curso.	El servicio Users recibe un error de red al intentar contactar con Gamey. La webapp muestra "Error realizando el movimiento" y el temporizador se reinicia para permitir al jugador intentarlo de nuevo.
SC-C04	Escalado del tamaño de tablero	Se añade soporte para un nuevo tamaño de tablero (por ejemplo 15x15x15).	Basta con añadir la opción en el modal de selección en `App.tsx` y en la función `getBoardDimensionFromSizeChoice`. El motor Gamey ya soporta cualquier tamaño gracias a su topología triangular paramétrica.
SC-C05	Migración de base de datos	Se decide cambiar de MongoDB local a MongoDB Atlas en producción.	Solo es necesario actualizar la variable de entorno `MONGODB_URI` en el `docker-co

SC-C01

Añadir un nuevo nivel de dificultad

Se implementa un nuevo bot con dificultad "Expert" en el módulo bot/ de Gamey.

El nuevo bot se registra en ybot_registry.rs y aparece automáticamente en el endpoint /difficulties. La webapp lo muestra en el modal de selección sin necesidad de modificar el frontend.

SC-C02

Cambio en el tiempo límite por dificultad

Se decide reducir el tiempo de Hard de 15 a 10 segundos.

Solo es necesario modificar la constante TURN_TIME_LIMIT en App.tsx. El resto del sistema (temporizador, barra de progreso, movimiento automático) se adapta automáticamente al nuevo valor.

SC-C03

Caída del servicio Gamey

El contenedor Gamey deja de responder durante una partida en curso.

El servicio Users recibe un error de red al intentar contactar con Gamey. La webapp muestra "Error realizando el movimiento" y el temporizador se reinicia para permitir al jugador intentarlo de nuevo.

SC-C04

Escalado del tamaño de tablero

Se añade soporte para un nuevo tamaño de tablero (por ejemplo 15x15x15).

Basta con añadir la opción en el modal de selección en App.tsx y en la función getBoardDimensionFromSizeChoice. El motor Gamey ya soporta cualquier tamaño gracias a su topología triangular paramétrica.

SC-C05

Migración de base de datos

Se decide cambiar de MongoDB local a MongoDB Atlas en producción.

Solo es necesario actualizar la variable de entorno MONGODB_URI en el `docker-co

11. Riesgos y Deudas Técnicas

Contents

Lista de riesgos y deudas técnicas identificadas, ordenadas por prioridad.

11.1. Riesgos

Riesgo	Descripción	Prioridad
Tiempo	El tiempo dedicado al proyecto es limitado debido a que el equipo de desarrollo tiene otras obligaciones laborales.	Medium
Poca experiencia en Rust y Docker	El equipo encuentra dificultades debido al conocimiento limitado del lenguaje Rust y la herramienta Docker. Para mitigarlo, se fomenta el aprendizaje activo y el intercambio de dudas.	High
Pérdida de datos	Posible pérdida de información por errores en el sistema, fallos de hardware o eliminaciones accidentales que podrían ralentizar el desarrollo del proyecto.	High
Fallos de conexión	Un fallo en la conexión a internet podría interrumpir el acceso a servidores en la nube y al repositorio de GitHub, retrasando el progreso.	Medium

Riesgo

Descripción

Prioridad

Tiempo

El tiempo dedicado al proyecto es limitado debido a que el equipo de desarrollo tiene otras obligaciones laborales.

Medium

Poca experiencia en Rust y Docker

El equipo encuentra dificultades debido al conocimiento limitado del lenguaje Rust y la herramienta Docker. Para mitigarlo, se fomenta el aprendizaje activo y el intercambio de dudas.

High

Pérdida de datos

Posible pérdida de información por errores en el sistema, fallos de hardware o eliminaciones accidentales que podrían ralentizar el desarrollo del proyecto.

High

Fallos de conexión

Un fallo en la conexión a internet podría interrumpir el acceso a servidores en la nube y al repositorio de GitHub, retrasando el progreso.

Medium

11.2. Deudas Técnicas

La deuda técnica representa el costo del retrabajo adicional causado por la elección de una solución rápida en lugar de la más efectiva a largo plazo.

Falta de tests automatizados: Se ha priorizado el desarrollo de funcionalidades sobre la cobertura de tests, lo que podría generar errores en el futuro.

12. Glosario

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
<Term-1>	<definition-1>
<Term-2>	<definition-2>

Term

Definition

<Term-1>

<definition-1>

<Term-2>

<definition-2>