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. Introduction and Goals

El proyecto Yovi es una propuesta planteada por la empresa de desarrollo de videojuegos Micrati, cuyo objetivo es desarrollar una aplicación web para jugar al juego Y, permitiendo tanto la interacción de usuarios humanos como la integración de bots mediante una API externa.

1.1. Participantes

El equipo está formado por:

  • Pablo García Menéndez, UO299834

  • Elías Fernández Medina, UO299673

  • Sergio Espina Marcos, UO301107

  • Adrián Pérez Menéndez, UO201188

1.2. Requirements Overview

Los requisitos del proyecto Yovi son los siguientes:

  • Los usuarios podrán jugar partidas desde la web al juego Y, al menos a la versión clásica del juego y contra una máquina.

  • Los usuarios podrán elegir el tamaño del tablero, así como la estrategia que el bot rival empleará.

  • Los usuarios podrán registrarse en el sistema y consultar el histórico de su participación: número de juegos realizados, estadísticas de partidas ganadas/perdidas, etc.

  • La aplicación dispondrá de una API que permita a los bots interactuar con ella.

  • La API de la aplicación permitirá acceder y gestionar información de los usuarios y de las partidas.

  • La API tendrá documentación.

  • La API permitirá que un bot juegue contra la aplicación.

1.3. Quality Goals

Objetivo de calidad Descripción

Usabilidad

La aplicación web deberá ser sencilla de usar e intuitiva, permitiendo que cualquier usuario tenga una buena experiencia jugando al juego Y.

Rapidez

Se buscará que los tiempos de respuesta sean lo más cortos posibles, tanto durante la partida como en la navegación de la aplicación.

Mantenibilidad

La aplicación deberá ser fácil de mantener, con código limpio y fácil de modificar o ampliar, siguiendo buenas prácticas de diseño de software.

Fiablilidad

La aplicación tendrá que ser fiable y funcionar correctamente ante cualquier situación llevada a cabo por los usuarios. También deberá de estar disponible el mayor tiempo posible.

1.4. Stakeholders

Rol/Nombre Contacto Expectativas

Micrati

Empresa de desarrollo de videojuegos

Espera una entrega de la aplicación que cumpla todos los requisitos especificados.

Equipo de desarrollo

Sergio Espina Marcos, Pablo García Menéndez, Elías Fernández Medina, Adrián Pérez Menéndez

Espera desarrollar una aplicación web aplicando y mejorando sus conocimientos y habilidades.

Usuarios

Personas que utilicen la aplicación

Esperan poder divertirse jugando al juego Y.

Profesor

Jose Emilio Labra Gayo

Espera asistir al equipo de desarrollo en el proyecto y evaluarlo.

2. Architecture Constraints

2.1. Technical Constraints

Restricción Descripción

Lenguaje frontend

La aplicación web debe desarrollarse utilizando TypeScript con React.

Módulo de lógica

El motor del juego debe implementarse en lenguaje introducido en seminarios Rust.

Comunicación

La comunicación entre el frontend y el módulo de lógica se realizará mediante servicios web usando JSON.

Notación YEN

Las partidas deberán representarse utilizando la notación YEN proporcionada.

API externa

El sistema debe exponer una API que permita la interacción con bots.

Despliegue web

La aplicación debe estar accesible a través de Internet (p.e VM de Azure).

2.2. Organizational Constraints

Restricción Descripción

Trabajo en equipo

El desarrollo se realiza en equipo, lo cual implica coordinación y reparto de tareas equitativo.

Evaluación académica

El proyecto será evaluado según los criterios establecidos.

Uso de GitHub

El repositorio debe mantenerse actualizado con un historial claro de commits, issues, actas y decisiones que se puedan tomar.

2.3. Conventions

Convención Descripción

PLantilla arc42

Se seguirá la plantilla de arc42 para documentar la arquitectura.

Buenas prácticas

Se aplicarán principios de diseño limpio y mantenible.

Control de versiones

Se utilizará Git para el control de versiones.

3. Context and Scope

3.1. Business Context

Elemento Entrada Salida

Usuario

Accede a la aplicación, realiza movimientos, consulta historial

Visualización del tablero, resultados de la partida, historial

Bot externo

Solicitudes al API (posición en formato YEN, peticiones de jugadas)

