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

Este proyecto consiste en el desarrollo de YOVI, un sistema que permite jugar partidas del juego Y a través de una aplicación web y un módulo de lógica en Rust. La aplicación web permite a los usuarios jugar, consultar estadísticas y usar un API para interacción con bots. El módulo de Rust verifica partidas y sugiere movimientos. El sistema soporta diferentes estrategias, tamaños de tablero y modalidades de juego.

Esta documentación ha sido creada por Andrea, Sara, Sergio y Jorge como parte de las prácticas del curso ASW de la Universidad de Oviedo.

Describe los requisitos relevantes y los factores impulsores que el equipo de arquitectura y desarrollo debe tener en cuenta.

Estos incluyen:

  • los objetivos de negocio subyacentes,

  • las funcionalidades esenciales,

  • los requisitos funcionales clave,

  • los objetivos de calidad de la arquitectura y

  • los stakeholders relevantes y sus expectativas.

1.1. Descripción de los requisitos

Registro de usuarios

  • RU1. El sistema debe permitir registrarse a un usuario no identificado.

    • RU1.1. El sistema solicitará los datos necesarios al usuario no identificado para registrarse.

      • RU1.1.1. Solicitará un nombre de usuario (dato obligatorio).

      • RU1.1.2. Solicitará una contraseña (dato obligatorio).

  • RU2. El sistema registrará al usuario no registrado.

    • RU2.1. El sistema guardará en la BBDD al usuario nuevo y todos sus datos asociados.

    • RU2.2. El sistema enviará una confirmación de que el registro del usuario no registrado se ha realizado correctamente.

Identificación de usuarios

  • IU1. El sistema debe permitir autenticarse a un usuario registrado no identificado.

    • IU1.1. El sistema solicitará los siguientes datos para su identificación.

      • IU1.1.1. Solicitará un nombre de usuario (dato obligatorio).

      • IU1.1.2. Solicitará una contraseña (dato obligatorio).

  • IU2. El sistema permitirá al usuario registrado cerrar sesión de forma segura, devolviendo la aplicación a la pantalla de inicio de sesión.

Gestión de partidas

  • GP1. El sistema debe permitir a un usuario registrado iniciar una nueva partida.

    • GP1.1. El sistema solicitará los siguientes datos para iniciar una nueva partida.

      • GP1.1.1. Solicitará el tamaño del tablero (dato obligatorio).

      • GP1.1.2. Solicitará la estrategia del bot (dato obligatorio).

    • GP1.2. El sistema deberá registrar y actualizar el estado de la partida durante el juego.

      • GP1.2.1. El usuario deberá poder realizar movimientos en la partida.

      • GP1.2.2. El usuario deberá poder consultar el estado actual de la partida.

      • GP1.2.3. El sistema deberá verificar la validez de los movimientos realizados por el usuario.

      • GP1.2.4. El sistema y el jugador deberán realizar movimientos en la partida.

      • GP1.2.5. El sistema deberá detectar el final de la partida y declarar un ganador.

      • GP1.2.6. El sistema deberá permitir al usuario deshacer el último movimiento realizado.

Gestión del historial de partidas

  • HP1. El sistema debe permitir a un usuario registrado consultar su historial de partidas.

    • HP1.1. El sistema deberá mostrar una lista con las partidas jugadas por el usuario.

    • HP1.2. El sistema deberá permitir al usuario consultar los detalles de una partida específica.

Contenido

Descripción breve de los requisitos funcionales, los factores impulsores y un extracto (o resumen) de los requisitos. Enlace a documentos de requisitos existentes (con número de versión e información sobre dónde encontrarlos).

Motivación

Desde el punto de vista de los usuarios finales, un sistema se crea o se modifica para mejorar el soporte de una actividad de negocio y/o mejorar la calidad.

Forma

Descripción textual breve, probablemente en formato tabular de casos de uso. Si existen documentos de requisitos, este resumen debería hacer referencia a ellos.

Mantén estos extractos lo más breves posible. Equilibra la legibilidad de este documento con la posible redundancia respecto a los documentos de requisitos.

Información adicional

Ver Introducción y Objetivos en la documentación de arc42.

1.2. Objetivos de calidad

Objetivo de Calidad Descripción

Rendimiento

El sistema debe responder rápidamente a las acciones del usuario y a las llamadas del API. El módulo Rust debe calcular el siguiente movimiento y validar partidas de manera eficiente.

Escalabilidad

El diseño del sistema debe permitir un crecimiento eficiente, asegurando que se puedan añadir nuevas variantes del juego, más usuarios, partidas simultáneas o bots sin afectar negativamente al rendimiento.

Seguridad

El sistema debe garantizar la protección de los datos de los usuarios, la autenticación segura, y controlar el acceso al API, evitando que bots o usuarios no autorizados manipulen partidas o estadísticas.

Mantenibilidad

El código debe ser modular, claro y bien documentado para facilitar nuevas modificaciones y mejoras. Se utilizarán buenas prácticas como reutilización de código, separación de responsabilidades y pruebas unitarias para garantizar la estabilidad del sistema.

