yovi_es5c

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

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

La aplicación YOVI tiene como objetivo desarrollar una plataforma web que permita jugar el juego Y y poder ser utilizada tanto por personas como por bots. Es accesible desde la Web y está pensada como base para futuras ampliaciones, como nuevas variantes del juego.

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.

Implementar la versión clásica del juego Y con tamaño de tablero variable.
El juego contra el ordenador deberá de implementar más de una estrategia que el usuario podrá elegir.
Los usuarios podrán registrarse en el sistema.
Los usuarios registrados podrán consultar el histórico de sus partidas.
La aplicación tendrá una API que permita a los bots interactuar con ella.
La API permitirá que un bot juegue contra la aplicación.

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

Prioridad	Objetivos de calidad	Escenarios
1	Exactitud	El motor del juego debe validar movimientos y detectar condiciones de victoria con precisión absoluta según las reglas del juego Y.
2	Mantenibilidad	Arquitectura modular con separación clara entre los diferentes módulos. Código siguiendo principios de diseño y convenciones estándar de cada lenguaje. Documentación arquitectónica completa. Diseño extensible que facilite añadir nuevas variantes del juego sin modificar código existente.
3	Usabilidad	La aplicación debe ser intuitiva y fácil de usar para usuarios nuevos y experimentados.
4	Robustez	El sistema debe manejar correctamente errores de comunicación entre módulos web y Rust, entradas inválidas de usuarios, y situaciones excepcionales sin colapsar ni perder datos de partida.
5	Rendimiento	El sistema debe responder en menos de 4 segundos a las solicitudes de los usuarios. Tambien debe soportar al menos 50 usuarios concurrentes.
6	Seguridad	La aplicación debe cifrar los datos de los usuarios para proteger su privacidad. El sistema debe poder protegerse de ataques de seguridad como SQL injection.
7	Disponibilidad	El sistema debe mantenerse operativo y accesible para los usuarios >90% del tiempo, con interrupciones mínimas durante despliegues o actualizaciones y sin pérdida de datos de partidas activas.

Prioridad

Objetivos de calidad

Escenarios

Exactitud

El motor del juego debe validar movimientos y detectar condiciones de victoria con precisión absoluta según las reglas del juego Y.

Mantenibilidad

Arquitectura modular con separación clara entre los diferentes módulos. Código siguiendo principios de diseño y convenciones estándar de cada lenguaje. Documentación arquitectónica completa. Diseño extensible que facilite añadir nuevas variantes del juego sin modificar código existente.

Usabilidad

La aplicación debe ser intuitiva y fácil de usar para usuarios nuevos y experimentados.

Robustez

El sistema debe manejar correctamente errores de comunicación entre módulos web y Rust, entradas inválidas de usuarios, y situaciones excepcionales sin colapsar ni perder datos de partida.

Rendimiento

El sistema debe responder en menos de 4 segundos a las solicitudes de los usuarios. Tambien debe soportar al menos 50 usuarios concurrentes.

Seguridad

La aplicación debe cifrar los datos de los usuarios para proteger su privacidad. El sistema debe poder protegerse de ataques de seguridad como SQL injection.

Disponibilidad

El sistema debe mantenerse operativo y accesible para los usuarios >90% del tiempo, con interrupciones mínimas durante despliegues o actualizaciones y sin pérdida de datos de partidas activas.

1.3. Stakeholders

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.

Role/Name	Contact	Expectations
Micrati	micratiGames@example.com	Producto funcional que cumpla los requisitos del juego Y. Arquitectura modular que facilite futuras extensiones. Código mantenible y documentación clara para mantener la aplicación en el tiempo.
Jugadores/usuarios finales	(los usuarios podrán dar feedback sobre la aplicación dentro de la misma y usarán sus correos para identificarse)	Aplicación web con interfaz intuitiva para jugar al juego Y. Respuestas rápidas del sistema con actualización visual clara e inmediata tras cada movimiento. Reglas claras y feedback visual preciso del estado de la partida. Sistema estable compatible con principales navegadores. Sitio web seguro.
Profesores de la asignatura	https://github.com/Arquisoft	Aplicación correcta de principios arquitectónicos con separación de módulos y comunicación entre ellos. Documentación clara y código limpio. Trabajo colaborativo y continuo visible en GitHub. Sistema desplegado y funcional.
Desarrolladores	https://github.com/danigpt https://github.com/claudiaRFS https://github.com/josemzuvi https://github.com/uo288285 https://github.com/uo294254	Distribución equilibrada del trabajo con responsabilidades claras entre los diferentes módulos (web TypeScript y motor Rust). Flujo de trabajo colaborativo mediante GitHub con integración continua. Documentación actualizada y útil.

Role/Name

Contact

Expectations

Micrati

micratiGames@example.com

Producto funcional que cumpla los requisitos del juego Y. Arquitectura modular que facilite futuras extensiones. Código mantenible y documentación clara para mantener la aplicación en el tiempo.

Jugadores/usuarios finales

(los usuarios podrán dar feedback sobre la aplicación dentro de la misma y usarán sus correos para identificarse)

Aplicación web con interfaz intuitiva para jugar al juego Y. Respuestas rápidas del sistema con actualización visual clara e inmediata tras cada movimiento. Reglas claras y feedback visual preciso del estado de la partida. Sistema estable compatible con principales navegadores. Sitio web seguro.

Profesores de la asignatura

https://github.com/Arquisoft

Aplicación correcta de principios arquitectónicos con separación de módulos y comunicación entre ellos. Documentación clara y código limpio. Trabajo colaborativo y continuo visible en GitHub. Sistema desplegado y funcional.

Desarrolladores

https://github.com/danigpt https://github.com/claudiaRFS https://github.com/josemzuvi https://github.com/uo288285 https://github.com/uo294254

Distribución equilibrada del trabajo con responsabilidades claras entre los diferentes módulos (web TypeScript y motor Rust). Flujo de trabajo colaborativo mediante GitHub con integración continua. Documentación actualizada y útil.

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.

2.1. Restricciones Técnicas

