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

1.1. Descripción de los requisitos

  • La app tendrá una interfaz web para jugar al juego Y.

  • Se ofrecerán dos funcionalidades de juego:

    • El usuario podrá enfrentarse a otro usuario.

    • El usuario podrá enfrentarse a un bot implementado.

      • El bot tendrá diferentes estrategias, y el usuario podrá elegir cuál de ellas usar (nivel de dificultad).

  • El tablero tendrá tamaño variable (a elección del usuario, sino el tamaño será el establecido como automático).

  • El usuario podrá registrarse en la aplicación, o inciar sesión si ya tiene cuenta asociada.

    • Cada usuario podrá ver un historial de partidas y sus estadísticas (ganadas/perdidas, número de partidas, etc.).

  • Se proporcionará un API externo (documentado) para que los bots puedan usar el sistema.

    • El API permitirá consultar/gestionar info de usuarios y partidas.

    • El API tendrá un método play que recibe al menos position (en notación YEN) y devuelve el siguiente movimiento (también en YEN).

  • El “motor” del juego estará en un módulo/servicio aparte (implementado en Rust), y la web lo llamará por HTTP mediante JSON (usando YEN).

Casos de uso:

ID Caso de uso Actor ¿Qué pasa?

UC-01

Registrarse / iniciar sesión

Usuario

El usuario se crea cuenta o entra con su cuenta para poder guardar partidas y ver estadísticas.

UC-02

Crear partida con tamaño de tablero

Usuario

El usuario crea una partida eligiendo el tamaño y el modo (vs. otro usuario o vs. bot).

UC-03

Jugar un turno desde la web

Usuario

El usuario hace un movimiento y el sistema actualiza el estado de la partida.

UC-04

Jugar contra bot (pedir movimiento)

Sistema / Usuario

