About arc42

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

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

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

Note

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

1. Introducción

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

  • underlying business goals,

  • essential features,

  • essential functional requirements,

  • quality goals for the architecture and

  • relevant stakeholders and their expectations

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

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

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

1.1. Resumen de Requisitos

Contents

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

Motivation

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

Form

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

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

Further Information

See Introduction and Goals in the arc42 documentation.

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

Prioridad Requisito

1

Debe soportar el modo de juego clásico que enfrenta a un jugador con la máquina.

2

Debe estar desplegada en la nube y ser públicamente accesible a través de la web.

3

Debe contar con una interfaz web que permita a los usuarios jugar al juego Y.

4

Debe ofrecer varias estrategias de juego que los usuarios puedan seleccionar junto a un nivel de dificultad para la máquina.

5

Debe proporcionar un sistema de registro y autenticación, que permita a los usuarios consultar sus estadísticas e histórico de participación en el sistema.

6

Debe exponer una API que permita el acceso y la gestión de la información de los usuarios.

7

Debe posibilitar que se juege a través de la API, ya sea para implementaciones públicas o a través de bots.

1.2. Objetivos de Calidad

Contents

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

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

Categories of Quality Requirements
Motivation

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

Form

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

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

Prioridad Objetivo Descripción

Alta

Interoperabilidad

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

Alta

Mantenibilidad

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

Alta

Fiabilidad

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

Media

Escalabilidad

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

Media

Usabilidad

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

1.3. Grupos de Interés

Contents

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

  • should know the architecture

  • have to be convinced of the architecture

  • have to work with the architecture or with code

  • need the documentation of the architecture for their work

  • have to come up with decisions about the system or its development

Motivation

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

Form

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

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

Grupo Interés

Usuarios finales

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

Bots externos

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

Equipo de desarrollo

Trabajar con una arquitectura clara, modular y mantenible.

Profesores

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

Micrati

Disponer de un producto que cumpla con los requisitos deseados.

2. Restricciones de la Arquitectura

Contents

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

Motivation

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

Form

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

Further Information

See Architecture Constraints in the arc42 documentation.

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

  • La aplicación web y la API deben desarrollarse en TypeScript, mientras que la lógica de juego debe desarrollarse en Rust.

  • El módulo de lógica de juego debe ofrecer un servicio web básico accesible desde la aplicación web.

  • Los módulos de aplicación y lógica de juego deben comunicarse a través de mensajes JSON, representando el estado de juego en notación YEN.

  • La aplicación web debe estar desplegada públicamente y la API documentada, permitiendo la interacción con bots.

  • La base de código debe mantenerse en un repositorio bien gestionado y se debe cumplir con los plazos de entrega propuestos.

3. Contexto y Alcance

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

3.1. Contexto de negocio

Actores y sistemas externos principales:

  • Jugador (usuario principal): interactúa a través del navegador con el módulo webapp para registrarse, autenticarse y jugar.

  • Administrador (usuario moderador): interactúa con el navegador para gestionar configuración del sistema y moderación de usuarios.

  • Navegador / Cliente Web: transporte HTTP(S) entre usuario y webapp.

  • Registro de contenedores: almacena y despliega imágenes Docker del ecosistema.

  • Persistencia: servicio de base de datos que almacena información de usuarios y registros de partidas (datos de juego, puntuaciones e historial).

3.2. Contexto técnico

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

Canales y protocolos previstos:

  • HTTP/HTTPS (REST + JSON): canal primario entre webapp, users y gamey.

  • Docker / Docker Compose: empaquetado y orquestación local para desarrollo y pruebas.

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

  • Prometheus (scrape/HTTP): recolecta métricas expuestas por los servicios.

  • Grafana: visualización y dashboards basados en datos de Prometheus y otras fuentes.

4. Estrategia de la Solución

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

  • gamey: Backend del juego, implementado en Rust. Responsable del motor de partidas y reglas del juego, con endpoints para manejar partidas.

  • users: Servicio de gestión de usuarios, implementado en Node.js. Encargado del manejo de usuarios y autenticación.

  • webapp: Frontend, implementado en React. Implementación de interfaces gráficas de usuario que permiten la comunicación del usuario con el resto de la aplicación.

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

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