Respuesta con el siguiente movimiento en formato YEN

Sistema Yovi

Recibe movimientos y peticiones

Gestiona partidas, usuarios y lógica del juego

Módulo de lógica (Rust)

Estado del tablero en formato YEN

Resultado de la partida o siguiente movimiento sugerido

El sistema Yovi actúa como intermediario entre los usuarios, los bots externos y el módulo de lógica del juego. Los usuarios interactúan a través de la interfaz web, mientras que los bots lo hacen mediante el API.

3.2. Technical Context

Elemento Canal Tecnología

Usuario ↔ Aplicación web

Navegador web

HTTP/HTTPS, TypeScript/React

Aplicación web ↔ API

Peticiones HTTP

JSON

Aplicación web ↔ Módulo de lógica

Servicios web

HTTP/HTTPS + JSON

Bot externo ↔ API

Peticiones HTTP

JSON

3.3. Mapping Input/Output to Channels

Entrada/Salida Canal

Movimiento del usuario

Agente de usuario (HTTP)

Visualización del tablero

Agente de usuario (HTTP)

Petición de jugada (bot)

API HTTP (JSON)

Respuesta del sistema

API HTTP (JSON)

Comunicación con módulo Rust

Servicios web (HTTP + JSON)

4. Solution Strategy

El sistema Yovi se ha diseñado siguiendo principios de modularidad y separación de responsabilidades. La estrategia general se basa en los siguientes aspectos:

4.1. Top-Level Decomposition

  • Frontend web (TypeScript/React): Se encarga de la interacción con los usuarios y la presentación del tablero de juego.

  • API de la aplicación: Expone los servicios para bots y comunicación interna entre frontend y módulo de lógica.

  • Módulo de lógica del juego (Rust): Calcula el estado de la partida, determina movimientos y comprueba victorias.

    • Se comunica mediante JSON utilizando la notación YEN.

  • Persistencia de datos (MySQL): Registro de usuarios, partidas e historial en la base de datos gestionada por la aplicación web.

4.2. Technology Decisions

  • Se utiliza TypeScript con React para la web por su tipado estático y facilidad de mantenimiento.

  • Se utiliza Rust para la lógica del juego por su rendimiento y seguridad.

  • Se usa JSON + notación YEN para comunicar los módulos y con los bots.

  • La API está basada en servicios web simples (HTTP) para facilitar la integración con bots y otros sistemas externos.

  • Se emplea Git con GitHub para control de versiones y seguimiento del proyecto.

4.3. Key Quality Goals

  • Usabilidad: Se prioriza una interfaz clara e intuitiva para el usuario.

  • Rendimiento: Respuesta rápida durante la partida y consultas al API.

  • Mantenibilidad: Código poco acoplado, cohesivo, modular y limpio que permite añadir estrategias o variantes del juego sin romper el sistema.

4.4. Group Decisions

  • El proyecto se desarrolla de forma colaborativa por el equipo indicado, con coordinación mediante reuniones telemáticas y/o presenciales, contacto por WhatsApp y el uso del GitHub.

  • Se sigue una metodología ágil ligera de tipo SCRUM como la aprendida en asignaturas pasadas como IPS.

  • La documentación sigue la plantilla arc42, pues es la indicada por el profesor.

5. Building Block View

Content

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

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

Motivation

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

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

Form

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

Hierarchy of building blocks

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

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

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

Further Information

See Building Block View in the arc42 documentation.

5.1. Whitebox Overall System

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

  • an overview diagram

  • a motivation for the decomposition

  • black box descriptions of the contained building blocks. For these we offer you alternatives:

    • use one table for a short and pragmatic overview of all contained building blocks and their interfaces

    • use a list of black box descriptions of the building blocks according to the black box template (see below). Depending on your choice of tool this list could be sub-chapters (in text files), sub-pages (in a Wiki) or nested elements (in a modeling tool).

  • (optional:) important interfaces, that are not explained in the black box templates of a building block, but are very important for understanding the white box. Since there are so many ways to specify interfaces why do not provide a specific template for them. In the worst case you have to specify and describe syntax, semantics, protocols, error handling, restrictions, versions, qualities, necessary compatibilities and many things more. In the best case you will get away with examples or simple signatures.

Diagrama

building block overview
Motivation