Denominación	Descripción breve
Frontend	La aplicación web accesible para los jugadores deberá estar escrita en TypeScript
Motor del juego / Backend	El módulo que controla la lógica del juego deberá estar escrito en Rust
Comunicación entre módulos	La comunicación entre los módulos anteriormente mencionados debe realizarse mediante JSON
Formato de datos	Debe utilizarse la notación YEN de JSON
Interfaz de la lógica	El módulo Rust debe disponer de una interfaz de servicio web básica accesible por la aplicación web
Despliegue	El juego debe ser desplegado y accesible vía web
API	El módulo Rust dispondrá de una API externa que será utilizada por bots para jugar.

Denominación

Descripción breve

Frontend

La aplicación web accesible para los jugadores deberá estar escrita en TypeScript

Motor del juego / Backend

El módulo que controla la lógica del juego deberá estar escrito en Rust

Comunicación entre módulos

La comunicación entre los módulos anteriormente mencionados debe realizarse mediante JSON

Formato de datos

Debe utilizarse la notación YEN de JSON

Interfaz de la lógica

El módulo Rust debe disponer de una interfaz de servicio web básica accesible por la aplicación web

Despliegue

El juego debe ser desplegado y accesible vía web

API

El módulo Rust dispondrá de una API externa que será utilizada por bots para jugar.

2.2. Restricciones Organizativas

Denominación	Descripción breve
Equipo	El equipo de desarrollo está formado por estudiantes de la asignatura, quienes deben colaborar y gestionar el proyecto conjuntamente, repartiendo roles y trabajo.
Calendario y Plazos	El desarrollo del proyecto debe ajustarse a las fechas de entrega establecidas por los profesores.
Metodología de Trabajo	Todos los miembros del equipo han de realizar su trabajo de manera semanal e incremental respecto a versiones previas del proyecto.
Control de Versiones	Es obligatorio el uso de un sistema de control de versiones (Git) alojado en un repositorio remoto (GitHub) de acceso publico asociado a la organización (Arquisoft).

Denominación

Descripción breve

Equipo

El equipo de desarrollo está formado por estudiantes de la asignatura, quienes deben colaborar y gestionar el proyecto conjuntamente, repartiendo roles y trabajo.

Calendario y Plazos

El desarrollo del proyecto debe ajustarse a las fechas de entrega establecidas por los profesores.

Metodología de Trabajo

Todos los miembros del equipo han de realizar su trabajo de manera semanal e incremental respecto a versiones previas del proyecto.

Control de Versiones

Es obligatorio el uso de un sistema de control de versiones (Git) alojado en un repositorio remoto (GitHub) de acceso publico asociado a la organización (Arquisoft).

2.3. Convenciones del Equipo

Tipo Convención

Tipo	Convención
Idioma	La documentación y el código fuente deben seguir las pautas de idioma establecidas previamente por el equipo (Documentación en Español y Codigo en Inglés).
Gestión de ramas	Se seguirá el flujo "Git Flow" simplificado: desarrollo en `develop`, `master` solo para entregas estables, y ramas adicionales para contextos variados como `documentacion`.
Revisión de código	Ningún Pull Request se fusionará sin la aprobación de al menos otro miembro del equipo.
Consistencia de actas	Se crearan las actas sobre los temas y decisiones correspondientes a los hablados durante las reuniones siguiendo la plantilla disponible en el repositorio online(Plantilla).

Idioma

La documentación y el código fuente deben seguir las pautas de idioma establecidas previamente por el equipo (Documentación en Español y Codigo en Inglés).

Gestión de ramas

Se seguirá el flujo "Git Flow" simplificado: desarrollo en develop, master solo para entregas estables, y ramas adicionales para contextos variados como documentacion.

Revisión de código

Ningún Pull Request se fusionará sin la aprobación de al menos otro miembro del equipo.

Consistencia de actas

Se crearan las actas sobre los temas y decisiones correspondientes a los hablados durante las reuniones siguiendo la plantilla disponible en el repositorio online(Plantilla).

2.4. Restricciones Políticas y Legales

Denominación	Descripción breve
Normas académicas	El proyecto debe estar en línea con las políticas de la Universidad de Oviedo con respecto a plagio y honestidad académica.
Privacidad y Protección de Datos	Los datos de los usuarios registrados (aún siendo en un entorno de pruebas) deben ser protegidos y evitar ser expuestos, acorde a la Ley de Protección de Datos.

Denominación

Descripción breve

Normas académicas

El proyecto debe estar en línea con las políticas de la Universidad de Oviedo con respecto a plagio y honestidad académica.

Privacidad y Protección de Datos

Los datos de los usuarios registrados (aún siendo en un entorno de pruebas) deben ser protegidos y evitar ser expuestos, acorde a la Ley de Protección de Datos.

3. Contexto y alcance

3.1. Contexto de negocio

Elemento	Descripción
Jugador	Usuario humano que interactúa con el sistema YOVI a través de la aplicación web para jugar partidas del juego Y. Se autentica en el sistema y realiza movimientos dentro de partidas iniciadas a través de la aplicación. Después de hacer movimientos recibirá el resultado que eso produce en la partida.
Bot Externo	Bot automatizado que utiliza un API para conectarse a YOVI para jugar partidas sin necesidad de interacción humana directa.
YOVI	Sistema completo de juegos tipo Y. Engloba la aplicación web en TypeScript y el módulo de validación en Rust. Gestiona autenticación de usuarios, lógica de juego, validación de partidas y sugerencias de movimientos.

Elemento

Descripción

Jugador

Usuario humano que interactúa con el sistema YOVI a través de la aplicación web para jugar partidas del juego Y. Se autentica en el sistema y realiza movimientos dentro de partidas iniciadas a través de la aplicación. Después de hacer movimientos recibirá el resultado que eso produce en la partida.

Bot Externo

Bot automatizado que utiliza un API para conectarse a YOVI para jugar partidas sin necesidad de interacción humana directa.

YOVI

Sistema completo de juegos tipo Y. Engloba la aplicación web en TypeScript y el módulo de validación en Rust. Gestiona autenticación de usuarios, lógica de juego, validación de partidas y sugerencias de movimientos.

3.2. Contexto técnico

Nodo	Descripción
Jugador	Persona que accede a YOVI desde el navegador para registrarse, iniciar sesión y jugar partidas.
Aplicación web YOVI	Es la parte visible del sistema. Muestra la interfaz al jugador, coordina el flujo de partida y conecta con el resto de componentes.
Punto de acceso para bots	Entrada específica para programas automáticos. Permite que bots externos jueguen sin usar la interfaz gráfica.
Bot externo	Programa automatizado que se conecta a YOVI para enviar jugadas y recibir respuestas del sistema.
Motor de reglas del juego	Componente interno que comprueba si una jugada es válida y calcula la respuesta según las reglas de Y.
Base de datos	Almacena de forma persistente usuarios, partidas y estadísticas para poder consultarlas en cualquier momento.