5. Building Block View

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

5.1. Whitebox Overall System

Overview Diagram

Overview Diagram
Motivation

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

  • webapp: interfaz de usuario

  • users: microservicio REST

  • gamey: motor de juego en Rust

  • Stack de monitorización

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

Contained Building Blocks
Name Responsibility

webapp

Interfaz de usuario desarrollada en React.

users

Microservicio Node.js para registro de usuarios.

gamey

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

Monitoring Stack

Monitorización con Prometheus y Grafana.
Important Interfaces

  • HTTP REST entre webapp y users

  • HTTP REST entre cliente y gamey

  • Endpoint /metrics para Prometheus

  • Comunicación interna mediante red Docker

5.1.1. webapp

Purpose/Responsibility

Gestiona la interacción con el usuario y realiza llamadas HTTP al backend.

Interface(s)

  • POST /createuser

  • Solicitudes al motor gamey

Directory/File Location

webapp/

5.1.2. users

Purpose/Responsibility

Servicio REST que procesa registros de usuario y expone métricas.

Interface(s)

  • POST /createuser

  • GET /metrics

Directory/File Location

users/

5.1.3. gamey

Purpose/Responsibility

Implementa la lógica del juego y los algoritmos de decisión.

Interface(s)

  • API HTTP (modo servidor)

  • CLI

  • Biblioteca interna Rust

Directory/File Location

gamey/

5.1.4. Monitoring Stack

Purpose/Responsibility

Recolecta y visualiza métricas del sistema.

Interface(s)

  • Scraping /metrics

Location

docker-compose.yml

5.2. Level 2

5.2.1. White Box webapp

Webapp Internal Structure
Motivation

Se detalla la estructura interna por ser el punto de entrada del sistema.

Name Responsibility

main.tsx

Punto de entrada React.

App.tsx

Componente raíz.

RegisterForm.tsx

Gestión del formulario y llamadas HTTP.

5.2.2. White Box gamey

Gamey Internal Structure
Motivation

Contiene la lógica más compleja del sistema.

Name Responsibility

main.rs

Selección de modo de ejecución.

lib.rs

Organización modular.

core/game.rs

Lógica del juego.

bot

Algoritmos de movimiento.

5.3. Level 3

5.3.1. White Box core/game.rs

Motivation

Contiene el núcleo algorítmico del sistema.

Name Responsibility

GameY

Estado completo de partida.

board_map

Representación del tablero.

history

Historial de movimientos.

Union-Find

Detección eficiente de conectividad.

available_cells

Movimientos válidos.

6. Runtime View

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

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

6.1. Runtime Scenario 1: Registro de usuario

6.1.1. Descripción del escenario

  1. El usuario accede a la webapp desde el navegador.

  2. Introduce su username en el formulario.

  3. El componente RegisterForm ejecuta la función handleSubmit.

  4. La webapp envía una petición HTTP POST a users (/createuser).

  5. El servicio users procesa la petición y simula 1 segundo de latencia.

  6. users devuelve un mensaje JSON de bienvenida.

  7. La webapp actualiza su estado interno.

  8. El mensaje se muestra en la interfaz.

6.1.2. Diagrama de secuencia

Sequence Diagram - User Registration

6.1.3. Aspectos arquitectónicamente relevantes

  • Comunicación síncrona mediante HTTP REST.

  • Separación clara entre frontend y backend.

  • Gestión asíncrona del estado en React.

  • Exposición de métricas Prometheus por parte de users.

  • Uso de CORS para permitir comunicación entre servicios.

6.2. Runtime Scenario 2: Solicitud de jugada al motor gamey

6.2.1. Descripción del escenario

  1. El cliente (webapp o cliente de prueba) solicita una jugada al motor gamey.

  2. gamey recibe la petición HTTP.

  3. Se ejecuta la lógica del bot dentro de core/game.rs.

  4. El motor calcula una jugada válida.

  5. Se devuelve la jugada en formato JSON.

  6. El cliente integra la jugada en la interfaz o en la simulación.