Usabilidad

La interfaz web debe ser clara e intuitiva, permitiendo jugar, seleccionar estrategias, ver estadísticas y seguir el estado del tablero de forma sencilla. Se aplicarán principios de predictibilidad, coherencia visual y retroalimentación adecuada.

Operatividad

El sistema debe estar desplegado y accesible a través de la web, con integración y despliegue continuos, monitorización de servicios y disponibilidad garantizada para usuarios y bots.

Pruebas y calidad del software

Se deben implementar pruebas unitarias, de integración y end-to-end que garanticen que todas las funcionalidades, reglas del juego y estrategias funcionan correctamente, además de pruebas de carga para evaluar el rendimiento bajo uso intensivo.
Contenido

Los tres principales (máximo cinco) objetivos de calidad de la arquitectura cuyo cumplimiento es de mayor importancia para los stakeholders principales.

Nos referimos realmente a objetivos de calidad de la arquitectura. No deben confundirse con los objetivos del proyecto. No son necesariamente idénticos.

Considera esta visión general de posibles temas (basada en el estándar ISO 25010):

Categorías de requisitos de calidad
Motivación

Debes conocer los objetivos de calidad de tus stakeholders más importantes, ya que influirán en decisiones arquitectónicas fundamentales. Asegúrate de ser muy concreto con estas cualidades y evita palabras vacías. Si como arquitecto no sabes cómo se evaluará la calidad de tu trabajo…

Forma

Una tabla con los objetivos de calidad y escenarios concretos, ordenados por prioridades.

1.3. Stakeholders

Contenido

Visión general explícita de los stakeholders del sistema, es decir, todas las personas, roles u organizaciones que:

  • deben conocer la arquitectura,

  • deben ser convencidos por la arquitectura,

  • deben trabajar con la arquitectura o con el código,

  • necesitan la documentación de la arquitectura para su trabajo,

  • deben tomar decisiones sobre el sistema o su desarrollo.

Motivación

Debes conocer a todas las partes involucradas en el desarrollo del sistema o afectadas por él. De lo contrario, podrías llevarte sorpresas desagradables más adelante en el desarrollo.

Estos stakeholders determinan el alcance y el nivel de detalle de tu trabajo y de sus resultados.

Forma

Tabla con nombres de roles, nombres de personas y sus expectativas respecto a la arquitectura y su documentación.

Role/Name Contact Expectations

Cliente

Usuario de la aplicación

Seguridad, disponibilidad y cumplimiento de las normas

Bot

Usuario no humano

Eficiencia, rapidez, disponibilidad y compatibilidad

Compañía contratada

Micrati

Entrega a tiempo y alta claridad del proyecto

Equipo de desarrollo

El equipo yovi_es4d

Claridad de los requisitos, apoyo continuo del cliente y herramientas adecuadas

2. Restricciones de 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.

Esta sección se describen las restricciones técnicas, funcionales y de alcance que condicionan el diseño del sistema.

2.1. Restricciones técnicas

Restricción Explicación

Acceso web

La aplicación deberá estar desplegada y ser accesible a través de la Web.

División de subsistemas

El sistema estará dividido en una Aplicación Web (frontend + API) y un módulo de lógica del juego.

Implementación web

La aplicación web debe estar implementada en TypeScript.

Módulo lógico

El módulo de lógica del juego debe estar implementado en Rust.

Intercambio de información

El intercambio de información entre la aplicación web y el módulo en Rust debe realizarse usando mensajes JSON, siguiendo la notación YEN.

2.2. Restricciones organizacionales

Restricción Explicación

Equipo

El equipo de desarrollo está conformado por 4 personas.

Reuniones

Se organizará al menos una reunioón semanal durante las clases de laboratorio donde se discutirá el proyecto y posibles impedimentos.

Actas

Tras cada reunión se escribirá un acta donde se describen las decisiones que han sido tomadas

2.3. Restricciones Funcionales

Restricción Explicación

Versión clásica del juego Y

El sistema debe implementar la versión clásica del juego Y, respetando sus reglas originales.

Modo de juego: Humano vs Máquina

El juego debe permitir partidas de un jugador humano contra la máquina.

Tablero configurable

El tamaño del tablero debe ser configurable por el usuario o mediante parámetros del sistema.

Estrategias seleccionables

El juego contra la máquina debe ofrecer más de una estrategia, que podrán ser seleccionadas por el usuario.

Módulo Rust para lógica de juego

El módulo desarrollado en Rust debe ser capaz de comprobar si una partida ha sido ganada, según las reglas del juego.

2.4. Restricciones de API

Restricción Explicación

API externa para bots

El sistema debe exponer una API externa que permita a bots interactuar con el juego.

Gestión de usuarios y partidas

La API debe incluir endpoints para gestionar usuarios y partidas (crear, consultar, finalizar, etc.).

Método play

La API debe exponer un método play que: - Reciba al menos un parámetro position en notación YEN. - Devuelva el siguiente movimiento en notación YEN.

2.5. Restricciones de Usuario y Datos