Nodo

Descripción

Jugador

Persona que accede a YOVI desde el navegador para registrarse, iniciar sesión y jugar partidas.

Aplicación web YOVI

Es la parte visible del sistema. Muestra la interfaz al jugador, coordina el flujo de partida y conecta con el resto de componentes.

Punto de acceso para bots

Entrada específica para programas automáticos. Permite que bots externos jueguen sin usar la interfaz gráfica.

Bot externo

Programa automatizado que se conecta a YOVI para enviar jugadas y recibir respuestas del sistema.

Motor de reglas del juego

Componente interno que comprueba si una jugada es válida y calcula la respuesta según las reglas de Y.

Base de datos

Almacena de forma persistente usuarios, partidas y estadísticas para poder consultarlas en cualquier momento.

3.2.1. Mapeo de entradas y salidas a canales

Entrada / Salida Canal Descripción

Entrada / Salida	Canal	Descripción
Registro/login	Jugador → Aplicación web	El usuario crea cuenta e inicia sesión desde el navegador.
Consulta de histórico/estadísticas	Jugador → Aplicación web	El usuario consulta partidas jugadas, ganadas/perdidas, etc.
Jugada del usuario	Jugador → Aplicación web	El usuario realiza un movimiento desde la UI.
Play (bot)	Bot externo → Punto de acceso para bots	El bot envía `position` en notación YEN y recibe el siguiente movimiento.
Siguiente movimiento / validación	Aplicación web ↔ Motor de reglas	La app pide validar/calcular la jugada y recibe el resultado para continuar la partida.
Persistencia	Aplicación web → Base de datos	Guardar/leer usuarios, partidas y estadísticas.

Registro/login

Jugador → Aplicación web

El usuario crea cuenta e inicia sesión desde el navegador.

Consulta de histórico/estadísticas

Jugador → Aplicación web

El usuario consulta partidas jugadas, ganadas/perdidas, etc.

Jugada del usuario

Jugador → Aplicación web

El usuario realiza un movimiento desde la UI.

Play (bot)

Bot externo → Punto de acceso para bots

El bot envía position en notación YEN y recibe el siguiente movimiento.

Siguiente movimiento / validación

Aplicación web ↔ Motor de reglas

La app pide validar/calcular la jugada y recibe el resultado para continuar la partida.

Persistencia

Aplicación web → Base de datos

Guardar/leer usuarios, partidas y estadísticas.

4. Estrategia de solució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.

4.1. Decisiones tecnológicas

Backend:
- NodeJS + Express: Debido a su popularidad, facilidad de uso y amplia comunidad, lo que facilita el desarrollo rápido y la integración con otras tecnologías.
- Rust: Para el desarrollo del juego, debido a su alto rendimiento, capacidad para manejar tareas concurrentes, lo que es esencial para una experiencia de juego fluida.
Frontend:
- Vite: Por su velocidad de arranque, y hot-reload instantáneo, permitiendo un desarrollo rápido y eficiente.
- React: Por su facilidad de uso, modularidad y amplia comunidad y capacidad de crear interfaces de usuario dinámicas y responsivas.
Base de datos:
- MongoDB: Debido a su flexibilidad para manejar datos no estructurados, lo que es ideal para almacenar información de usuarios, partidas y estadísticas de juego.
Github: Lo hemos elegido como plataforma de control de versiones al estar mas familiarizados con él, y su capacidad para gestionar proyectos de software.
Docker: Por su capacidad para crear, desplegar y ejecutar aplicaciones en contenedores de manera intuituva.
Azure: Debido a que ya estabamos habituados a su uso, su accesibilidad mediante una IP pública y la facilidad de apertura de puertos.

4.2. Descomposición de alto nivel

La solución se basará en una arquitectura de servicios desacoplados, por un lado contamos con un módulo centrado en el rendimiento que gestionará la lógica del juego, escrito en Rust, e independiente a este trabajaremos con la gestión de usuarios y API en módulos TypeScript, buscando la agilidad de desarrollo web. La cohesión del sistema se hará por medio del estándar YEN sobre protocolos HTTP/JSON. Se tendrá también en cuenta la relevancia del despliegue continuo acompañado de diversos tipos de pruebas que garanticen la calidad y mantenibilidad del código.

4.3. Decisiones para alcanzar objetivos de calidad

En vistas a garantizar los atributos de calidad requeridos en cualquier sistema moderno, se toman las siguientes decisiones, asociadas a metas u objetivos específicos:

Mantenibilidad y Desacoplamiento: Se adopta una separación clara de responsabilidades mediante servicios independientes. Al utilizar JSON y la notación YEN como único contrato de comunicación, es posible modificar la interfaz web o el motor de IA de forma aislada sin afectar al otro componente, facilitando la evolución del código.
Escalabilidad y Flexibilidad de Datos: La elección de MongoDB permite una escalabilidad horizontal sencilla y una gestión de datos flexible. Esto asegura que el sistema pueda crecer en volumen de usuarios y tipos de juegos sin necesidad de complejas migraciones de esquemas que comprometan la disponibilidad del servicio.
Portabilidad y Despliegue: El uso de contenedores Docker garantiza que el sistema se comporte de manera idéntica en el entorno de desarrollo de los estudiantes, en los servidores de la universidad y en la web final, eliminando el problema de "en mi máquina funciona".
Documentación: Apostar por una documentación formalizada en Arc42, que refleje con claridad y concisión las decisiones tanto técnicas como organizativas tomadas ayudará a comprender mejor cómo ha sido el proceso de desarrollo, lo que facilita el mantenimiento y uso del proyecto a otros desarrolladores.

4.4. Deciciones organizativas relevantes

Cada tarea o incidencia se registrará como un Issue en GitHub, y se utilizará GitHub Projects para mantener organizada la gestión de las tareas. No habrá una separación estricta entre front-end y back-end, permitiendo que todos los miembros trabajen en ambas áreas. Para cada tarea se creará una rama específica y, una vez finalizada, los cambios se integrarán en la rama develop mediante pull requests. Cuando la funcionalidad esté completamente probada, se fusionará la rama develop con master, garantizando un flujo de desarrollo ordenado y controlado.