El sistema se descompone en servicios independientes (microservicios) para separar claramente la capa de presentación, la gestión de usuarios y la lógica principal del juego. Esta modularización mejora la mantenibilidad, la escalabilidad y permite el despliegue independiente de cada componente mediante contenedores Docker.

Contained Building Blocks
Name Responsibility

WebApp

Aplicación SPA que proporciona la interfaz de usuario y se comunica con los servicios backend.

Users Service

API REST responsable de la gestión de usuarios y lógica de autenticación.

Gamey Engine

Motor principal que implementa la lógica del juego y la gestión de bots.

Documentation

Documentación arquitectónica y técnica del sistema basada en arc42.
Important Interfaces

  • Comunicación REST HTTP entre WebApp y Users Service.

  • Comunicación REST HTTP entre WebApp y Gamey Engine.

  • Comunicación interna entre servicios mediante red Docker.

  • Intercambio de datos en formato JSON.

Insert your explanations of black boxes from level 1:

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

Name Responsibility

<black box 1>

 <Text>

<black box 2>

 <Text>

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

Name Responsibility

WebApp

Frontend SPA que proporciona la interfaz de usuario y comunica con los servicios backend.

Users Service

Backend REST responsable de la gestión de usuarios y autenticación.

Gamey Engine

Motor del juego que implementa la lógica y gestión de bots.

Documentation

Contiene la documentación arquitectónica y técnica del sistema.

5.1.1. WebApp

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

  • Purpose/Responsibility

  • Interface(s), when they are not extracted as separate paragraphs. This interfaces may include qualities and performance characteristics.

  • (Optional) Quality-/Performance characteristics of the black box, e.g.availability, run time behavior, …​.

  • (Optional) directory/file location

  • (Optional) Fulfilled requirements (if you need traceability to requirements).

  • (Optional) Open issues/problems/risks

Interfaces

  • Consume los endpoints REST expuestos por Users Service.

  • Se comunica con Gamey Engine para operaciones relacionadas con el juego.

  • Utiliza HTTP y JSON como protocolo y formato de intercambio.

Localización

  • /webapp

5.1.2. Users Service

Interfaces

  • Expone endpoints REST (por ejemplo, creación y consulta de usuarios).

  • Comunicación mediante HTTP y JSON.

Localización

  • /users

5.1.3. Gamey Engine

Interfaces

  • Expone endpoints HTTP para operaciones del juego.

  • Intercambio de datos estructurados en JSON.

Localización

  • /gamey

5.1.4. Documentation

Interfaces

  • Archivos estáticos en formato AsciiDoc.

Localización

  • /docs

5.2. Level 2

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

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

…​describes the internal structure of building block 1.

5.2.1. White Box WebApp

La WebApp sigue la estructura típica de una SPA basada en React.

Componente Responsabilidad

App.tsx

Punto de entrada de la aplicación y configuración de rutas.

Views

Componentes de nivel página.

Components

Componentes reutilizables de interfaz.

Services

Lógica de comunicación con APIs backend.
Interaction

  • Los componentes llaman a la capa Services.

  • Services realiza peticiones HTTP a los servicios backend.

5.2.2. White Box Users Service

API REST basada en Express estructurada por rutas y controladores.

Componente Responsabilidad

Server

Configuración e inicialización del servidor Express.

Routes

Definición de endpoints REST.

Controllers

Lógica de gestión de peticiones.

Models

Estructuras de datos de usuario.
Interaction

  • Las rutas delegan en los controladores.

  • Los controladores procesan la lógica y devuelven respuestas JSON.

5.2.3. White Box Gamey Engine

Proyecto en Rust estructurado siguiendo convenciones de Cargo.

Componente Responsabilidad

main.rs

Punto de entrada de la aplicación.

core

Lógica de reglas y estado del juego.

bot

Gestión y comportamiento de bots.

web

Capa de exposición HTTP.
Interaction

  • La capa web expone endpoints HTTP.

  • El módulo core ejecuta la lógica del juego.

  • El módulo bot integra comportamiento automatizado.

5.3. Level 3

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

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

Specifies the internal structure of building block x.1.

5.3.1. White Box Gamey Engine Core

El módulo core encapsula las reglas del juego y la gestión del estado.

  • Representación del estado del juego.

  • Validación de reglas.

  • Transiciones de estado.

  • Gestión de errores.

    Responsabilidad

    Garantizar la ejecución determinista de la lógica del juego de forma independiente a la interfaz web.