Restricción Explicación

Registro de usuarios

Los usuarios deben poder registrarse en el sistema con credenciales únicas.

Histórico de participación

El sistema debe almacenar el histórico de participación de cada usuario, incluyendo: - Número de partidas jugadas. - Partidas ganadas y perdidas. - Estadísticas asociadas (por ejemplo, porcentaje de victorias, movimientos promedio, etc.).

3. Contexto y alcance

Contenido

El Contexto y Alcance, como su nombre indica, delimita tu sistema (es decir, tu alcance) respecto a todos sus interlocutores de comunicación (sistemas vecinos y usuarios, es decir, el contexto de tu sistema). De este modo, especifica las interfaces externas.

Si es necesario, diferencia el contexto de negocio (entradas y salidas específicas del dominio) del contexto técnico (canales, protocolos, hardware).

Motivación

Las interfaces de dominio y las interfaces técnicas con los interlocutores de comunicación son algunos de los aspectos más críticos de tu sistema. Asegúrate de comprenderlas completamente.

Forma

Varias opciones:

  • Diagramas de contexto

  • Listas de interlocutores de comunicación y sus interfaces

Más información

Consulta Context and Scope en la documentación de Arc42.

3.1. Contexto de negocio

Contenido

Especificación de todos los interlocutores de comunicación (usuarios, sistemas IT, etc.) con explicaciones de las entradas y salidas específicas del dominio o interfaces.

Opcionalmente, puedes añadir formatos específicos del dominio o protocolos de comunicación.

Motivación

Todos los interesados (stakeholders) deben comprender qué datos se intercambian con el entorno del sistema.

Forma

Cualquier tipo de diagrama que muestre el sistema como una caja negra y especifique las interfaces de dominio con los interlocutores de comunicación.

Alternativamente (o adicionalmente), puedes usar una tabla. El título de la tabla es el nombre de tu sistema y las tres columnas contienen:

  • Nombre del interlocutor de comunicación

  • Entradas

  • Salidas

Diagrama de contexto de negocio de yovi
Elemento Explicación detallada

Usuario

Actor externo que interactúa con el sistema.
Realiza acciones como iniciar sesión, jugar al juego, consultar el historial de partidas, entre otros.

UserDB

Base de datos de usuarios.
Gestiona registro, inicio y cierre de sesión.

Yovi

Aplicación principal para mostrar el juego.

3.2. Contexto técnico

Contenido

Interfaces técnicas (canales y medios de transmisión) que conectan tu sistema con su entorno. Además, un mapeo de las entradas/salidas específicas del dominio hacia los canales, es decir, una explicación de qué entrada/salida utiliza qué canal.

Motivación

Muchos interesados toman decisiones arquitectónicas basadas en las interfaces técnicas entre el sistema y su contexto. Especialmente los diseñadores de infraestructura o hardware definen estas interfaces técnicas.

Forma

Por ejemplo, un diagrama de despliegue UML que describa los canales hacia los sistemas vecinos, junto con una tabla de mapeo que muestre las relaciones entre los canales y las entradas/salidas.

Diagrama de contexto técnico de yovi
Elemento Explicación detallada

Usuario

Actor externo que interactúa con el sistema.
Se conecta a través del navegador web a la aplicación Yovi.

UserDB

Base de datos hecha en MondoDB, donde, por ahora, se guardan los datos de los usuarios.

Microservicios

Son los diferentes microservicios que componen el sistema, cada uno con su función específica.

3.2.1. Mapeo de entradas/salidas a canales

Canal específico Entrada Salida

Yovi microservicios

Cualquier petición o respuesta en formato HTTP.

Realiza peticiones HTTP tanto para redirigirse a servicios externos o para comunicarse con otros microservicios.

UserDB

Pueden ser consultas variadas, como pueden ser datos del usuario, o inserciones, como el registro de un nuevo usuario.

Los resultados de esas consultas o de las inserciones.

4. Estrategia de Solución

4.1. Deciciones tecnológicas

4.1.1. Frontend

  • Motivación: Se eligió JavaScript y React para el desarrollo del frontend, dado que permite construir interfaces interactivas y dinámicas, fundamentales en un juego donde la experiencia del usuario y la fluidez son prioritarias. React facilita la actualización eficiente de la interfaz ante acciones del jugador y mejora la mantenibilidad del código.

  • Objetivos de calidad: Usabilidad, Mantenibilidad, Integrabilidad

  • Restricciones clave: Debe funcionar correctamente en distintos navegadores y resoluciones.

4.1.2. Backend

  • Motivación:

    • Node.js con Express se utiliza para la gestión general del backend, como usuarios, estadísticas y almacenamiento, por su facilidad de desarrollo y ecosistema.

    • Rust se utiliza para la lógica del juego debido a su alto rendimiento, seguridad de memoria y capacidad para manejar múltiples jugadores simultáneamente de manera eficiente. Esto permite que las partidas funcionen en tiempo real sin problemas de rendimiento.

  • Objetivos de calidad: Rendimiento, Escalabilidad, Mantenibilidad, Seguridad

  • Restricciones clave: El backend general debe integrarse con el módulo de juego en Rust de manera fluida, garantizando que la experiencia del jugador no se vea afectada.