Por otro lado, se realizará mínimo una reunión semanal para revisar el avance del proyecto. Sin embargo, adicionalmente, se realizarán las reuniones que sean necesarias para resolver dudas o problemas que puedan surgir durante el desarrollo.

5. Vista de Bloques

5.1. Sistema General (Nivel 1)

Tabla 1. Bloques de construcción contenidos (Nivel 1)

Bloque	Descripción
Stakeholder: Usuario	Persona que accede a Yovi desde un navegador para registrarse y jugar partidas a través de la interfaz gráfica.
Stakeholder: Bot	Cliente externo automatizado que interactúa con el sistema mediante los endpoints expuestos en el API Gateway.
Aplicación Web	Aplicación Frontend (SPA desarrollada con React y Vite) que ofrece la interfaz de usuario. Delega toda la comunicación externa al API Gateway.
API Gateway	Punto de entrada principal del sistema (Node.js/Express). Expone la API pública, maneja límites de peticiones y enruta el tráfico hacia los servicios correspondientes.
Servicio de Usuarios	Gestiona la lógica de negocio relacionada con cuentas de usuario, validación de datos, registro, y autenticación. Interactúa con la base de datos.
Servicio de Juego (Rust)	Implementa la lógica central del juego Y. Procesa y valida los movimientos, gestiona el estado de los tableros y calcula las respuestas automatizadas.
Base de datos	Sistema de persistencia (MongoDB) utilizado por el Servicio de Usuarios para almacenar información.

Bloque

Descripción

Stakeholder: Usuario

Persona que accede a Yovi desde un navegador para registrarse y jugar partidas a través de la interfaz gráfica.

Stakeholder: Bot

Cliente externo automatizado que interactúa con el sistema mediante los endpoints expuestos en el API Gateway.

Aplicación Web

Aplicación Frontend (SPA desarrollada con React y Vite) que ofrece la interfaz de usuario. Delega toda la comunicación externa al API Gateway.

API Gateway

Punto de entrada principal del sistema (Node.js/Express). Expone la API pública, maneja límites de peticiones y enruta el tráfico hacia los servicios correspondientes.

Servicio de Usuarios

Gestiona la lógica de negocio relacionada con cuentas de usuario, validación de datos, registro, y autenticación. Interactúa con la base de datos.

Servicio de Juego (Rust)

Implementa la lógica central del juego Y. Procesa y valida los movimientos, gestiona el estado de los tableros y calcula las respuestas automatizadas.

Base de datos

Sistema de persistencia (MongoDB) utilizado por el Servicio de Usuarios para almacenar información.

5.2. Nivel 2

5.2.1. Whitebox: Aplicación Web

Tabla 2. Bloques de construcción contenidos (Aplicación Web)

Bloque Descripción

Bloque	Descripción
Enrutador (React Router)	Gestiona la navegación en el cliente (SPA) mapeando URLs a sus componentes correspondientes y protegiendo las rutas privadas (ej. redirigiendo al login si no hay sesión activa).
Vistas y Componentes (React / MUI)	Conjunto de pantallas y elementos visuales (Login, Registro, Tablero de Juego) desarrollados con React y Material-UI que presentan la interfaz e interceptan las acciones del usuario.
Gestión de Sesión (SessionContext)	Estado global de la aplicación en el navegador. Utiliza la Context API de React y el LocalStorage para mantener de forma persistente la información del usuario logueado (`username`, `isLoggedIn`, `sessionId`).
Cliente API (Axios / Fetch)	Capa de integración encargada de construir, ejecutar y gestionar las respuestas de las peticiones HTTP asíncronas dirigidas a la URL pública del API Gateway (`VITE_API_URL`).

Enrutador (React Router)

Gestiona la navegación en el cliente (SPA) mapeando URLs a sus componentes correspondientes y protegiendo las rutas privadas (ej. redirigiendo al login si no hay sesión activa).

Vistas y Componentes (React / MUI)

Conjunto de pantallas y elementos visuales (Login, Registro, Tablero de Juego) desarrollados con React y Material-UI que presentan la interfaz e interceptan las acciones del usuario.

Gestión de Sesión (SessionContext)

Estado global de la aplicación en el navegador. Utiliza la Context API de React y el LocalStorage para mantener de forma persistente la información del usuario logueado (username, isLoggedIn, sessionId).

Cliente API (Axios / Fetch)

Capa de integración encargada de construir, ejecutar y gestionar las respuestas de las peticiones HTTP asíncronas dirigidas a la URL pública del API Gateway (VITE_API_URL).

5.2.2. Whitebox: Servicio de Juego Y (Rust)

Tabla 3. Bloques de construcción contenidos (Servicio de Juego)

Bloque Descripción

Bloque	Descripción
Servidor API HTTP (Axum)	Punto de entrada de red. Funciona de manera completamente stateless (sin estado de partida). En lugar de almacenar partidas, extrae el estado del tablero que llega en el cuerpo de cada petición HTTP (`MoveRequest`) para procesarlo.
Notación y Parsing (YEN)	Capa de traducción. Deserializa el formato de texto compacto YEN recibido en JSON para construir estructuras nativas de Rust (`GameY`), y a la inversa para devolver la respuesta al cliente.
Motor de juego (Lógica)	Núcleo del sistema. En lugar de persistir, se crea una instancia efímera de `GameY` en cada petición basándose en la notación entrante. Aplica reglas, valida movimientos y verifica victorias.
Registro de bots (AppState)	El único estado global que mantiene el servidor en memoria. Gestiona y registra qué implementaciones de bots (estrategias) están cargadas y disponibles para ser utilizadas en base al parámetro enviado en la petición.
Bots	Módulo que contiene las implementaciones de los oponentes automatizados (ej. `RandomBot`). Analizan la instancia temporal del tablero y proponen unas coordenadas válidas para jugar.
Interfaz de Consola (CLI)	Aplicación de línea de comandos incluida en el binario que permite arrancar el programa y jugar localmente sin necesidad del servidor HTTP, interactuando directamente con el motor.

Servidor API HTTP (Axum)

Punto de entrada de red. Funciona de manera completamente stateless (sin estado de partida). En lugar de almacenar partidas, extrae el estado del tablero que llega en el cuerpo de cada petición HTTP (MoveRequest) para procesarlo.