6.2.2. Diagrama de secuencia

Sequence Diagram - Game Move Request

6.2.3. Aspectos arquitectónicamente relevantes

  • Separación entre capa HTTP y lógica de dominio.

  • Uso de estructuras eficientes (Union-Find).

  • Motor desacoplado y reutilizable (CLI o servidor).

  • Servicio independiente del frontend.

6.3. Runtime Scenario 3: Inicio del sistema mediante Docker Compose

6.3.1. Descripción del escenario

  1. El operador ejecuta docker-compose up --build.

  2. Docker construye las imágenes de webapp, users y gamey.

  3. Se levantan los contenedores correspondientes.

  4. Se crea la red Docker interna.

  5. users comienza a exponer métricas en /metrics.

  6. Prometheus comienza a recolectarlas.

  7. Grafana permite visualizar las métricas.

6.3.2. Diagrama de secuencia

Sequence Diagram - System Startup

6.3.3. Aspectos arquitectónicamente relevantes

  • Infraestructura reproducible y automatizada.

  • Aislamiento mediante contenedores.

  • Monitorización integrada.

  • Comunicación interna segura mediante red Docker.

6.4. Runtime Scenario 4: Fallo del servicio users

6.4.1. Descripción del escenario

  1. El usuario intenta registrarse.

  2. La webapp envía la petición a users.

  3. El servicio users no está disponible (contenedor caído).

  4. La petición falla por timeout o error de red.

  5. La webapp muestra un mensaje de error.

  6. Prometheus deja de recibir métricas del servicio.

6.4.2. Diagrama de secuencia

Sequence Diagram - Users Service Failure

6.4.3. Aspectos arquitectónicamente relevantes

  • Manejo explícito de errores en el frontend.

  • Arquitectura desacoplada que evita fallos en cascada.

  • Detección de fallos mediante monitorización.

  • El sistema sigue parcialmente operativo.

7. Vista de Despliegue

Contenido

La vista de despliegue describe:

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

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

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

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

Motivación

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

Forma

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

  • UML ofrece diagramas de despliegue para expresar esa vista. Úsalos, probablemente con diagramas anidados, cuando tu infraestructura sea más compleja.

  • Si tus partes interesadas (stakeholders de hardware) prefieren otro tipo de diagramas en lugar de un diagrama de despliegue, que utilicen cualquiera que pueda mostrar nodos y canales de la infraestructura.

Más Información

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

7.1. Infraestructura Nivel 1

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

  • distribución de un sistema a múltiples ubicaciones, entornos, ordenadores, procesadores, …, así como las conexiones físicas entre ellos

  • justificaciones o motivaciones importantes para esta estructura de despliegue

  • características de calidad y/o rendimiento de esta infraestructura

  • mapeo de artefactos de software a elementos de esta infraestructura

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

Diagrama de Despliegue
Motivación

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

  • Escalabilidad Automática: Oracle permite escalar según la carga de usuarios sin intervención manual.

  • Seguridad: Oracle proporciona cifrado de datos.

  • Flexibilidad: MongoDB es ideal ya que las entidades cambiaran con el tiempo.

  • Polimorfismo Sencillo: MongoDB permite modelas fácilmente el cambio entre entidades.

  • Rendimiento Excelente: MongoDB es óptimo para registros rápidos de eventos e interacciones frecuentes.

Características de Calidad y/o Rendimiento

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

  • Escalabilidad

  • Rendimiento

  • Seguridad

  • Eficiencia

Mapeo de Bloques de Construcción a Infraestructura

<En este punto de desarrollo del proyecto, este apartado no se puede desarrollar>

7.2. Infraestructura Nivel 2

Aquí puedes incluir la estructura interna de (algunos) elementos de infraestructura del nivel 1.

Por favor copia la estructura del nivel 1 para cada elemento seleccionado.