4.1.3. Base de Datos

  • Motivación: Se optó por MongoDB debido a su flexibilidad para almacenar datos de partidas, jugadores y progresos sin requerir un esquema rígido. Esto permite evolucionar el juego y agregar nuevas funcionalidades sin grandes cambios en la base de datos.

  • Objetivos de calidad: Escalabilidad, Mantenibilidad, Disponibilidad

  • Restricciones clave: Debe manejar grandes volúmenes de datos de partidas y jugadores de forma eficiente.

4.1.4. Contenedores

  • Motivación: Docker se eligió para estandarizar entornos de desarrollo, prueba y producción, asegurando que la aplicación funcione de manera consistente en todos ellos. Esto simplifica el despliegue y escalado del juego.

  • Objetivos de calidad: Escalabilidad, Disponibilidad, Mantenibilidad

  • Restricciones clave: Permitir replicar servicios según sea necesario sin complejidad adicional.

4.1.5. Infraestructura

  • Motivación: Se utiliza Microsoft Azure por su alta disponibilidad, facilidad para escalar recursos automáticamente según la demanda de jugadores y los servicios gestionados que facilitan el despliegue del backend y del motor de juego en Rust. Esto asegura que el juego se mantenga operativo incluso durante picos de tráfico.

  • Objetivos de calidad: Disponibilidad, Escalabilidad, Fiabilidad

  • Restricciones clave: Debe soportar múltiples jugadores simultáneos sin degradar la experiencia y garantizar que los servicios de Node.js y Rust funcionen de manera coordinada.

4.1.6. Modelado

  • Motivación: PlantUML se utiliza para crear diagramas de arquitectura y diseño debido a su simplicidad y la capacidad de generar diagramas automáticamente a partir de texto, lo que facilita la documentación continua y permite mantener actualizados los diagramas a lo largo del desarrollo.

  • Objetivos de calidad: Comunicación, Claridad, Consistencia

  • Restricciones clave:Los diagramas deben mantenerse actualizados durante el desarrollo.

4.1.7. Control de Versiones

  • Motivación: GitHub es la herramienta de control de versiones elegida debido a su popularidad y facilidad de uso, lo que permite la colaboración entre los miembros del equipo de desarrollo. Además, permite una gestión eficiente del código fuente, la revisión y el seguimiento de cambios, lo que es fundamental para mantener la calidad y la integridad del código.

  • Objetivos de calidad: Colaboración, Integridad, Mantenibilidad

  • Restricciones clave: Todos los desarrolladores deben poder acceder y colaborar eficientemente.

4.2. Decisiones sobre la Descomposición de Alto Nivel

4.2.1. Patrón Arquitectónico

  • Motivación: El sistema sigue un patrón de microservicios, donde cada componente del sistema se gestiona de manera independiente. El backend general corre en Node.js/Express, mientras que la lógica central del juego se ejecuta en un motor de Rust, especializado en manejar partidas y movimientos en tiempo real. Esta separación permite escalar cada parte según sea necesario y mantener la independencia de cada servicio.

  • Objetivos de calidad: Escalabilidad, Mantenibilidad, Flexibilidad, Rendimiento

  • Restricciones clave: Los microservicios deben comunicarse de manera eficiente (por ejemplo, Node.js con el motor Rust) sin generar dependencias críticas que puedan afectar la disponibilidad o rendimiento del juego.

4.2.2. Descomposición del Sistema

  • Motivación: El sistema se organiza en módulos que manejan la interfaz, la lógica del juego y el almacenamiento de datos. Esto facilita el mantenimiento y la expansión de funcionalidades a futuro.

  • Objetivos de calidad: Escalabilidad, Mantenibilidad, Flexibilidad

  • Restricciones clave: La comunicación entre módulos debe ser clara y sin cuellos de botella.

4.3. Decisiones sobre cómo lograr los Objetivos Clave de Calidad

4.3.1. Usabilidad

  • React permite interfaces interactivas y reactivas, mejorando la experiencia del jugador y facilitando la interacción en tiempo real.

4.3.2. Disponibilidad

  • Microsoft Azure y Docker aseguran que el juego esté disponible incluso en picos de tráfico o ante fallos parciales.

4.3.3. Compatibilidad

  • Se seleccionaron tecnologías como React y Node.js por ser compatibles con múltiples navegadores y dispositivos, asegurando accesibilidad para todos los jugadores.

4.3.4. Escalabilidad y Rendimiento

  • MongoDB y Microsoft Azure permiten escalar de manera flexible para soportar más jugadores y partidas simultáneas. Docker facilita la replicación de servicios según la demanda.

4.3.5. Seguridad

  • Se implementan medidas básicas como cifrado de contraseñas y protección ante accesos no autorizados para garantizar la seguridad de los datos de los jugadores.