Notación y Parsing (YEN)

Capa de traducción. Deserializa el formato de texto compacto YEN recibido en JSON para construir estructuras nativas de Rust (GameY), y a la inversa para devolver la respuesta al cliente.

Motor de juego (Lógica)

Núcleo del sistema. En lugar de persistir, se crea una instancia efímera de GameY en cada petición basándose en la notación entrante. Aplica reglas, valida movimientos y verifica victorias.

Registro de bots (AppState)

El único estado global que mantiene el servidor en memoria. Gestiona y registra qué implementaciones de bots (estrategias) están cargadas y disponibles para ser utilizadas en base al parámetro enviado en la petición.

Bots

Módulo que contiene las implementaciones de los oponentes automatizados (ej. RandomBot). Analizan la instancia temporal del tablero y proponen unas coordenadas válidas para jugar.

Interfaz de Consola (CLI)

Aplicación de línea de comandos incluida en el binario que permite arrancar el programa y jugar localmente sin necesidad del servidor HTTP, interactuando directamente con el motor.

5.3. Nivel 3

5.3.1. Whitebox: Core del juego

Tabla 4. Bloques de construcción contenidos (Core del juego)

Bloque Descripción

Bloque	Descripción
GameY (Motor efímero de partida)	Estructura central que funciona como una máquina de transición de estado. Su ciclo de vida en el servidor web consta de tres fases: 1) Reconstruirse a partir de una notación YEN simulando las piezas previas. 2) Aplicar un único movimiento entrante validando reglas. 3) Exportarse de nuevo a YEN y destruirse.
Topología y Coordenadas	Módulo de cálculo puro (`Coordinates`) basado en coordenadas baricéntricas `(x, y, z)`. Resuelve conversiones desde índices lineales y, crucialmente, calcula cuáles son las coordenadas adyacentes a una casilla concreta y qué bordes del tablero toca.
Movimientos y Acciones	Representación de la intención del turno actual. Define si el jugador o bot intenta colocar una pieza (`Placement`) en unas coordenadas específicas, o ejecutar una regla especial del juego (`GameAction` como `Swap` o `Resign`).
Algoritmo Union-Find (PlayerSet)	Estructura de datos y algoritmo que gestiona el grafo de conexiones. Cada vez que GameY reconstruye el tablero o añade una pieza, `PlayerSet` une las casillas del mismo color que se tocan. Comprueba de forma ultra-optimizada si un mismo conjunto ha logrado tocar los lados A, B y C simultáneamente (condición de victoria).

GameY (Motor efímero de partida)

Estructura central que funciona como una máquina de transición de estado. Su ciclo de vida en el servidor web consta de tres fases: 1) Reconstruirse a partir de una notación YEN simulando las piezas previas. 2) Aplicar un único movimiento entrante validando reglas. 3) Exportarse de nuevo a YEN y destruirse.

Topología y Coordenadas

Módulo de cálculo puro (Coordinates) basado en coordenadas baricéntricas (x, y, z). Resuelve conversiones desde índices lineales y, crucialmente, calcula cuáles son las coordenadas adyacentes a una casilla concreta y qué bordes del tablero toca.

Movimientos y Acciones

Representación de la intención del turno actual. Define si el jugador o bot intenta colocar una pieza (Placement) en unas coordenadas específicas, o ejecutar una regla especial del juego (GameAction como Swap o Resign).

Algoritmo Union-Find (PlayerSet)

Estructura de datos y algoritmo que gestiona el grafo de conexiones. Cada vez que GameY reconstruye el tablero o añade una pieza, PlayerSet une las casillas del mismo color que se tocan. Comprueba de forma ultra-optimizada si un mismo conjunto ha logrado tocar los lados A, B y C simultáneamente (condición de victoria).

6. Vista en tiempo de ejecución

Contents

The runtime view describes concrete behavior and interactions of the system’s building blocks in form of scenarios from the following areas:

important use cases or features: how do building blocks execute them?
interactions at critical external interfaces: how do building blocks cooperate with users and neighboring systems?
operation and administration: launch, start-up, stop
error and exception scenarios

Remark: The main criterion for the choice of possible scenarios (sequences, workflows) is their architectural relevance. It is not important to describe a large number of scenarios. You should rather document a representative selection.

Motivation

You should understand how (instances of) building blocks of your system perform their job and communicate at runtime. You will mainly capture scenarios in your documentation to communicate your architecture to stakeholders that are less willing or able to read and understand the static models (building block view, deployment view).

Form

There are many notations for describing scenarios, e.g.

numbered list of steps (in natural language)
activity diagrams or flow charts
sequence diagrams
BPMN or EPCs (event process chains)
state machines
…

Further Information

See Runtime View in the arc42 documentation.

6.1. Ejecución de partida jugador contra jugador

A continuación se muestra el diagrama de secuencia de una partida entre dos jugadores humanos a través de la terminal, que representa el flujo principal del sistema en su estado actual. El diagrama muestra:

El ciclo de juego: renderizado → verificación de estado → captura de entrada → procesamiento
Cómo se gestionan los turnos alternados entre jugadores hasta que finaliza la partida

6.2. Registro de un usuario

En este otro diagrama observamos el proceso de registro de un nuevo usuario en el sistema, donde participan el usuario, la API REST, el middleware de validación y la base de datos.

El proceso es el siguiente:

El nuevo usuario envía a la API por el endpoint /createuser sus datos (correo, username, contraseña…)
Los datos son validados (formato del correo, nombre de usuario, formato de la contraseña…)
Si los datos no son válidos la API devuelve un error con código HTTP 400
Si los datos son válidos se comprueba si el usuario no está ya creado en la base de datos
En este caso, se hashea la contraseña introducida por el usuario, y se guardan los datos en la BDD, devolviendo un código exitoso 200 y el JSON con los datos del usuario o token de sesión

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. Infrastructure Level 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.

Diagrama de Despliegue (resumen)

Se utiliza el diagrama de la sección "Contexto de negocio" para representar, a alto nivel, los contenedores Docker, la red interna, la base de datos y la pila de monitoreo. El diagrama muestra cómo los bloques de software (Gamey Server, Users Service, Web App, Gateway) se despliegan en contenedores separados y cómo estos consumen servicios infraestructurales (MongoDB, red Docker, Prometheus, Grafana).

Motivación