5.3.2. White Box WebApp Services Layer

Capa encargada de encapsular toda la comunicación HTTP.

  • Cliente de API.

  • Llamadas fetch/axios.

  • Gestión de errores.

    Responsabilidad

    Desacoplar los componentes de interfaz de los detalles de comunicación con el backend.

6. Runtime View

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. Resgistro del usuario

Caso

  • El usuario entra en la página web e inicia el proceso de registrarse para poder echar unas partidas.

    • La WebApp envía los datos del formulario al Users Service para validación y creación de la cuenta.

    • Users Service valida los datos, crea al usuario y devuelve la confirmación.

Registro de Usuario

6.2. Partida a Y

Caso

  • El usuario comienza una nueva partida.

    • La WebApp solicita al Gamey Engine que cree una nueva sesión de juego.

    • Gamey Engine inicializa el estado de la partida y registra los bots necesarios.

    • Gamey Engine devuelve a la WebApp el estado inicial de la partida.

    • La WebApp muestra al usuario el tablero o interfaz de juego lista para interactuar.

Diagrama de secuencia representativo:

Inicio de Partida

7. Deployment View

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

<Overview Diagram>

deployment overview
Motivation

La infraestructura usa una máquina virtual en Azure que ejecuta Docker para aislar y contener los servicios. Esto permite un control completo sobre la ejecución de contenedores, facilita el despliegue reproducible y permite escalar cada contenedor independientemente en la misma VM. Azure SQL Database gestiona la persistencia de datos.

Quality and/or Performance Features

  • Contenedores aislados mediante Docker dentro de la VM.

  • Fácil gestión de actualizaciones y despliegues mediante CI/CD.

  • Red interna de baja latencia entre contenedores.

  • Persistencia gestionada con Azure SQL Database (replicación y backups automáticos).

  • Seguridad: firewall de VM y conexión segura a base de datos.

Mapping of Building Blocks to Infrastructure
Bloque de Construcción Elemento de Infraestructura

WebApp

Contenedor Docker dentro de la VM Azure

Users Service

Contenedor Docker dentro de la VM Azure

Gamey Engine

Contenedor Docker dentro de la VM Azure

Base de Datos

MySQL Database

7.2. Infrastructure Level 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. Docker Host en VM Azure

Diagrama:

Docker Host Deployment

Todos los servicios backend y frontend se ejecutan en contenedores Docker sobre la misma VM. Cada contenedor está aislado, puede reiniciarse independientemente y comparte la red interna para comunicación rápida entre servicios.

8. 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. Modelo de Dominio

El sistema sigue un modelo de dominio centrado en la separación de responsabilidades: * Usuarios: gestión de cuentas, autenticación y autorización. * Juego: lógica de reglas, estado del juego y comportamiento de bots. * Interacción Web: comunicación entre frontend y backend mediante APIs REST.

Este modelo asegura consistencia en todo el sistema y permite mantener la integridad conceptual entre los diferentes servicios.

8.2. Experiencia de Usuario (UX)

  • La interfaz WebApp sigue el patrón SPA (Single Page Application) para ofrecer fluidez y rapidez.

  • Navegación intuitiva mediante rutas y vistas organizadas.

  • Formularios de registro y login que validan datos antes de enviarlos al backend.

  • Mensajes de error y éxito consistentes en toda la aplicación.

8.3. Seguridad y Autenticación

  • Gestión de autenticación en Users Service con credenciales básicas.

  • Comunicación segura mediante HTTPS (recomendado en despliegues reales).

  • Validación de datos de entrada en frontend y backend para evitar errores o exploits comunes.

  • Roles de usuario potencialmente diferenciados para acceso a distintas funcionalidades del juego.

8.4. Patrones de Arquitectura y Diseño

  • Arquitectura modular por servicios:

  • WebApp: presentación.

  • Users Service: backend REST.

  • Gamey Engine: lógica del juego.

  • Separación de responsabilidades para facilitar mantenimiento y despliegue independiente.

  • Uso de MVC simplificado en Users Service (Rutas → Controladores → Modelos).

  • Patrón cliente‑servidor para comunicación WebApp ↔ Backend.

  • Contenerización con Docker para aislar servicios y garantizar reproducibilidad.