4.4. Decisiones Organizativas Relevantes

  • Proceso de desarrollo: Se utiliza un proceso ágil, con gestión de tareas y colaboración en GitHub, favoreciendo entregas incrementales y ajustes rápidos durante el desarrollo.

Contents

Un breve resumen y explicación de las decisiones fundamentales y estrategias de solución que dan forma a la arquitectura del sistema. Incluye:

  • decisiones tecnológicas

  • decisiones sobre la descomposición de alto nivel del sistema, por ejemplo, el uso de un patrón arquitectónico o de diseño

  • decisiones sobre cómo lograr los objetivos clave de calidad

  • decisiones organizativas relevantes, por ejemplo, la selección de un proceso de desarrollo o la delegación de ciertas tareas a terceros.

Motivation

Estas decisiones forman las piedras angulares de tu arquitectura. Son la base para muchas otras decisiones detalladas o reglas de implementación.

Form

Mantén las explicaciones de dichas decisiones clave breves.

Motiva lo que se decidió y por qué se decidió de esa manera, basándote en la declaración del problema, los objetivos de calidad y las restricciones clave. Consulta los detalles en las secciones siguientes.

Further Information

See Solution Strategy in the arc42 documentation.

5. Vista de Bloques

Contenido

La vista de bloques muestra la descomposición estática del sistema en bloques (módulos, componentes, subsistemas, clases, interfaces, paquetes, librerías, frameworks, capas, particiones, niveles, funciones, macros, operaciones, estructuras de datos, etc.), así como sus dependencias (relaciones, asociaciones, etc.).

Esta vista es obligatoria en toda documentación arquitectónica. En analogía con una casa, representa el plano.

Motivación

Mantener una visión general del código fuente haciendo que su estructura sea comprensible mediante la abstracción.

Esto permite comunicarse con los stakeholders a un nivel abstracto sin revelar detalles de implementación.

Forma

La vista de bloques es una colección jerárquica de cajas negras y cajas blancas (véase la figura siguiente) junto con sus descripciones.

Jerarquía de bloques

Nivel 1 es la descripción en caja blanca del sistema completo junto con las descripciones en caja negra de todos los bloques que contiene.

Nivel 2 amplía (hace zoom sobre) algunos bloques del nivel 1. Por tanto, contiene la descripción en caja blanca de bloques seleccionados del nivel 1, junto con las descripciones en caja negra de sus bloques internos.

Nivel 3 amplía bloques seleccionados del nivel 2, y así sucesivamente.

Más información

Consulta Vista de Bloques en la documentación de arc42.

La vista de bloques muestra el comportamiento interno de la aplicación haciendo uso de diagramas de componentes que ilustran el funcionamiento de los microservicios que emplea la aplicación.

5.1. Representación del sistema general

diagrama componentes vista bloques yovi V0 1
Motivación

Yovi permite interactuar con el sistema, hace que los usuarios se puedan registrar y hacer uso del juego. Por otro lado, de manera interna, tenemos los microservicios los cuales interactuan con la aplicación web. Finalmente, el microservicio de usuarios se conecta con la base de datos para persistir la información.

Table 1. Descripción general del sistema
Actores Descripción

Usuario

Cliente/Usuario de la aplicación que interactúa con Yovi.

Yovi

Sistema principal que permite a los usuarios hacer uso del juego.

WebApp

Contiene la interfaz de usuario de la aplicación.

Backend (Microservicios)

Conjunto de microservicios que gestionan la lógica de negocio del sistema, incluyendo la gestión de usuarios, partidas y estadísticas.

Base de Datos

Sistema de almacenamiento donde se persisten los usuarios y las estadísticas de las partidas.

Inserta aquí las explicaciones de las cajas negras del nivel 1:

Si utilizas formato tabular, solo deberás describir tus cajas negras con nombre y responsabilidad según el siguiente esquema:

Nombre Responsabilidad

<caja negra 1>

<Texto>

<caja negra 2>

<Texto>

Si utilizas una lista de descripciones de cajas negras, entonces deberás rellenar una plantilla de caja negra independiente para cada bloque de construcción importante.

El encabezado debe ser el nombre de la caja negra.

6. Vista de tiempo de ejecución

Contenido

La vista de ejecución (Runtime View) describe el comportamiento concreto y las interacciones de los bloques de construcción del sistema en forma de escenarios de las siguientes áreas:

  • Casos de uso o funcionalidades importantes: ¿cómo los ejecutan los bloques de construcción?

  • Interacciones en interfaces externas críticas: ¿cómo cooperan los bloques con usuarios y sistemas vecinos?

  • Operación y administración: lanzamiento, inicio, parada

  • Escenarios de error y excepción

Observación: El criterio principal para la selección de los posibles escenarios (secuencias, flujos de trabajo) es su relevancia arquitectónica. No es importante describir una gran cantidad de escenarios. Es preferible documentar una selección representativa.

Form

  • Existen muchas notaciones para describir escenarios, por ejemplo:

  • Lista numerada de pasos (en lenguaje natural)

  • Diagramas de actividad o diagramas de flujo

  • Diagramas de secuencia

  • BPMN o EPCs (cadenas de procesos dirigidas por eventos)

  • Máquinas de estados

  • …​