Una arquitectura basada en contenedores permite:

Aislar responsabilidades (lógica de juego, gestión de usuarios, interfaz web).
Facilitar despliegues y escalado independientes por servicio.
Simplificar integración de monitoring y gestión de logs.
Permitir replicación y orquestación en entornos distintos (desarrollo, staging, producción).

Table 1. Características de Calidad y Rendimiento
Característica	Descripción
Escalabilidad	Escalado horizontal de servicios (réplicas de Gamey y Users) para soportar picos de carga.
Alta Disponibilidad	MongoDB configurado con persistencia en volúmenes para garantizar la persistencia de datos.
Monitoreo y Diagnóstico	Uso de Prometheus para la recolección de métricas (scrape targets) y Grafana para la visualización de alertas.
Optimización de Red	Redes Docker que proporcionan aislamiento y latencias bajas entre contenedores.
Gestión de Recursos	Definición de límites de CPU/memoria y controles de estado (readiness/healthchecks) para recuperación automática.
Control de Despliegue	Gestión de dependencias declaradas (ej. `depends_on`) para asegurar un orden de inicio correcto entre servicios.

Para entornos: * Desarrollo: despliegue en un único host con contenedores o mediante npm sin replicado y datos locales. * Staging: configuración similar a producción pero con tamaños menores y datos de prueba. * Producción: orquestador con réplicas, balanceadores y políticas de actualización.

7.2. Infraestructura 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. Contenedores

Este grupo representa los servicios principales de la aplicación que se ejecutan dentro del entorno de Docker. Se dividen en tres servicios:

Puerto 4000 (Gamey): Este servicio es el núcleo de la aplicación, encargado de gestionar la lógica del juego y las interacciones entre los jugadores.
Puerto 3000 (Users): Es el encargado de la gestión de usuarios. Conexión directa a MongoDB.
Puerto 80 (WebApp): Es la interfaz de usuario de la aplicación, proporcionando acceso a través de un navegador web. Este servicio se comunica con el Gateway para acceder a los servicios de Gamey y Users.
Puerto 8000 (Gateway): Actúa como punto de entrada para las solicitudes HTTP y redirige las peticiones a los microservicios correspondientes.
Puerto 27017 (MongoDB): Es la base de datos de la aplicación. Esta interrelacionado con casi todos los conteneder ya que necesita almacenar y proveer de tanto los datos de identificación de los usuarios como de los resultados de sus partidas y sus estadísticas. Cuenta con un volumen persistente para trasladar datos en caso de ser necesario.

7.2.2. Monitoreo

Este grupo incluye los servicios relacionados con el monitoreo y la gestión de la infraestructura. Se compone de dos servicios:

Puerto 9090 (Prometheus): Responsable de recopilar métricas y datos de los otros contenedores y del entorno Docker.
Puerto 3001 (Grafana): Se utiliza para la visualización de datos conectandose a Prometheus para mostrar las métricas recopiladas en paneles gráficos.

7.2.3. Docker

Actúa como el entorno de ejecución controla la visibilidad y las listas de control de acceso (ACL) para los contenedores de aplicación y monitoreo.

8. Conceptos transversales

Content

This section describes overall, principal regulations and solution ideas that are relevant in multiple parts (= cross-cutting) of your system. Such concepts are often related to multiple building blocks. They can include many different topics, such as

models, especially domain models
architecture or design patterns
rules for using specific technology
principal, often technical decisions of an overarching (= cross-cutting) nature
implementation rules

Motivation

Concepts form the basis for conceptual integrity (consistency, homogeneity) of the architecture. Thus, they are an important contribution to achieve inner qualities of your system.

Some of these concepts cannot be assigned to individual building blocks, e.g. security or safety.

Form

The form can be varied:

concept papers with any kind of structure
cross-cutting model excerpts or scenarios using notations of the architecture views
sample implementations, especially for technical concepts
reference to typical usage of standard frameworks (e.g. using Hibernate for object/relational mapping)

Structure

A potential (but not mandatory) structure for this section could be:

Domain concepts
User Experience concepts (UX)
Safety and security concepts
Architecture and design patterns
"Under-the-hood"
development concepts
operational concepts

Note: it might be difficult to assign individual concepts to one specific topic on this list.

Possible topics for crosscutting concepts

Further Information

See Concepts in the arc42 documentation.

8.1. Modelo de dominio

Los principales conceptos de dominio son:

Usuario: jugador registrado en el sistema.
Partida: instancia de una partida en entre dos jugadores.
Movimiento: acción realizada por un jugador en una casilla válida.
Estado de partida: representación del tablero en un instante dado.
Estrategia: algoritmo utilizado por el sistema para calcular el siguiente movimiento.

El estado del juego se representa mediante la notación YEN, que permite serializar una partida en formato JSON. Esta notación es utilizada tanto en la comunicación entre servicios como en el API para bots, garantizando coherencia en todo el sistema.

8.2. Arquitectura y patrones de diseño

La arquitectura del sistema sigue una separación clara de responsabilidades entre los distintos bloques principales:

Arquitectura basada en servicios: separación entre aplicación web, servicio de usuarios y servicio de juego.
Separación por capas: diferenciación entre capa de presentación, lógica de negocio y persistencia.
Patrón Strategy: utilizado en el motor del juego para implementar distintas estrategias y niveles de dificultad.
Arquitectura cliente-servidor: el frontend actúa como cliente y los servicios backend como servidores.
Comunicación REST: intercambio de información mediante HTTP y JSON entre los distintos servicios.

Esta organización favorece la mantenibilidad, escalabilidad y testabilidad del sistema.

8.3. Persistencia de datos

La persistencia del sistema se gestiona mediante MongoDB:

Usuarios: almacenamiento de credenciales y datos de perfil.
Estadísticas: registro de partidas jugadas, ganadas y perdidas.
Historial de partidas: almacenamiento de resultados relevantes.

MongoDB utiliza un modelo orientado a documentos, lo que permite adaptarse fácilmente a cambios en la estructura de datos. La base de datos no se expone directamente al exterior y solo es accesible desde los servicios internos.

8.4. Conceptos de desarrollo

El desarrollo del sistema sigue prácticas modernas de ingeniería de software:

Integración continua: uso de GitHub Actions para ejecutar pruebas y análisis de calidad en cada Pull Request.
Control de versiones por ramas: uso de ramas master, develop y ramas de funcionalidad.
Revisión de código: todas las modificaciones se integran mediante Pull Requests revisadas por el equipo.
Testing multinivel: pruebas unitarias y de integración.
Uso de docker: uso de contenedores para asegurar entornos consistentes entre desarrollo y producción.

8.5. Seguridad

La seguridad es un aspecto transversal del sistema.

Almacenamiento seguro: las contraseñas se almacenan utilizando algoritmos seguros.
Validación de entradas: se verifican todos los datos recibidos para evitar ataques.
Control de acceso: los usuarios deben autenticarse para acceder a funcionalidades protegidas.
Protección frente a fuerza bruta: limitación de intentos de inicio de sesión.

9. Decisiones Arquitectónicas

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.

9.1. Base de Datos

Sección	Descripción
Título	Selección de MongoDB como base de datos para el juego YOVI
Contexto	Necesidad de persistencia de datos para el historial de partidas, registro de usuarios y datos internos. Se requiere una solución que soporte esquemas flexibles (tableros variables) y comunicación mediante JSON (notación YEN).
Decisión	Aceptar el uso de MongoDB. Se elige por ser una base de datos documental nativa en JSON, su compatibilidad con Docker y la familiaridad previa del equipo con esta tecnología.
Estado	Aceptado
Consecuencias	Beneficios: Optimización para JSON/YEN, flexibilidad ante cambios en el modelo de datos (tableros), alta velocidad de lectura/escritura para bots y fácil escalabilidad para futuros modos de juego. Desventajas: Gestión de transacciones ACID más compleja (riesgo de inconsistencia en estadísticas) y un elevado consumo de memoria RAM en el despliegue.

Sección

Descripción

Título

Selección de MongoDB como base de datos para el juego YOVI

Contexto

Necesidad de persistencia de datos para el historial de partidas, registro de usuarios y datos internos. Se requiere una solución que soporte esquemas flexibles (tableros variables) y comunicación mediante JSON (notación YEN).

Decisión

Aceptar el uso de MongoDB. Se elige por ser una base de datos documental nativa en JSON, su compatibilidad con Docker y la familiaridad previa del equipo con esta tecnología.

Estado

Aceptado

Consecuencias

Beneficios: Optimización para JSON/YEN, flexibilidad ante cambios en el modelo de datos (tableros), alta velocidad de lectura/escritura para bots y fácil escalabilidad para futuros modos de juego.

Desventajas: Gestión de transacciones ACID más compleja (riesgo de inconsistencia en estadísticas) y un elevado consumo de memoria RAM en el despliegue.

9.2. Estrategia de Control de Versiones

Sección	Descripción
Título	Adopción de modelo Git Flow para la gestión del repositorio en GitHub
Contexto	Necesidad de coordinar el desarrollo grupal para evitar conflictos e inconsistencias. Se requiere un flujo que permita separar el código estable del experimental y facilite el trabajo paralelo.
Decisión	Implementar una variante de Git Flow. Se utilizarán dos ramas persistentes (main para entregas estables y develop para integración) junto a ramas temporales (feature) de ciclo de vida corto para tareas específicas.
Estado	Aceptado
Consecuencias	Beneficios: Protección del entorno de producción, aislamiento de errores en ramas experimentales y facilitación del desarrollo paralelo (ej. lógica en Rust y corrección de bugs simultáneos). Desventajas: Historial menos lineal debido a múltiples bifurcaciones y mayor complejidad potencial al resolver conflictos en integraciones semanales.

Sección

Descripción

Título

Adopción de modelo Git Flow para la gestión del repositorio en GitHub

Contexto

Necesidad de coordinar el desarrollo grupal para evitar conflictos e inconsistencias. Se requiere un flujo que permita separar el código estable del experimental y facilite el trabajo paralelo.

Decisión

Implementar una variante de Git Flow. Se utilizarán dos ramas persistentes (main para entregas estables y develop para integración) junto a ramas temporales (feature) de ciclo de vida corto para tareas específicas.

Estado

Aceptado

Consecuencias

Beneficios: Protección del entorno de producción, aislamiento de errores en ramas experimentales y facilitación del desarrollo paralelo (ej. lógica en Rust y corrección de bugs simultáneos).

Desventajas: Historial menos lineal debido a múltiples bifurcaciones y mayor complejidad potencial al resolver conflictos en integraciones semanales.

9.3. Centralización de Endpoints

Sección	Descripción
Título	Implementación de un API Gateway para la centralización de endpoints
Contexto	El esqueleto proporcionado inicialmente presentaba una estructura dispersa. Para gestionar las peticiones de los clientes (web, bots) hacia los diferentes módulos de la aplicación, es necesario un punto de entrada único que simplifique la comunicación y la seguridad.
Decisión	Implementar un API Gateway. Se centralizan todos los endpoints de la aplicación en un único punto de acceso para actuar como intermediario hacia los servicios internos.
Estado	Aceptado
Consecuencias	Beneficios: - Abstracción y simplificación: Los servicios internos son transparentes al cliente; el gateway redirige cada petición al servicio oportuno. - Seguridad centralizada: Permite gestionar la autenticación, el filtrado de datos y el control de tráfico en un solo punto. Desventajas: -Punto único de fallo: Si el gateway falla, se interrumpe toda la comunicación externa con el juego. -Latencia añadida: La inclusión de esta capa puede incrementar sutilmente el tiempo de respuesta.

Sección

Descripción

Título

Implementación de un API Gateway para la centralización de endpoints

Contexto

El esqueleto proporcionado inicialmente presentaba una estructura dispersa. Para gestionar las peticiones de los clientes (web, bots) hacia los diferentes módulos de la aplicación, es necesario un punto de entrada único que simplifique la comunicación y la seguridad.

Decisión

Implementar un API Gateway. Se centralizan todos los endpoints de la aplicación en un único punto de acceso para actuar como intermediario hacia los servicios internos.

Estado

Aceptado

Consecuencias

Beneficios:

- Abstracción y simplificación: Los servicios internos son transparentes al cliente; el gateway redirige cada petición al servicio oportuno.

- Seguridad centralizada: Permite gestionar la autenticación, el filtrado de datos y el control de tráfico en un solo punto.

Desventajas:

-Punto único de fallo: Si el gateway falla, se interrumpe toda la comunicación externa con el juego.