7.2.1. <Elemento de Infraestructura 1>

<En este punto de desarrollo del proyecto, este apartado no se puede desarrollar>

8. Conceptos Transversales

Contenido

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

  • modelos, especialmente modelos del dominio

  • patrones de arquitectura o de diseño

  • reglas para el uso de tecnologías específicas

  • decisiones principales, a menudo técnicas, de carácter general (= transversal)

  • reglas de implementación

Motivación

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

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

Forma

La forma puede variar:

  • documentos de concepto con cualquier tipo de estructura

  • extractos de modelos transversales o escenarios usando notaciones de las vistas de arquitectura

  • implementaciones de ejemplo, especialmente para conceptos técnicos

  • referencias al uso típico de frameworks estándar (por ejemplo, usar Hibernate para el mapeo objeto/relacional)

Estructura

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

  • Conceptos de dominio

  • Conceptos de experiencia de usuario (UX)

  • Conceptos de seguridad y protección

  • Patrones de arquitectura y de diseño

  • “Bajo el capó”

  • Conceptos de desarrollo

  • Conceptos operativos

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

Posibles temas para conceptos transversales
Más Información

Consulta Concepts en la documentación de arc42.

8.1. Concepto de Dominio

Diagrama de Despliegue

  • Usuarios: Tendrán nombre, nombre de usuario, contraseña, además de las estadísticas que irán variando según usen YOVI. Representan a los usuarios reales.

  • Bots: En caso de que un usuario no juegue contra otra persona real, jugará contra un bot, que tendrá nombre y dificultad.

  • JuegosY: Juego principal, con modo, jugadores y un resultado que se dará una vez su estado sea finalizado.

8.2. Conceptos de Experiencia de Usuario

La experiencia del usuario será una de los pilares de toda la aplicación a desarrollar. Se ofrecerá en versión Web la posibilidad de jugar a diferentes juegos basados en el juego Y.

8.3. Conceptos de Seguridad

La seguridad de la aplicación es un tema que aún no se ha indagado dentro del desarrollo de la aplicación. Muy seguramente, haya un sistema de inicio de sesión en el que gire todo este apartado.

8.4. Conceptos de Arquitectura

Los conceptos de arquitectura serán más indigados en el siguiente apartado. De forma superficial, la arquitectura está basada en microservicios unidos para comprender toda la aplicación.

8.5. Conceptos de Desarrollo

La aplicación se basará en su testing, integración y deployment. En este apartado no se puede indagar mucho ya que actualmente la aplicación únicamente de ha desplegado.

El desplegue se realizará con Docker, donde se empaquetará la aplicación en un contenedor estandarizado donde se facilita un despliegue rápido, consistente y reproducible en cualquier entorno.

9. Decisiones de Arquitectura

Contenido

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

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

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

Motivación

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

Forma

Varias opciones posibles:

  • ADR (Architecture Decision Record, Registro de Decisión de Arquitectura) para cada decisión importante :contentReference[oaicite:2]{index=2}

  • Lista o tabla, ordenada por importancia y consecuencias :contentReference[oaicite:3]{index=3}

  • Más detallado en forma de secciones separadas por cada decisión :contentReference[oaicite:4]{index=4}

Más Información

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

En este apartado se hablará de la motivación y las consecuencias de cada decisión arquitectura que se ha tomado en el desarrollo del proyecto. Por tanto, no se contemplarán las decisiones tomadas por el equipo docente de la asignatura. mongodb

9.1. Máquina Ubuntu en la Nube de Oracle

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

  • Estabilidad: Ubuntu es conocida por ser una distribución robusta ampliamente usada en entornos de producción.

  • Compatabilidad: A sabiendas que el proyecto desarrollo comprenderá de alguna que otra API, esta decisión minimizará problemas de compatibilidad ya que una gran parte de estos microservicios funcionan de forma óptima en Ubuntu.

  • Costes: Las máquinas Linux en Oracle al no incluir licencias adicionales resultan más baratas que otro tipo de máquinas.

  • Control: Una máquina virtual Ubuntu permite instalar software personalizado además de ofrecer control total del sistema operativo.

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

  • Mayor Responsabilidad Operativa: Al tener control total del sistema operativo, la administración recae sobre el equipo.

  • Seguridad: La gestión de la seguridad recae sobre los desarrolladores.