Further Information

Consulta Runtime View en la documentación de arc42.

6.1. Escenario 1: Registro de usuario

Diagrama de secuencia

6.2. Escenario 2: Inicio de sesión

Diagrama de secuencia

6.3. Escenario 3: Juego con el bot

Diagrama de secuencia

7. 7. Vista de Despliegue

Contenido

La vista de despliegue describe:

  1. La infraestructura técnica utilizada para ejecutar el sistema, con elementos de infraestructura como ubicaciones geográficas, entornos, computadoras, procesadores, canales y topologías de red, así como otros elementos de infraestructura.

  2. La asignación de los bloques de construcción (software) a esos elementos de infraestructura.

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

Documente especialmente una vista de despliegue si su software se ejecuta como un sistema distribuido con más de una computadora, procesador, servidor o contenedor, o cuando diseñe y construya sus propios procesadores o chips de hardware.

Desde una perspectiva de software, es suficiente capturar únicamente aquellos elementos de la infraestructura que sean necesarios para mostrar el despliegue de los bloques de construcción. Los arquitectos de hardware pueden ir más allá y describir una infraestructura con el nivel de detalle que necesiten.

Motivación

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

Forma

Puede que un diagrama de despliegue de alto nivel ya esté contenido en la sección 3.2 como contexto técnico, con su propia infraestructura como UNA caja negra. En esta sección se puede hacer zoom dentro de esa caja negra utilizando diagramas de despliegue adicionales:

  • UML ofrece diagramas de despliegue para expresar esta vista. Úselos, probablemente con diagramas anidados, cuando su infraestructura sea más compleja.

  • Cuando las partes interesadas de hardware prefieran otros tipos de diagramas en lugar de un diagrama de despliegue, permita que utilicen cualquier tipo que sea capaz de mostrar nodos y canales de la infraestructura.

Información Adicional

Consulte Deployment View en la documentación de arc42.

7.1. Infraestructura Nivel 1

Diagrama de despliegue - Nivel 1
Diagrama de despliegue - Nivel 1

Motivacion * Escalabilidad: La infraestructura de Microsoft Azure permite escalar horizontalmente mediante la creación dinámica de instancias de contenedores según la demanda del sistema.

  • Disponibilidad: La plataforma de Azure facilita la alta disponibilidad a través de balanceadores de carga y múltiples zonas de disponibilidad.

Características de Calidad y Rendimiento

  • Bajo tiempo de respuesta: La distribución geográfica de los servidores de Azure reduce la latencia y mejora la experiencia del usuario final.

  • Mantenibilidad: El uso de Docker facilita la gestión de versiones de los microservicios, su despliegue y la recuperación rápida ante fallos.

Asignación de Artefactos de Software a la Infraestructura

  • Juego (Core): Implementado en Rust, donde se desarrolla la lógica principal y el motor del juego para maximizar rendimiento y seguridad.

  • Microservicios: Desplegados como contenedores Docker dentro de Azure.

  • Frontend (Web Browser): Ejecutado en el dispositivo del usuario e interactuando con la API del backend alojada en Azure.

  • Base de Datos MongoDB: Desplegada en un contenedor propio dentro de Azure utilizando MongoDB como sistema gestor de base de datos.

7.2. Infraestructura Nivel 2

Diagrama de despliegue - Nivel 2
Diagrama de despliegue - Nivel 2

Microservicios

  • WebApp: Servicio que sirve la aplicacion web y se cominica con el Gateway.

  • Gateway: Actúa como punto de entrada único para el fronted, enrutando las solicitudes a los microservicios correspondientes.

  • User: Gestiona la autenticación, el registro de usuarios y el historial de partidas.

  • Game: Maneja la lógica del juego, incluyendo la gestión de partidas, movimientos y estadísticas.

8. Conceptos Transversales