8.5. Detalles Técnicos (“Under-the-hood”)

  • WebApp utiliza React + TypeScript + Vite.

  • Users Service implementado en Node.js + Express.

  • Gamey Engine implementado en Rust, siguiendo estructura modular (core, bot, web).

  • Comunicación entre servicios mediante JSON sobre HTTP.

  • Docker Compose como orquestador de los contenedores para facilitar despliegue local y pruebas.

8.6. Conceptos de Desarrollo

  • Uso de npm y Cargo para gestión de dependencias y scripts de compilación.

  • Estructura de carpetas consistente para mantener claridad y escalabilidad.

  • Pruebas unitarias básicas en frontend y backend.

  • Separación de configuración y código para facilitar cambios de entorno.

8.7. Conceptos Operativos

  • Cada servicio corre de manera independiente en contenedores Docker.

  • Red interna de Docker para comunicación entre servicios.

  • Posibilidad de despliegue independiente de WebApp, Users Service o Gamey Engine.

  • Logs y errores manejados por cada servicio de forma local; integrable con sistemas de logging centralizados en el futuro.

9. Architecture Decisions

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. MySQL como BBDD del proyecto

Estado

Aceptada.

Contexto

Se requiere un sistema de persistencia para almacenar los datos de los usuarios, partidas y estado del juego. La solución debe ser flexible, integrarse correctamente con el ecosistema tecnológico elegido y facilitar el desarrollo y despliegue del proyecto.

Alternativas consideradas

  • Otras bases de datos relacionales.

  • Bases de datos no relacionales.

Justificación

Modelo relacional

MySQL permite estructurar los datos en tablas normalizadas, ideal para usuarios, partidas y relaciones entre entidades del juego.

Integridad de datos

Garantiza consistencia mediante claves primarias, foráneas y restricciones, evitando errores de duplicidad o pérdida de información.

Madurez y soporte

MySQL es estable, ampliamente documentado y compatible con la mayoría de frameworks y lenguajes backend.

Adopción del equipo de desarrollo

Es una tecnología que todo el equipo de desarrollador ha empleado en algún otro proyecto.

Rendimiento

Adecuado para cargas moderadas, asegurando tiempos de respuesta rápidos en operaciones comunes.

Facilidad de despliegue

Compatible con Docker y entornos cloud, lo que facilita levantar instancias de forma reproducible.
Consecuencias

  • Se adopta un esquema relacional que requiere planificación previa de las tablas y relaciones.

  • Cambios estructurales en el futuro pueden requerir migraciones más cuidadosas que en una base de datos NoSQL.

  • Se asegura integridad y consistencia de los datos, facilitando mantenimiento y auditorías.

9.2. Azure como infraestructura de despliegue (Máquina Virtual)

Estado

Aceptada.

Contexto

Se requiere un entorno donde desplegar la aplicación backend, la base de datos y los servicios asociados, garantizando disponibilidad, escalabilidad y acceso remoto seguro. La solución debe integrarse fácilmente con el ecosistema tecnológico del proyecto y permitir un despliegue sencillo y controlado.

Alternativas consideradas

  • AWS EC2.

  • Google Compute Engine.

  • Servidores on-premise.

  • Otros proveedores cloud.

Justificación

Adopción del equipo de desarrollo

Es una tecnología que todo el equipo de desarrollador ha empleado en algún otro proyecto.

Infraestructura como servicio (IaaS)

Azure permite crear y configurar máquinas virtuales con control total sobre el sistema operativo y el entorno de ejecución.

Escalabilidad

Posibilidad de aumentar recursos (CPU, RAM, almacenamiento) según crezcan las necesidades del proyecto.

Alta disponibilidad

Integración con servicios de red, copias de seguridad y monitorización dentro del ecosistema Azure.

Integración con el entorno cloud

Compatible con Docker, CI/CD y otros servicios gestionados del ecosistema Azure.

Seguridad

Configuración de redes virtuales, grupos de seguridad y control de acceso basado en roles.

Flexibilidad