9.2. Base de Datos en MongoDB

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

  • Flexibilidad: MongoDB es ideal para modelos que evolucionan, contienen relaciones flexibles o estructuras variables, como es el caso.

  • Alto Rendimiento: MongoDB está optimizado para sistemas en tiempo real.

  • Resilencia Integrada: Los Backups son automáticos

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

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

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

]["Á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

Escenario Descripción

Escenario 1 - Disponibilidad

El sistema debe estar disponible el 95% del tiempo. El sistema permite a los usuarios acceder a sus funcionalidades en cualquier momento, excepto durante las ventanas de mantenimiento programadas.

Escenario 2 - Rendimiento

El sistema debe responder a las solicitudes de los usuarios en menos de 2 segundos. Esto asegura una experiencia de usuario fluida y eficiente, incluso durante períodos de alta demanda.

Escenario 3 - Seguridad

El sistema debe proteger los datos de los usuarios. Esto asegura que la información personal y sensible de los usuarios esté protegida contra accesos no autorizados, garantizando la confidencialidad y la integridad de los datos.

Escenario 4 - Escalabilidad básica

El sistema debe ser capaz de manejar un aumento del 50% en el número de usuarios sin degradar el rendimiento. Esto asegura que el sistema pueda crecer y adaptarse a un número creciente de usuarios sin comprometer la calidad del servicio.
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 deuda técnica

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

Riesgo Descripción Impacto Probabilidad Mitigación

Uso combinado de Rust, Node.js, React y TypeScript.

La utilización de varias tecnologías con paradigmas distintos incrementa la complejidad del desarrollo y mantenimiento del sistema. Pueden generar una curva de aprendizaje elevada y aumentar el esfuerzo necesario para depurar errores entre capas.

Medio

Media

Formación continua de los desarrolladores en todas las tecnologías involucradas.

Dependencia de librerías externas (npm y crates).

El sistema depende de paquetes externos que pueden contener vulnerabilidades, quedar sin mantenimiento o introducir cambios incompatibles en versiones futuras. Esto podría afectar a la estabilidad y seguridad del sistema.

Medio

Baja

Seleccionar librerías confiables y mantenerlas actualizadas. Revisar dependencias antes de actualizaciones mayores.

Mala comunicación entre los integrantes del equipo.

La falta de comunicación efectiva puede llevar a malentendidos sobre los requisitos, diseño y tareas, lo que podría resultar en retrasos, errores o trabajo duplicado.

Alto

Baja

Establecer canales de comunicación claros y fomentar reuniones regulares para sincronizar al equipo.

11.2. Deuda técnica

Deuda técnica

Descripción

Impacto

Probabilidad

Mitigación

Código no documentado o mal documentado.

La falta de documentación clara y actualizada dificulta la comprensión del código, lo que puede ralentizar el desarrollo y aumentar el riesgo de errores al modificar el sistema.

Medio

Media

Establecer estándares de documentación y revisarlos regularmente.

Implementación inicial sin optimización.

La implementación inicial del sistema puede no estar optimizada para rendimiento o escalabilidad, lo que podría requerir refactorización significativa en el futuro para cumplir con los requisitos de rendimiento.

Medio

Alta

Planificar iteraciones de mejora continua y refactorización a medida que se identifican cuellos de botella.

Gestión básica de autenticación y autorización.

La implementación inicial de la autenticación y autorización puede ser básica, lo que podría no cumplir con los requisitos de seguridad a medida que el sistema evoluciona.

Alto

Media

Planificar mejoras en la gestión de autenticación y autorización a medida que se identifican nuevas amenazas y requisitos de seguridad.

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

JSON

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

Notación YEN

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

API

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

Bots

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

Microservicio REST

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

Frontend

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

Backend

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

Motor del juego

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