Contenido

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

  • modelos, especialmente modelos de 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 global (= 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 su sistema.

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

Forma

La forma puede variar:

  • documentos de conceptos con cualquier tipo de estructura

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

  • implementaciones de ejemplo, especialmente para conceptos técnicos

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

Estructura

Una estructura posible (pero no obligatoria) 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 diseño

  • “Bajo el capó”

  • Conceptos de desarrollo

  • Conceptos operativos

Nota: puede resultar difícil asignar conceptos individuales a un único tema de esta lista.

Temas posibles para conceptos transversales
Más información

See Concepts in the arc42 documentation.

8.1. Usabilidad

Usabilidad es la facilidad con la que un usuario puede interactuar con un sitio o aplicación, logrando sus objetivos de manera eficiente, efectiva y satisfactoria. La aplicación web será intuitiva, el tebloro mostrará en todo momento el estado del juego, se podrán consultar las reglas del juego durante una partida. La aplicación será también accesible para la mayor cantidad de usuarios posible.

8.2. Autenticación

El sistema ha de poder validad la identidad de los usuarios antes de permitir el acceso a funcionalidades de la aplicación. Los datos personales han de estar protegidos de cualquier acceso no autorizado. Lo0s datos personales incluyen las credenciales de los usarios; nombre, correo asociado y contraseña encriptada.

8.3. Persistencia

El sistema almacena y recupera la información necesaria de una base de datos, esta base de datos solo debe de ser accesible por el sistema. En la base se guardarán los datos de las credenciales de los usuarios.

La base de datos es, de momento:

Diagrama de la base de datos de yovi

8.4. Internacionalizacion

La aplicación será implementada en inglés y español. Se seguirán las recomendaciones i18n, para hacerla entendible a un mayor rango de usuarios.

8.5. Microservicio

Una aplicación pequeña e independiente que hace una sola función específica y se comunica con otros servicios, normalmente por APIs. Se puede desplegar, escalar y mantener sin depender del resto del sistema.

Contenido

Decisiones arquitectónicas importantes, costosas, de gran escala o con riesgo, incluyendo sus justificaciones. Con "decisiones" nos referimos a seleccionar una alternativa basada en criterios dados.

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

Evita redundancias. Haz referencia a la sección 4, donde ya has recogido las decisiones más importantes de tu arquitectura.

Motivación

Los stakeholders de tu sistema deben poder comprender y reconstruir tus decisiones.

Forma

Varias opciones:

  • ADR (Documenting Architecture Decisions) para cada decisión importante

  • Lista o tabla, ordenada por importancia y consecuencias o:

  • Más detallado en forma de secciones separadas por decisión

Más información

Consulta Architecture Decisions en la documentación de arc42. Allí encontrarás enlaces y ejemplos sobre ADR.

9. Decisiones arquitectónicas

En este apartado se justifican las decisiones tomadas por el equipo en cuanto a decisiones arquitectónicas se refiere, justifcando detalladamente el porque de cada decisión a continuación.

9.1. Resumen de decisiones

Decisión Tecnología seleccionada Justificación principal

Control de versiones

Git

Hemos escogido Git para el control de versiones dado que es ampliamente utilizado en la industria, además de que ha sido empleado por todo el equipo lo que nos permite trabajar de manera cómoda y más eficiente.

Base de datos

MongoDB

Base de datos sencilla, formato simple con un modelo flexible orientado a documentos, ideal para los datos de los usuarios que necesitamos almacenar.

Backend

Node.js

Alto rendimiento en I/O, ecosistema amplio y buena integración con frontend en JavaScript.

Frontend

React + Vite

Desarrollo rápido, sencillo de implementar y amplia cantidad bibliotecas.

Motor de estrategia y procesamiento

Rust

Lenguaje de alto rendimiento, eficiente para cálculos de estrategia del juego, seguridad de memoria.

Lenguaje principal web

Javascript / Typescript

Tecnologías ampliamente utilizadas en el desarrollo web, con una gran comunidad y ecosistema consolidado. Permiten una integración natural entre frontend y backend, facilitando el mantenimiento, la reutilización de código y la productividad del equipo.

Contenerización y despliegue

Docker

Se eligió Docker dado que permite de manera sencilla garantizar entornos consistentes entre desarrollo, pruebas y producción. Además es una herramienta que facilita la portabilidad, el aislamiento de dependencias y simplifica el proceso de despliegue.

Internacionalización

i18n

Incorporamos un sistema de internacionalización (i18n) que permite la adaptación de la aplicación a múltiples idiomas.

10. Quality Requirements

Contenido

Esta sección contiene todos los requisitos de calidad organizados como un árbol de calidad con escenarios. Los más importantes ya se han descrito en la sección 1.2 (objetivos de calidad).

Aquí también puedes capturar requisitos de calidad de menor prioridad, que no generarán riesgos altos si no se cumplen completamente.

Motivación

Dado que los requisitos de calidad tendrán mucha influencia en las decisiones arquitectónicas, debes saber para cada interesado qué es realmente importante para ellos, de manera concreta y medible.

Información adicional

Consulta Quality Requirements en la documentación de arc42.

10.1. Árbol de calidad

  • Calidad del Sistema

    • Usabilidad QR01

      • La aplicación es fácil de aprender y utilizar.

    • Rendimiento QR02

      • El sistema responde en un corto tiempo.

    • Fiabilidad QR03

      • La aplicación se comporta de forma estable.

    • Funcionalidad QR04

      • Las reglas del juego y-game y sus variantes se aplican correctamente.

    • Portabilidad QR05

      • La aplicación funciona en los navegadores web más comunes.

Contenido

El árbol de calidad (según lo definido en ATAM – Architecture Tradeoff Analysis Method) con escenarios de calidad/evaluación como hojas.

Motivación

La estructura de árbol con prioridades ofrece una visión general de un número a veces grande de requisitos de calidad.

Forma

El árbol de calidad es una visión general de alto nivel de los objetivos y requisitos de calidad:

Refinamiento en forma de árbol del término “calidad”. Usar “calidad” o “utilidad” como raíz.

Un mapa mental con categorías de calidad como ramas principales.

En cualquier caso, el árbol debe incluir enlaces a los escenarios de la sección siguiente.

10.1.1. Escenarios de Calidad

Id Atributo de Calidad Escenario Respuesta esperada Cómo se mide

QR01

Usabilidad

Usuario nuevo intenta usar la aplicación

Usuario comprende cómo usar la aplicación

La aplicación es lo suficientemente intuitiva para que un usuario complete tareas sin ayuda y con un corto tiempo de aprendizaje

QR02

Rendimiento

Usuario realiza una acción

Sistema responde rápidamente

Tiempo de respuesta aceptable para evitar malas experiencias

QR03

Fiabilidad

Varias solicitudes consecutivas al sistema

Sistema mantiene comportamiento estable

Menor cantidad de fallos posible, en caso de error; mostrárselo al usuario

QR04

Funcionalidad

Usuario ejecuta las reglas del juego

Reglas aplicadas correctamente

Todas las reglas evaluadas correctamente en pruebas

QR05

Portabilidad

Usuario abre la aplicación en distintos navegadores

Aplicación funciona correctamente

La aplicación es funcional en distintos navegadores
Contenido

Concretización de requisitos de calidad (a veces vagos o implícitos) utilizando escenarios de calidad.

Estos escenarios describen lo que debería suceder cuando un estímulo llega al sistema.

Para los arquitectos, son importantes dos tipos de escenarios:

Escenarios de uso (también llamados escenarios de aplicación o escenarios de casos de uso) describen la reacción del sistema en tiempo de ejecución ante un determinado estímulo. Esto incluye también escenarios que describen la eficiencia o el rendimiento del sistema. Ejemplo: El sistema responde a la solicitud de un usuario en menos de un segundo.

Escenarios de cambio describen una modificación del sistema o de su entorno inmediato. Ejemplo: Se implementa funcionalidad adicional o cambian los requisitos de un atributo de calidad.

Motivación

Los escenarios hacen que los requisitos de calidad sean concretos y permiten medirlos o decidir más fácilmente si se cumplen.

Especialmente si quieres evaluar tu arquitectura usando métodos como ATAM, necesitas describir tus objetivos de calidad (de la sección 1.2) de manera más precisa, hasta un nivel de escenarios que puedan ser discutidos y evaluados.

Forma

En tabla o en texto libre.

11. Riesgos y deudas técnicas

11.1. Riesgos técnicos

Riesgo Explicación detallada

Inexperiencia del grupo

Somos un grupo de estudiantes de informática, por lo que no tenemos experiencia en el desarrollo de grandes proyectos.

Inexperiencia con Rust

No tenemos experiencia con Rust, lo que puede dificultar el desarrollo del bot, como la del tablero de juego y los moviemientos.

Inexperiencia con React

No tenemos experiencia con React, lo que puede dificultar el desarrollo de la aplicación principal para mostrar el juego yel inicio de sesión.

Poco conocimiento con Node.js

En el curso se ha visto algo de Node.js, pero no tenemos la suficiente experiencia, por lo que podría llegar a dificultar el desarrollo del proyecto.

Poco conocimiento con Docker

Aplicación principal para mostrar el juego.

Caída de la máquina virtual

La caída de Azure podría afectar a la disponibilidad de la máquina virtual, lo que podría afectar al funcionamiento de la aplicación principal.

Tiempo ajustado

El poco tiempo disponible por otras asignaturas y prácticas de empresa haría que el tiempo para desarrollar el proyecto sea vea mermado.

Factor del autobús

Si un miembro del grupo se ve afectado por una enfermedad o accidente, podría afectar al desarrollo del proyecto en la realización de las tareas asignadas.

11.2. Deudas técnicas

Deuda Explicación detallada

Deuda técnica 1

Explicación detallada de la deuda técnica 1.

Deuda técnica 2

Explicación detallada de la deuda técnica 2.

En desarrollo…​

Contenido

Una lista de los riesgos técnicos o deudas técnicas identificadas, ordenadas por prioridad.

Motivación

«La gestión de riesgos es la gestión de proyectos para adultos» (Tim Lister, Atlantic Systems Guild).

Este debería ser tu lema para la detección y evaluación sistemática de riesgos y deudas técnicas en la arquitectura, que serán necesarios para los interesados de gestión (por ejemplo, jefes de proyecto, product owners) como parte del análisis global de riesgos y la planificación de mediciones.

Forma

Lista de riesgos y/o deudas técnicas, que probablemente incluya medidas sugeridas para minimizar, mitigar o evitar los riesgos, o para reducir la deuda técnica.

Further Information

Consulta Risks and Technical Debt en la documentación de arc42.

12. Glossary

Contents

The most important domain and technical terms that your stakeholders use when discussing the system.

You can also see the glossary as source for translations if you work in multi-language teams.

Motivation

You should clearly define your terms, so that all stakeholders

  • have an identical understanding of these terms

  • do not use synonyms and homonyms

Form

A table with columns <Term> and <Definition>.

Potentially more columns in case you need translations.

Further Information

See Glossary in the arc42 documentation.

Term Definition

<Term-1>

<definition-1>

<Term-2>

<definition-2>