Si es el turno del bot, se llama al servicio (módulo `gamey') para que sugiera el siguiente movimiento según la estrategia/dificultad escogida.

UC-05

Comprobar si alguien ha ganado

Sistema

Después de cada movimiento, se comprueba si la partida está ganada.

UC-06

Ver historial y estadísticas

Usuario registrado

El usuario ve el historial partidas anteriores y sus estadisticas guardadas en su cuenta.

UC-07

Consultar/gestionar datos vía API

Bot

El bot puede acceder/gestionar información de usuarios y partidas (según los permisos establecidos).

1.2. Objetivos de calidad

Los objetivos de calidad del sistema se concretan y evaluarán en la sección "10. Atributos de Calidad" siguiendo el modelo ISO/IEC 25010, mediante un árbol de calidad y escenarios. De forma resumida, la arquitectura prioriza:

  • Adecuación funcional: El motor debe garantizar el cumplimiento de reglas y la validación del estado de la partida, evitando acciones inválidas y guiando al usuario durante el juego.

  • Eficiencia de desempeño: Se busca respuesta ágil y sin “lag” en las operaciones principales, con un uso eficiente de recursos y soporte de concurrencia, apoyado en el motor en Rust y el despliegue en contenedores.

  • Compatibilidad / interoperabilidad: La comunicación entre subsistemas y con bots externos debe ser estable, clara y validada, basada en JSON con notación YEN y un API bien documentado.

  • Usabilidad: La web debe ser intuitiva y fácil de aprender, con una interfaz que indique turnos, opciones y restricciones, reduciendo errores del usuario.

  • Fiabilidad / disponibilidad: El sistema debe mantener estabilidad ante fallos habituales y ser observable/monitorizable para detectar caídas o degradaciones.

  • Seguridad: Se controlarán accesos (registro/login y API pública), validación de entradas y medidas de protección de credenciales (por ejemplo, cifrado/hasheado de contraseñas).

  • Mantenibilidad: El diseño modular por microservicios y la separación de responsabilidades deben permitir incorporar nuevas estrategias/reglas o cambios en el API minimizando el impacto en el resto del sistema.

  • Portabilidad: Al basarse en Docker, el sistema debe ser desplegable en distintos entornos con una instalación reproducible.

1.3. Stakeholders

Stakeholder Descripción Expectativas / motivaciones

Jugador (usuario final)

Persona que entra a la web para jugar al juego Y (contra otra persona o contra el bot).

Que sea fácil de usar, que cargue rápido, que el juego no dé errores raros, poder elegir tamaño/estrategia y ver su historial y estadísticas.

Equipo de desarrollo

Mario Amandi, Marcelo Díez, Andrea Ivanov y Eloy Rubio

Poder avanzar sin bloqueos, tener una arquitectura modular, poder implementar buenos tests y desplegar el sistema, además de mejorar las habilidades de programación (nuevos lenguajes), desarrollo y trabajo en equipo.

Profesorado

Jose E. Labra Gayo, Pablo González, Diego Martín Fernández y Celia Melendi Lavandera

Que se cumplan los requisitos, que se justifiquen las decisiones arquitectónicas, que haya pruebas de código y que el despliegue sea accesible por web.

Micrati

Empresa que decide apostar por el desarrollo del juego y encarga el proyecto.

Que el producto final sea usable y presentable, que cumpla los requisitos establecidos, que sea fácil de mantener/mejorar y que no tenga fallos.

2. Restricciones Arquitectónicas

2.1. Restricciones técnicas y estructurales

Restricción Descripción

Frontend desarrollado con Vite y React

La interfaz gráfica debe implementarse con Vite y/o React.

Servicio de usuarios desarrollado con Node.js y Express

El servicio dedicado a la gestión de usaurios debe ser un REST API implementado con Node.js y/o Express.

Juego desarrollado con Rust

La lógica clave del juego (crear tablero, manejar movimientos, implementación de bot, etc) tiene que estar desarrollado en Rust y expuesta como servicio web.

Comunicación por JSON usando notación YEN

Los mensajes entre los módulos de interfaz (webapp) y el servicio Rust (gamey) deben usar JSON y representar posiciones con la notación YEN.

Soporte de tablero de tamaño variable

El sistema debe soportar un tablero cuyo tamaño sea variable (un tamaño establecido predefinido, y que el usuario pueda escoger otro tamaño diferente).

Diverentes estrategias de bot (dificultad)

El bot debe tener más de una estrategia y el usuario debe poder elegirla (relacionado con niveles de dificultad).

Host en Docker

El sistema deberá estar "levantado" con Docker en una máquina virtual para la entrega final.

Documentación con arc42

La documentación debe seguir la estructura base de la plantilla arc42.

Control de versiones

El proyecto se desarrollará mediante Git, alojándolo en GitHub.

2.2. Restricciones organizativas y de proceso

Restricción Descripción

Énfasis en calidad y evaluación

Se valora explícitamente documentación, pruebas, despliegue, repositorio y calidad general.

Trabajo en equipo y control de cambios

Al ser un proyecto en grupo, se necesita un flujo de trabajo con control de versiones, revisiones y acuerdos, además de comunicación entre compañeros.

Gestión de tareas

Se utilizará la funcionalidad de Github "Github Issues" para asignar y gestionar las tareas de cada miembro del equipo.

Tiempo y alcance limitados

El proyecto tiene diferentes entregas a lo largo de su desarrollo (versiones).

Reuniones de equipo

Se realizará al lo menos una reunión semanal (sesión de laboratorio). Además, se harán reuniones extras cuando se vea necesario (presenciales o telemáticas) para poner de acuerso diferentes implementaciones. Estas quedarán reflejadas en sus respectivas actas en el apartado "Wiki" del repositorio de GitHub.

3. Contexto y Alcance

3.1. Contexto de negocio

Diagrama correspondiente al Contexto de Negocio

  • Jugador: Usa el sistema para registrarse/iniciar sesión, jugar (elegir estrategia, contrincante y tamaño de tablero) y consultar resultados.

  • Bot: Consume el API para automatizar partidas y realizar jugadas.

  • Administrador: Supervisa el sistema y su disponibilidad (logs, despliegue, etc.).

  • Repositorios de datos (MongoDB): Almacena todos los datos necesarios relacionados con los usuarios y las partidas de estos.

3.2. Contexto técnico

Diagrama correspondiente al Contexto Técnico

  • Web Browser (Jugador): Cliente que actua con la interfaz web. Se comunica con el frontend y realiza peticiones al backend para registro/autenticación y gestión de partidas.

  • Servidor (Docker): Aloja los servicios backend y el motor del juego. Contiene:

    • webapp (React/Vite): Contenedor que sirve la aplicación frontend (SPA) como contenido estático al navegador.

    • users (Node/Express): Servicio backend que expone el API REST público. Gestiona usuarios y partidas y actúa como punto de entrada tanto para el navegador como para el bot.

    • gamey (Rust): Servicio interno que encapsula la lógica del juego. Se invoca desde el backend para verificar victoria, calcular sugerencias de movimientos de bot y gestiona el estado del tablero, intercambiando este último usando notación JSON (YEN).

    • MongoDB: Servicio de persistencia donde se almacenan los datos correspondientes de usuarios, partidas y estadísticas.

  • Bot Client: Cliente externo que consume el API público enviando posiciones en YEN para obtener el siguiente movimiento.

4. Estrategia de Solución

4.1. Decisiones Tecnológicas

El sistema adopta una arquitectura de microservicios con tres componentes principales:

  • webapp (React + Vite + TypeScript): Interfaz web donde los usuarios juegan

  • users (Node.js + Express): Gestiona usuarios, autenticación y partidas

  • gamey (Rust): Motor del juego con las reglas y lógica del Juego Y

4.1.1. Stack Tecnológico

Frontend (webapp):

  • React + TypeScript para crear una interfaz de usuario moderna y robusta

  • Vite para desarrollo rápido

Backend (users):

  • Node.js + Express por su simplicidad para crear APIs REST

  • Swagger para documentar el API

  • Prometheus para recoger métricas del sistema

Motor de juego (gamey):

  • Rust por su alto rendimiento y seguridad

  • Puede ejecutarse como servidor web o desde línea de comandos

Base de datos:

  • MongoDB por su flexibilidad y fácil integración con JSON

Comunicación:

  • HTTP/REST con JSON

  • Notación YEN para las posiciones del tablero

Despliegue:

  • Azure para alojar la maquina virtual en la que se ejecuta la aplicación

  • Docker para que funcione igual en todos los entornos

4.2. Patrones Arquitectónicos

4.2.1. Frontend: Single Page Application (SPA)

Webapp es una aplicación de página única con React que actualiza dinámicamente el contenido sin recargar la página.

4.2.2. Motor de Juego: Separación entre Dominio e Infraestructura

gamey separa la lógica del juego de los detalles técnicos:

Lógica del juego:

  • core/: Núcleo del juego

  • bot/: Diferentes estrategias de bots

Infraestructura:

  • game_server/: Servidor del juego con el servidor

  • bot_server/: Conexión del bot con el servidor

  • notation/: Conversión entre formatos (YEN, YGN)

4.3. Decisiones Organizativas

Gestión:

  • GitHub Issues para tareas y bugs

  • Kanban para seguimiento visual

  • Pull Requests con revisión obligatoria

  • Rama master protegida

Documentación:

  • Arc42 para la documentación del proyecto

  • Draw.io para realizar los diagramas

  • Wiki para las actas de las reuniones

5. Vista de bloques

5.1. Visión general

Diagrama correspondiente a la visita de bloque general

Vista general del sistema con tres microservicios independientes: webapp (interfaz), users (gestión de usuarios) y gamey (motor del juego).

6. Vista de ejecución

6.1. Registrar un usuario

Diagrama correspondiente a el proceso de registrar un usuario

Proceso de registrar un usuario.

6.2. Jugar una casilla

Diagrama correspondiente a el proceso de jugar una casilla

Proceso de jugar una casilla.

7. Vista de Despliegue

Content

The deployment view describes:

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

  2. 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. Infrastructura Nivel 1

La arquitectura de despliegue se basa en la contenedorización de los servicios, permitiendo un entorno aislado y reproducible tanto en desarrollo como en producción dentro de la infraestructura de Microsoft Azure.

Diagrama correspondiente al Despliegue
Motivación

Se ha elegido Azure por su capacidad de integración con flujos de CI/CD (GitHub Actions) y su robustez. El uso de Docker garantiza que el software se comporte de la misma manera en el servidor que en los entornos de prueba, evitando el clásico "en mi máquina funciona".

Características de calidad y/o rendimiento

  • Disponibilidad: Azure garantiza un SLA elevado para sus servicios de computación.

  • Observabilidad: La inclusión de Prometheus y Grafana directamente en la infraestructura permite monitorizar el rendimiento y la salud de los servicios en tiempo real.

  • Escalabilidad: Azure ofrece escalado automático, lo que permite ajustar los recursos según la demanda.

Mapeo de los bloques de construcción a la infraestructura
Bloque de Construcción Puerto Externo

webapp

80

users

3000

gamey

4000

prometheus

9090

grafana

9091

7.2. Infrastructura Nivel 2

7.2.1. Servicios de Aplicación

Estos contenedores representan la lógica de negocio y la interfaz de usuario:

  • webapp (Puerto 80): Servidor web (Nginx/Apache) que sirve la aplicación frontend. Se comunica con el backend a través de la URL de API configurada.

  • users (Puerto 3000): Microservicio encargado de la gestión de usuarios y autenticación.

  • gamey (Puerto 4000): Microservicio encargado de la lógica del juego.

7.2.2. Servicios de Monitorización

Infraestructura dedicada a asegurar el correcto funcionamiento del sistema bajo carga:

  • Prometheus (Puerto 9090): Recolecta métricas de los servicios users y otros componentes.

  • Grafana (Puerto 9091): Visualiza las métricas recolectadas mediante paneles de control (dashboards) configurados mediante volúmenes de aprovisionamiento.

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.

8. Conceptos Transversales (Cross-cutting Concepts)

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. Monitorización y Observabilidad

Para garantizar la salud del sistema, se ha implementado una infraestructura de observabilidad transversal:

  • Recolección de métricas: Prometheus actúa como el recolector central, extrayendo datos de rendimiento de los diferentes contenedores.

  • Visualización: Grafana proporciona tableros de control para monitorizar en tiempo real el estado de los servicios, facilitando la detección temprana de fallos.

8.2. Proceso de Desarrollo y Gestión (GitHub Ecosystem)

Para asegurar la calidad del software y la organización del equipo, se utiliza el ecosistema de GitHub de manera integral:

  • Gestión de Tareas (Kanban): Se utiliza GitHub Projects con una metodología Kanban para visualizar el flujo de trabajo (To Do, In Progress, Done…​). Esto permite el seguimiento en tiempo real del estado de cada funcionalidad.

  • Seguimiento de Tareas (Issues): Cada nueva funcionalidad, error o mejora se documenta mediante Issues, que sirven como unidad básica de trabajo y permiten la trazabilidad de los requisitos.

  • Flujo de Trabajo (Pull Requests): El código no se integra directamente en la rama principal. Se utilizan Pull Requests (PRs) para la revisión, asegurando que el código cumpla con los estándares antes de ser fusionado.

8.3. Tecnologías

El sistema adopta un enfoque de varios lenguajes, seleccionando la herramienta más adecuada para cada dominio del problema:

  • Backend de Gestión (Node.js/Express): El servicio users utiliza un entorno basado en eventos y JavaScript para gestionar la lógica de usuario de forma ágil y escalable.

  • Motor de Juego de Alto Rendimiento (Rust): El servicio gamey está desarrollado en Rust para garantizar la seguridad de memoria y un alto rendimiento en la lógica del juego, ofreciendo además versatilidad al poder ejecutarse tanto en modo servidor como en modo CLI.

  • Frontend Moderno (React + Vite): La interfaz de usuario (webapp) utiliza React para una gestión eficiente del estado de la UI y Vite como herramienta de construcción rápida.

9. Decisiones de Arquitectura (ADR)

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.

En esta sección se documentan las decisiones arquitectónicas fundamentales que rigen el diseño y desarrollo de Yovi_es4a, detallando su justificación y las alternativas consideradas.

9.1. ADR 1: Uso de MongoDB como Base de Datos

  • Estado: Aceptada.

  • Contexto: Se requiere un sistema de persistencia para almacenar los datos de los usuarios y del juego que sea flexible y compatible con el ecosistema tecnológico actual.

  • Alternativas: Bases de datos relacionales (como MySQL).

  • Justificación: Compatibilidad: MongoDB utiliza formato BSON (variante de JSON), lo que facilita enormemente el flujo de datos con el frontend en React y el uso de TypeScript**.

    • Integración con Rust: La seguridad de tipos permite convertir documentos de la base de datos en structs de Rust con una sola línea de código, garantizando datos válidos en el motor gamey.

    • Facilidad de despliegue: Gracias a Docker, levantar una instancia de MongoDB es inmediato, facilitando la adición de requisitos sin necesidad de migraciones complejas.

    • Idoneidad: Es ideal para estructuras de datos no excesivamente complejas, como las de un juego web.

  • Consecuencias: Se espera una mayor flexibilidad y rapidez en el desarrollo al no depender de esquemas rígidos.

9.2. ADR 2: Uso inicial de PlantUML para diagramación

  • Estado: Reemplazada (por ADR 3).

  • Contexto: Necesidad de una herramienta para crear los diagramas técnicos de la documentación arc42.

  • Alternativas: Editores visuales como draw.io.

  • Justificación: Enfoque técnico: Es una herramienta basada en texto ("pseudo-código") recomendada en el ámbito académico.

    • Mantenibilidad: El uso de código facilita la realización de cambios rápidos y el control de versiones.

  • Consecuencias: Permite la generación automática de diagramas visuales a partir de relaciones definidas por código, aunque carece de flexibilidad en la disposición visual manual.

9.3. ADR 3: Adopción de draw.io para diagramas

  • Estado: Aceptada.

  • Contexto: Tras evaluar el uso de PlantUML, se identificó la necesidad de una representación más esquemática y visual de los componentes.

  • Alternativas: PlantUML (mantenida como opción de respaldo).

  • Justificación: Intuitividad: Es una herramienta más visual que no requiere aprendizaje previo para su manejo.

    • Control Visual: Permite ubicar los componentes (webapp, users, gamey) libremente, facilitando la representación de relaciones y jerarquías de forma más clara y esquemática.

  • Consecuencias: Aunque requiere algo más de tiempo manual para la creación, resulta más cómoda y comunicativa para el equipo de desarrollo.

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.

En esta sección se evaluarán los requisitos de calidad del proyecto siguiendo el modelo ISO/IEC 25010, el cuál nos facilita una serie de puntos imprescindibles para cumplir los estándares internacionales de ingeniería del software.

10.1. Quality Tree

arbol de calidad

Adecuación funcional

  • Completitud funcional: Se cubren los requisitos de jugabilidad implementando las acciones propias del juego Y, competición contra un bot y contra otros usuarios.

  • Corrección funcional: Se contemplan las reglas de juego desde el motor, garantizando una validación precisa del estado de la partida en cada momento. Se guía al usuario a seguir correctamente el desarrollo de partida. SC1

Eficiencia de desempeño

  • Comportamiento en el tiempo: Se garantiza un tiempo de respuesta óptimo al utilizarse Rust en el motor del juego. Además de la implementación de una estrategia cuidada del algoritmo de respuesta.

  • Utilización de recursos: El despliegue mediante contenedores Docker permite una gestión eficiente de la memoria y la CPU para los tres subsistemas (webapp, users, gamey). SC4

  • Capacidad: Se limitan los tamaños de tablero dentro de un rango para que siga siendo jugable dentro de la configuración que el usuario escoja.

Compatibilidad

  • Facilidad para interoperar: El intercambio de información entre subsistemas se realiza estrictamente mediante mensajes JSON siguiendo la notación YEN, asegurando que el API sea compatible tanto con la WebApp como con bots externos.

  • Coexistencia: Los microservicios están clasificados en sus contenedores correspondientes y facilmente se levantan y conectan entre sí en el docker-compose.yml.

Usabilidad

  • Inteligibilidad: Dispone de una interfaz clara e intuitiva diseñada con React para facilitar su uso a todo tipo de usuario. Se busca tener un aspecto actualizado.

  • Capacidad de aprendizaje: El juego sigue reglas sencillas con facilidad de aprendizaje. La dificultad está presente en aprender qué estrategia seguir.

  • Operabilidad: La propia interfaz te guía durante el juego mostrándote de quién es el turno, las casillas disponibles y opciones disponibles. SC2

  • Protección contra errores de usuario: Aquellas acciones que desencadenarían algún fallo, como por ejemplo jugar fuera de tu propio turno, están deshabilitadas, previendo una mala práctica del juego.

  • Participación del usuario: Se dispone de una interfaz interactiva con distintas funciones para que el usuario además de jugar al juego pueda registrar usuario y disponer de sus estadísticas.

  • Accesibilidad: Cualquier persona de habla hispana puede acceder al juego. No tiene soporte de idiomas. SC3

  • Asistencia al usuario: Dispone de una ayuda para entender qué hace cada componente en cada caso, además de tooltips y mensajes descriptivos.

  • Autodescripción: Se busca dejar lo más claro posible el uso de cada herramienta ya sea con un texto descriptivo en botones o dibujos que indiquen claramente su finalidad.

Fiabilidad

  • Madurez: A lo largo de todo el proyecto se utiliza SonarCloud para mantener cierta calidad de código. Se han realizado pruebas unitarias y de integración para garantizar la estabilidad del sistema.

  • Disponibilidad: Se utilizan las herramientas Prometheus y Grafana para monitorizar el estado de los microservicios y detectar posibles caídas o problemas de rendimiento.

Seguridad

  • Confidencialidad: Se implementa un sistema de registro apoyado por una base de datos para almacenar a los usuarios, los cuales se autenticarán para acceder a sus cuentas.

  • Integridad: Se implementa un grado más de seguiridad cifrando las contraseñas de los usuarios, así nosotros tampoco contamos explicitamente con estas. SC5

  • No repudio: Se guarda en la base de datos la interacción del usuario con la aplicación junto con una serie de datos estadísticos, por lo que el correo asociado con la cuenta guarda un registro de actividad.

Mantenibilidad

  • Modularidad: El proyecto está dividido en tres microservicios (gamey, users y webapp). A su vez, en cada uno se sigue una estructura con las resposabilidades bien definidas y una clara separación de capas. Así se garantiza que un mínimo cambio no proboca un efecto de cascada. SC6

Portabilidad

  • Adaptabilidad: Al estar basado en Docker, el proyecto es independiente del sistema operativo, lo que facilita su despliegue en diferentes entornos.

  • Instalabilidad: Mediante scripts de npm y comandos de Cargo, se levanta el entorno al completo rápidamente, con todos los componentes ya configurados.

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. Quality Scenarios

A continuación se exponen distintos escenarios de uso identificados por un código, por ejemplo SC1. Este código se encontrará en el arbol de calidad en el apartado que lo satisface, si pinchas en él te redirige a requisito de calidad.

ID Atributo Escenario

SC1

Adecuación funcional

Un usuario trata de colocar una ficha en un turno que no es el suyo. El sistema no le permite saltarse el turno.

SC2

Usabilidad

Un nuevo usuario juega por primera vez sin saber las reglas de turnos, la interfaz muestra claramente mediante identificadores visuales cuándo le toca.

SC3

Usabilidad

Una persona que no sabe español accede al juego. No tiene otra opción que jugar en español, lo que dificulta su experiencia de usuario.

SC4

Eficiencia de desempeño

Se quiere jugar una partida rápida, el juego responde rápido a los cambios de ventana y carga de componentes visuales.

SC5

Seguridad

Se accede con una clave no muy segura, se cifran las contraseñas por lo que se añade un grado de seguridad.

SC6

Mantenibilidad

Nos comunican que hay un nuevo requisito en la interfaz y que además se ha añadido una regla, son facilmente indentificables las zonas responsables de cada tarea.
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.

11. Riesgos y Deudas Técnicas

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.

En esta sección se describen los riesgos encontrados en el desarrollo del proyecto y las soluciones propuestas.

Riesgo Descripción Solución

Mezcla de lengueajes

Para este proyecto se usa Rust, Node.js y React, añadiendo dificultad extra ya que utilizan lenguajes con los que no estamos familiarizados, además de que el proyecto tiene equipos marcados para sección.

Estar al tanto revisando el trabajo todos de todos, respondiendo pull request y manteniendo en cada sección una documentación clara y un seguimiento del proyecto exhaustivo.

Curva de aprendizaje de Rust

Se trata de un lenguaje complejo con el que levantar un proyecto de cero sin conocer su sintaxis y funcionamiento puede suponer un retraso.

Documentarse muy bien, tomar ejemplos de otros proyectos y apoyarse en la IA como guía. Se empezó implementando algoritmos con dificultades más leves para ir mejorándolos.

Tiempos de carga elevados

El juego utiliza un algoritmo de búsqueda en el que se valoran las mejores opciones recorriendo repetidamente un arbol, lo que puede costar tiempos elevados de carga y hacer que se cuelgue el contenedor.

Implementar límites de tiempo de respuesta.

Seguridad en el servicio de usuarios

Para acceder al juego hay que pasar por una ventana de registro en la que el usuario debe introducir sus datos.

Se implementan dos medidas, la primera de verificación de integridad, para que el usuario corrobore que tiene acceso al correo que está usando se emplea una verificación en dos pasos. La segunda es que en nuestra base de datos almacenamos codigos hash creados a partir de la contraseña del usuario, por lo que no disponemos de su contraseña real.

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

Arc42

Plantilla de arquitectura de software utilizada para estructurar y documentar las decisiones de diseño de este proyecto.

Docker Compose

Herramienta utilizada para orquestar la ejecución simultánea de los servicios webapp, users y gamey, definiendo sus redes y puertos en un solo archivo de configuración.

SPA (Single Page Application)

Arquitectura del frontend (webapp) construida con React y Vite, donde la aplicación se carga una sola vez y actualiza dinámicamente el contenido sin recargar la página.

Coordenadas Baricéntricas

Sistema de coordenadas (x, y, z) utilizado para representar posiciones en el tablero triangular. Cumplen la restricción x + y + z = N - 1, lo que facilita el cálculo de distancias a los lados del triángulo.

MCTS (Monte Carlo Tree Search)

Algoritmo probabilístico que decide el mejor movimiento ejecutando miles de partidas aleatorias desde el estado actual para estimar estadísticamente la probabilidad de victoria.

YEN (Y Exchange Notation)

Formato de serialización basado en JSON inspirado en FEN. Representa el estado completo de una partida (tablero, turno, jugadores) para su almacenamiento o transmisión.