-Latencia añadida: La inclusión de esta capa puede incrementar sutilmente el tiempo de respuesta.

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

10.2.1. Escenario 1: Exactitud en Movimientos

10.2.2. Escenario 2: Exactitud en estado de la partida

10.2.3. Escenario 3: Usabilidad de la aplicación

10.2.4. Escenario 4: Rendimiento en tiempos de respuesta

10.2.5. Escenario 5: Protección contra inyecciones SQL

10.2.6. Escenario 6: Disponibilidad de la aplicación en mantenimientos

11. Riesgos y Deuda Técnica

En esta sección se recogen los principales riesgos y deudas técnicas identificados durante el desarrollo del proyecto. Se han ordenado por prioridad y se incluye una breve propuesta de mitigación para cada caso.

Contents

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

Motivation

“Risk management is project management for grown-ups” (Tim Lister, Atlantic Systems Guild.)

This should be your motto for systematic detection and evaluation of risks and technical debts in the architecture, which will be needed by management stakeholders (e.g. project managers, product owners) as part of the overall risk analysis and measurement planning.

Form

List of risks and/or technical debts, probably including suggested measures to minimize, mitigate or avoid risks or reduce technical debts.

Further Information

See Risks and Technical Debt in the arc42 documentation.

11.1. 11.1 Riesgos

Nombre	Descripción	Prioridad	Mitigación propuesta
Falta de tiempo	El proyecto debe desarrollarse al mismo tiempo que otras asignaturas y entregas, por lo que existe un riesgo real de no llegar a implementar todas las funcionalidades previstas con la calidad deseada.	Alta	Priorizar primero las funcionalidades esenciales, trabajar con incrementos pequeños y evitar dedicar demasiado tiempo a mejoras secundarias antes de estabilizar la funcionalidad principal.
Problemas de coordinación y control de versiones	Al tratarse de un proyecto en equipo con varios servicios y documentación compartida, una mala coordinación o una resolución incorrecta de conflictos en GitHub puede sobrescribir trabajo, retrasar integraciones o dejar cambios inconsistentes entre módulos.	Media	Seguir utilizando issues, pull requests y ramas de corta duración, y revisar cuidadosamente las fusiones antes de integrar cambios en las ramas principales.
Punto único de fallo en el gateway	El API Gateway es el punto principal de entrada para todo el tráfico externo. Si falla, la aplicación web y el acceso de bots quedan indisponibles, ya que el despliegue actual no cuenta con réplicas ni mecanismos de tolerancia a fallos.	Media	Añadir healthchecks, políticas de reinicio y un despliegue más robusto, y valorar replicación si el entorno de producción crece.
Experiencia limitada con algunas tecnologías	Parte del equipo está trabajando por primera vez con tecnologías como React, despliegue con Docker, documentación Arc42 y separación por servicios, lo que puede ralentizar el desarrollo y provocar errores evitables.	Media	Compartir conocimiento dentro del equipo, reutilizar ejemplos que ya funcionan en el propio proyecto y documentar las decisiones técnicas principales para reducir el tiempo de aprendizaje.

Nombre

Descripción

Prioridad

Mitigación propuesta

Falta de tiempo

El proyecto debe desarrollarse al mismo tiempo que otras asignaturas y entregas, por lo que existe un riesgo real de no llegar a implementar todas las funcionalidades previstas con la calidad deseada.

Alta

Priorizar primero las funcionalidades esenciales, trabajar con incrementos pequeños y evitar dedicar demasiado tiempo a mejoras secundarias antes de estabilizar la funcionalidad principal.

Problemas de coordinación y control de versiones

Al tratarse de un proyecto en equipo con varios servicios y documentación compartida, una mala coordinación o una resolución incorrecta de conflictos en GitHub puede sobrescribir trabajo, retrasar integraciones o dejar cambios inconsistentes entre módulos.

Media

Seguir utilizando issues, pull requests y ramas de corta duración, y revisar cuidadosamente las fusiones antes de integrar cambios en las ramas principales.

Punto único de fallo en el gateway

El API Gateway es el punto principal de entrada para todo el tráfico externo. Si falla, la aplicación web y el acceso de bots quedan indisponibles, ya que el despliegue actual no cuenta con réplicas ni mecanismos de tolerancia a fallos.

Media

Añadir healthchecks, políticas de reinicio y un despliegue más robusto, y valorar replicación si el entorno de producción crece.

Experiencia limitada con algunas tecnologías

Parte del equipo está trabajando por primera vez con tecnologías como React, despliegue con Docker, documentación Arc42 y separación por servicios, lo que puede ralentizar el desarrollo y provocar errores evitables.

Media

Compartir conocimiento dentro del equipo, reutilizar ejemplos que ya funcionan en el propio proyecto y documentar las decisiones técnicas principales para reducir el tiempo de aprendizaje.

11.2. 11.2 Deuda técnica

Nombre	Descripción	Prioridad	Mitigación propuesta
Inconsistencia de configuración	Algunas variables de entorno y URLs de servicios siguen convenciones distintas según el módulo o el entorno. Esto hace que el despliegue y el mantenimiento sean más frágiles de lo necesario.	Media	Unificar convenciones de nombres, validar la configuración al arrancar y mantener una única referencia para las variables de despliegue.
Monitorización básica	Prometheus y Grafana están presentes en el proyecto, pero su configuración todavía es básica y se centra sobre todo en el servicio de usuarios. Esto deja una observabilidad limitada para el resto de la arquitectura.	Media	Extender la recogida de métricas al resto de servicios y mejorar progresivamente dashboards y alertas.

Nombre

Descripción

Prioridad

Mitigación propuesta

Inconsistencia de configuración

Algunas variables de entorno y URLs de servicios siguen convenciones distintas según el módulo o el entorno. Esto hace que el despliegue y el mantenimiento sean más frágiles de lo necesario.

Media

Unificar convenciones de nombres, validar la configuración al arrancar y mantener una única referencia para las variables de despliegue.

Monitorización básica

Prometheus y Grafana están presentes en el proyecto, pero su configuración todavía es básica y se centra sobre todo en el servicio de usuarios. Esto deja una observabilidad limitada para el resto de la arquitectura.

Media

Extender la recogida de métricas al resto de servicios y mejorar progresivamente dashboards y alertas.

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

Term

Definition

<Term-1>

<definition-1>

<Term-2>

<definition-2>