Permite alojar tanto la aplicación como la base de datos en un mismo entorno o separarlos en distintas máquinas virtuales según necesidades.
Consecuencias

  • Se asume la responsabilidad de la administración del sistema operativo, actualizaciones y configuración del servidor.

  • Puede implicar costes variables en función del uso de recursos y tiempo de ejecución.

  • Ofrece mayor control y personalización frente a soluciones PaaS, a cambio de una mayor gestión técnica.

  • Facilita el escalado futuro y la integración con otros servicios del ecosistema Azure.

10. Quality Requirements

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

quality tree
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

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.

Atributo Escenario Comportamiento esperado

Usabilidad

Un usuario accede por primera vez a la aplicación, sin conocimiento de la misma ni del juego, y comienza una partida.

El usuario entiende las reglas básicas y puede iniciar y jugar una partida sin necesidad de instrucciones externas.

Rendimiento

Un jugador realiza una acción durante la partida (por ejemplo, realizar un movimiento).

El sistema procesa la acción y actualiza el estado del juego inmediatamente o en un muy corto periodo de tiempo.

Mantenibilidad

Un desarrollador necesita añadir una nueva funcionalidad o modificar una regla del juego.

El cambio puede implementarse sin afectar a otras partes del sistema y sin introducir errores colaterales.

Fiabilidad

Durante una partida, el sistema enfrenta situaciones inesperadas (por ejemplo, entrada inválida, pérdida de conexión o error interno).

El sistema maneja el error de forma controlada, no se bloquea ni pierde el progreso del usuario, mantiene la coherencia del estado del juego y permite continuar o recuperarse sin corrupción de datos.

11. Risks and Technical Debts

Risk / Technical Debt Impact Mitigation / Notes

Complejidad de la integración Frontend ↔ Backend

La comunicación JSON/YEN entre TypeScript/React y Rust puede generar errores de formato o inconsistencias.

Definir y validar estrictamente el formato YEN, comprobar e integrar todos los endpoints.

Evolución de las estrategias de juego

Medio: Añadir nuevas estrategias puede romper el motor de juego si no se diseña modularmente.

Diseñar motor de juego con interfaces claras; documentar cómo añadir nuevas estrategias.

Gestión de concurrencia en partidas multiusuario

Usuarios jugando simultáneamente pueden generar conflictos de estado e incoherencias.

Implementar control de acceso a partidas; usar bloqueos o transacciones en la persistencia.

Dependencia de bots externos

Bots externos pueden enviar datos inválidos o malformateados.

Validación estricta de entradas y manejo de errores; definir contratos claros en la API.

Deuda técnica en el frontend

Código TypeScript con React puede no ser modular o adquierir acoplamiento que dificulte el mantenimiento o futuros cambios.

Revisiones de código, pruebas unitarias y refactorizaciones periódicas.

Escalabilidad del backend

El API y la lógica deben soportar múltiples partidas simultáneas.

Planificar escalabilidad desde el inicio; monitorización y pruebas de carga.

Compatibilidad con variantes futuras del juego

Añadir variantes como Master Y o Holey Y puede requerir cambios en la lógica.

Diseñar motor de juego flexible y documentar cómo extender reglas.

12. Glossary

Term Definition

Yovi

Nombre del proyecto, plataforma web para jugar al juego Y y permitir la interacción de usuarios y bots.

Juego Y

Juego de tablero abstracto en el que dos jugadores intentan conectar lados opuestos del tablero siguiendo reglas específicas.

Notación YEN

Formato JSON utilizado para representar el estado de una partida, incluyendo tamaño de tablero, turno, disposición de jugadores y layout.

Bot

Programa que juega automáticamente contra la aplicación o contra otros usuarios, usando la API.

API (Application Programming Interface)

Conjunto de servicios web que permite la interacción de bots o módulos externos con la aplicación.

Frontend

Interfaz web implementada en TypeScript con React que permite a los usuarios jugar y consultar su historial.

Módulo de Lógica (Rust)

Componente encargado de calcular movimientos válidos, verificar victorias y sugerir estrategias usando la notación YEN.

Persistencia (MySQL)

Componente encargado de almacenar información de usuarios, partidas y estadísticas en la base de datos.

Estrategia

Algoritmo que define cómo el bot decide su siguiente movimiento en una partida.

Partida

Instancia de un juego Y entre dos jugadores, humanos o bots, con un tablero y un historial de movimientos.

Historial

Datos calculados sobre los jugadores y sus partidas, incluyendo victorias, derrotas y ranking.