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 Metas (wiq_es05a)

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

El objetivo es crear una aplicación web llamada Quizz Master basada en el programa de televisión "Saber y Ganar". La aplicación permitirá registrarse a los usuarios para poder jugar. Dicho juego consiste en una serie de preguntas generadas aleatoriamente, de diferentes temáticas y respuestas, que deberán responderse en un tiempo determinado. Por cada respuesta correcta se obtendrá un premio.

1.1. Vista de Requerimientos

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

  • Frontend Web Desplegado: Habrá una interfaz web accesible vía navegador.

  • Registro de Usuarios y Consulta de Estadísticas: Usuarios podrán registrarse y ver sus estadísticas de participación.

  • Generación Automática de Preguntas desde Wikidata: Las preguntas se generarán automáticamente usando datos de Wikidata.

  • Plazo de Tiempo para Responder: Los usuarios tendrán un límite de tiempo para responder preguntas.

  • Respuestas Correctas e Incorrectas Automatizadas: Cada pregunta tendrá una respuesta correcta y varias incorrectas, generadas automáticamente.

  • Acceso a Información de Usuarios vía API: Otros sistemas podrán acceder a los datos de los usuarios a través de un API.

  • Acceso a Información de Preguntas vía API: Otros sistemas podrán acceder a los detalles de las preguntas generadas mediante un API.

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

Nombre Descripción

Usabilidad

La aplicación tiene que poder usarse por el mayor tipo de usuarios, promoviendo una experiencia intuitiva y accesible desde el primer contacto.Conforme los usuarios se familiarizan y exploran más la aplicación, su uso se vuelve más intuitivo y sencillo, gracias a la curva de aprendizaje.

Rendimiento

La aplicación debe de ofrecer un tiempo de respuesta rápido para garantizar una experiencia fluida y eficiente para los usuarios.

Testeable

Las pruebas deben ser capaces de detectar errores de manera rápida y precisa, fáciles de mantener y actualizar a medida que el código base cambia. Esto implica que las pruebas estén bien estructuradas y documentadas.

Disponibilidad

Debemos asegurar que la aplicación esté funcional y operativa durante la mayor parte del tiempo.

1.3. Stakeholders

Contents

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

  • should know the architecture

  • have to be convinced of the architecture

  • have to work with the architecture or with code

  • need the documentation of the architecture for their work

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

Motivation

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

Form

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

Rol/Nombre Expectativa Descripción

Profesor

Aplicar correctamente los conocimientos y competencias adquiridos en la asignatura Arquitectura del Software

Profesor de la asignatura

HappySw

Una aplicación buena para atraer al mayor número de usuarios

Equipo de desarrollo

Wikidata

Usar su aplicacion con precaución, sin sobrecargar sus servicios

Empresa que nos facilita la API para obtener información

Usuarios Registrados

Poder jugar en la aplicación que recrea el juego sin tener que participar en el programa.

Usuarios registrados en la plataforma, pudiendo haber jugado una o más partidas.

Usuarios No Registrados

Poder registrarse lo más rápido posible para empezar a jugar al juego de preguntas y respuestas

Usuarios que nunca se han registrado antes

RTVE

Versión mejorada de "Saber y Ganar" para ganar mayor audiencia e interés social.

Dueño del producto

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

Este proyecto tiene una serie de restricciones de arquitectura marcadas por los responsables de la asignatura. Por ello esta aplicación está desarrollada siguiendo una serie de limitaciones las cuales nombraremos a continuación.

2.1. Limitaciones técnicas

Restricción Explicación

GIT

En la asignatura se requiere el uso del sistema de control de versiones GIT, además de emplear GitHub como repositorio. Asimismo, nos permite una continua integración de forma remota mediante la paralelización del trabajo usando el sistema de ramas.

Docker

Esta tecnología de contenerización será requerida ya que la usaremos para desplegar la aplicación web tanto en el entorno de desarrollo como en el de producción y realizar las pruebas pertinentes.

Wikidata

En la asignatura se requiere que esta sea la fuente de información principal para generar aleatoriamente tanto las preguntas como las respuestas correctas e incorrectas del juego.

APIs rest

Son una limitación por varias razones, no proporcionan seguridad avanzada, no ofrecen un esquema de datos detallados, pueden no ser ideales para operaciones mas complejas y requieren endpoints predefinidos.

2.2. Limitaciones organizativas

Restricción Explicación

Equipo

El equipo de trabajo está compuesto por 4 integrantes, por lo que la cooperación y coordinación es esencial para el desarrollo de la aplicación.

Experiencia

Es la primera ocasión en la que los miembros del equipo trabajan en un proyecto de esta envergadura. Al comienzo del proyecto, los miembros del equipo de desarrollo enfrentaba una curva de aprendizaje considerable con respecto al uso de algunas de las tecnologías necesarias, por lo que fue necesario aprender a trabajar, en algunos casos desde cero, con alguna de estas.

Reuniones

Para mantener un buen ritmo de trabajo a través de una correcta organización se realizan reuniones semanales en las clases prácticas de la asignatura. Además, mantenemos contacto a través de nuestro grupo de WhatsApp y en casos necesarios realizamos reuniones extraordinarias utilizando nuestro servidor de Discord.

Issues

Para el seguimiento y la gestión de las tareas, problemas, mejoras, autoinformes, etc. de la aplicación tendremos que usar las issues ofrecidas por github; esto es una obligación ya que reflejara el trabajo realizado por cada miembro del equipo al poder asignarse cada issue.

Actas

Al igual que las issues, las actas servirán para la organización de las tareas asi como para la toma de decisiones, y tendrán que reflejar el trabajo repartido a cada miembro. Se deberán realizar obligatoriamente cada vez que se realice una reunión y deberán constar los miembros del equipo que han participado.

Decisiones arquitectónicas

Las decisiones arquitectónicas pueden ser una limitación organizativa al definir la estructura básica de un sistema de software, lo que podría obstaculizar la capacidad de realizar cambios y adaptarse a nuevas necesidades y tecnologías.

2.3. Convenciones

Restricción Explicación

Diseño del software

Para lograr un buen diseño es indispensable que el código de la aplicación sea flexible, mantenible y comprensible. Además se espera que sigamos los principios de "codigo limpio" en cuanto a modularidad, limpieza, nombrado de métodos y variables.

Documentación

Para crearla usaremos la plantilla Arc42 con la finalidad de que sea sencilla y práctica.

Estructura

Debe seguir una estructura de paquetes fija y bajo los mismos estandares. Los diferentes modulos estarán separados en carpetas: 'userservice' para la gestión de usuarios (registro y autentificación), 'questionservice' para la comunicación con wikidata y 'webapp' para el desarrollo de la aplicación. Todos estos servicios estarán comunicados por 'gatewayservice'.

Convenciones del lenguaje de programación

Es fundamental adherirse a las convenciones de los diferentes lenguajes de programación utilizados para garantizar que la aplicación tenga un código legible, que facilite su mantenimiento.

3. Alcance y Contexto del Sistema

Contents

System scope and context - as the name suggests - delimits your system (i.e. your scope) from all its communication partners (neighboring systems and users, i.e. the context of your system). It thereby specifies the external interfaces.

If necessary, differentiate the business context (domain specific inputs and outputs) from the technical context (channels, protocols, hardware).

Motivation

The domain interfaces and technical interfaces to communication partners are among your system’s most critical aspects. Make sure that you completely understand them.

Form

Various options:

  • Context diagrams

  • Lists of communication partners and their interfaces.

Further Information

See Context and Scope in the arc42 documentation.

3.1. Contexto de Negocio

Contents

Specification of all communication partners (users, IT-systems, …​) with explanations of domain specific inputs and outputs or interfaces. Optionally you can add domain specific formats or communication protocols.

Motivation

All stakeholders should understand which data are exchanged with the environment of the system.

Form

All kinds of diagrams that show the system as a black box and specify the domain interfaces to communication partners.

Alternatively (or additionally) you can use a table. The title of the table is the name of your system, the three columns contain the name of the communication partner, the inputs, and the outputs.

Diagrama de contexto de negocio
Componentes Explicación

Sistema

Contiene el frontend y backend de la aplicación.

Usuario nuevo

Usuario nuevo en la aplicación se registrará y será el propio sistema el que confirme el registro o le muestre un error.

Usuario registrado

Usuario antiguo que podrá jugar y el sistema le irá devolviendo feedback de la partida o podrá entrar a consultar datos de partidas anteriores que el sistema le devolverá.

Wikidata

Fuente de información para la creación de las preguntas y respuestas.

3.2. Contexto Técnico

Contents

Technical interfaces (channels and transmission media) linking your system to its environment. In addition a mapping of domain specific input/output to the channels, i.e. an explanation which I/O uses which channel.

Motivation

Many stakeholders make architectural decision based on the technical interfaces between the system and its context. Especially infrastructure or hardware designers decide these technical interfaces.

Form

E.g. UML deployment diagram describing channels to neighboring systems, together with a mapping table showing the relationships between channels and input/output.

Diagrama de contexto técnico
Componentes Explicación

Sistema

Contiene el frontend y backend de la aplicación.

MongoDB

Base de datos no relacional para el almacenamiento de usuarios y registro de sus partidas.

Usuario

Persona que interactua con nuestra aplicación web a través del navegador.

Wikidata API

API de donde obtendremos las preguntas y respuestas correctas y falsas para el juego de la aplicación, todas estas preguntas serán cargadas al inicio del juego.

Javascript

Lenguaje de programación principal de la aplicación permite una sintaxis uniforme en toda la aplicación y facilita el mantenimiento del código. Además, al usar JavaScript en el frontend y el backend, se puede compartir lógica entre ambas partes para un desarrollo más eficiente.

Express JS

Express es un framework de aplicación web para Node.js, que te permite crear aplicaciones web robustas y escalables en JavaScript para el backend.

React

Biblioteca de Javascript para creación de interfaces de usuario, utilizado en el frontend.

Bootstrap

Biblioteca de código abierto que proporciona herramientas y estilos para el diseño de aplicaciones web y sitios responsivo. Podemos crear interfaces de usuario atractivas y funcionales de manera rápida y sencilla.

webapp

Módulo del sistema que se encarga de la interfaz del sistema.

questionservice

Módulo del sistema que se encarga de crear preguntas obteniendo tanto preguntas como respuestas correctas e incorrectas de la API Wikidata.

gateway

Módulo del sistema que funciona como puerta de enlace para coordinar el resto de modulos del sistema.

userservice

Módulo del sistema que se encarga de tener los modelos y hacer las consultas para el almacenamiento correcto de los usuarios de la aplicación y del registro de partidas con la ayuda de nuestra base de datos MongoDB.

authservice

Módulo del sistema que se encarga de gestionar la autenticación del usuario.

4. Estrategia de solución

Contents

A short summary and explanation of the fundamental decisions and solution strategies, that shape system architecture. It includes

  • technology decisions

  • decisions about the top-level decomposition of the system, e.g. usage of an architectural pattern or design pattern

  • decisions on how to achieve key quality goals

  • relevant organizational decisions, e.g. selecting a development process or delegating certain tasks to third parties.

Motivation

These decisions form the cornerstones for your architecture. They are the foundation for many other detailed decisions or implementation rules.

Form

Keep the explanations of such key decisions short.

Motivate what was decided and why it was decided that way, based upon problem statement, quality goals and key constraints. Refer to details in the following sections.

Further Information

See Solution Strategy in the arc42 documentation.

  • JavaScript: Este lenguaje es muy buena opción para utilizar en proyectos en que se empleé la biblioteca REACT. Nos pareció mejor opción que otros lenguajes como TypeScript debido a que su compresión y manejo es más sencillo. Además usamos Express es una infraestructura de aplicaciones web en Node.js que ofrece una solución rápida, minimalista y flexible para desarrollar aplicaciones web y móviles1

  • React: Esta libreria de JavaScript permite la creación de interfaces de usuario para la aplicacion web de forma sencilla.

  • Docker: Utilizaremos esta plataforma para desplegar la aplicacion web, de manera que puedan realizarse pruebas aisladas de esta misma.

  • Mongo-DB: Esta API nos servirá como sistema de autenticación del usuario para poder llevar un registro de sus estadísticas, así como algunas de sus estadísticas.

  • Microservicios: Enfoque arquitectónico donde el software está compuesto por pequeños servicios independientes. Lo hemos elegido debido a la facilidad para modificar una parte de la aplicación sin afectar al resto.

5. Vista de Bloques

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. Nivel 1: Sistema General de Caja Blanca

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.

Sistema General de Caja Blanca
Motivación

La motivación de este diagrama es ofrecer una representación clara y sencilla de cómo el sistema interactúa con los usuarios y los servicios externos.

Bloques de construcción contenidos
Nombre Responsabilidad

Usuario

Cuando alguien usa nuestra aplicación, se comunica con ella a través de Internet usando un lenguaje especial llamado HTTP. Cuando se registra en la aplicación, los datos que ingresa se guardan en una base de datos especial llamada MongoDB. Para que esto suceda, usamos una herramienta llamada Mongoose, que nos ayuda a conectarnos y comunicarnos con la base de datos de una manera fácil y segura. Entonces, cada vez que alguien se registra en nuestra aplicación, Mongoose se asegura de guardar esos datos en la base de datos para que puedan ser utilizados más tarde.

WIQ

La propia aplicación, encargada de pedir las preguntas a wikidata para poder llevar a cabo la partida.

Wikidata

Servicio externo desde donde obtenemos los datos para generar las preguntas.

5.2. Nivel 2: WIQ

Nivel 2 de la aplicación: WIQ
Bloques de construcción contenidos
Nombre Responsabilidad

webapp

La interfaz con la que interactua el usuario.

gatewayservice

Servicio de puerta de enlace que actúa como intermediario entre los usuario que quieran juagar y otros servicios, reenviando las solicitudes a los servicios correspondientes y devolviendo las respuestas al cliente.

authservice

Servicio que se encarga de verificar las credenciales de los usuarios al iniciar sesión en la aplicación. Si las credenciales son correctas, se genera un token de acceso que permite al usuario autenticado acceder a partes protegidas de la aplicación.

userservice

Servicio que gestiona el registro de nuevos usuarios en la aplicación. Cuando un usuario se registra, se asegura de que se proporcionen los campos necesarios y luego cifra la contraseña antes de guardarla. También ofrece funciones para actualizar las estadísticas del usuario y obtener información de usuario.

questionservice

Este servicio se encarga de proporcionar preguntas y respuestas basadas en datos de Wikidata. Utiliza consultas SPARQL para obtener información de Wikidata y luego genera preguntas aleatorias basadas en estos datos para ser utilizadas en la aplicación."

Wikidata

Servicio externo desde donde obtenemos los datos para generar las preguntas.

MongoDB

MongoDB es un sistema de gestión de bases de datos NoSQL utilizado en la aplicación para almacenar y organizar los datos de manera eficiente. Su responsabilidad principal es gestionar la persistencia de los datos de la aplicación, permitiendo el almacenamiento, consulta y manipulación de la información de manera escalable y flexible.

OpenAPI

Encargado de la especificación utilizada junto a swagger para la creación de una documentacio de todos los métodos que se realizan en gateway.

6. Vista en Tiempo de Ejecución

Contents

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

  • important use cases or features: how do building blocks execute them?

  • interactions at critical external interfaces: how do building blocks cooperate with users and neighboring systems?

  • operation and administration: launch, start-up, stop

  • error and exception scenarios

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

Motivation

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

Form

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

  • numbered list of steps (in natural language)

  • activity diagrams or flow charts

  • sequence diagrams

  • BPMN or EPCs (event process chains)

  • state machines

  • …​

Further Information

See Runtime View in the arc42 documentation.

6.1. Inicio de Sesión

Al iniciar sesión en nuestra WebApp, se presentará una interfaz solicitando al usuario que ingrese los datos necesarios para comenzar a jugar. Estos datos incluirán información de identificación única, como nombre de usuario y contraseña, así como posiblemente otros detalles relevantes para el perfil del jugador.

Una vez que el usuario proporciona estos datos, la WebApp los enviará al servicio userService a través de gatewayService, que actuará como el backend encargado de autenticar al usuario y gestionar su sesión. UserService verificará la validez de los datos proporcionados por el usuario y, si son correctos, emitirá un token de sesión único que identificará al usuario.

Este token de sesión se devolverá a la WebApp, donde se utilizará para mantener la sesión del usuario durante su interacción con la plataforma de juego.

Una vez que el proceso de inicio de sesión se completa con éxito, la WebApp cambiará su interfaz para mostrar que ha iniciado sesión correctamente.

Diagrama vista de tiempo de ejecución para el acceso

6.2. Interacción con Preguntas

Comenzaremos con la API REST que obtendrá las preguntas de Wikidata junto con sus opciones de respuestas correctas e incorrectas.

Al obtener dicha información, QuestionService se la transmitirá a GatewayService que a su vez ira mostrando en WebApp pregunta por pregunta junto con todas las opciones de respuesta disponibles al usuario, quien podrá seleccionar una única respuesta entre las opciones proporcionadas. Una vez que el usuario ha realizado su selección, la WebApp verificará la precisión de la respuesta.

Posteriormente, basándose en la respuesta proporcionada por el usuario, la WebApp ofrecerá una retroalimentación visual clara que permitirá al usuario comprender si su respuesta fue correcta o incorrecta.

Por tanto, terminaremos con una retroalimentación visual por pantalla del resultado obtenido tras la respuesta del jugador.

Tras esto y cuando el jugador solicite la siguiente pregunta se seguirá repitiendo el proceso de GatewayService proporcionando a WebApp una nueva pregunta hasta terminar el juego.

Este flujo de interacción garantiza una experiencia de usuario fluida y comprensible, optimizando así la participación y el compromiso del usuario con la plataforma.

Diagrama vista de tiempo de ejecución para la pregunta

7. Vista de Despliegue

Content

The deployment view describes:

  1. technical infrastructure used to execute your system, with infrastructure elements like geographical locations, environments, computers, processors, channels and net topologies as well as other infrastructure elements and

  2. mapping of (software) building blocks to that infrastructure elements.

Often systems are executed in different environments, e.g. development environment, test environment, production environment. In such cases you should document all relevant environments.

Especially document a deployment view if your software is executed as distributed system with more than one computer, processor, server or container or when you design and construct your own hardware processors and chips.

From a software perspective it is sufficient to capture only those elements of an infrastructure that are needed to show a deployment of your building blocks. Hardware architects can go beyond that and describe an infrastructure to any level of detail they need to capture.

Motivation

Software does not run without hardware. This underlying infrastructure can and will influence a system and/or some cross-cutting concepts. Therefore, there is a need to know the infrastructure.

Form

Maybe a highest level deployment diagram is already contained in section 3.2. as technical context with your own infrastructure as ONE black box. In this section one can zoom into this black box using additional deployment diagrams:

  • UML offers deployment diagrams to express that view. Use it, probably with nested diagrams, when your infrastructure is more complex.

  • When your (hardware) stakeholders prefer other kinds of diagrams rather than a deployment diagram, let them use any kind that is able to show nodes and channels of the infrastructure.

Further Information

See Deployment View in the arc42 documentation.

7.1. Infrastructura Nivel 1

Describe (usually in a combination of diagrams, tables, and text):

  • distribution of a system to multiple locations, environments, computers, processors, .., as well as physical connections between them

  • important justifications or motivations for this deployment structure

  • quality and/or performance features of this infrastructure

  • mapping of software artifacts to elements of this infrastructure

For multiple environments or alternative deployments please copy and adapt this section of arc42 for all relevant environments.

Diagrama de despliegue

Utilizamos como servidor en la nube Azure como infraestructura principal, dentro de ella tenemos desplegados cinco contenedores de Docker.

  • UserService: encargado de la gestión de usuarios, maneja autenticación, gestión de los perfiles, etc..

  • WebApp: donde reside la aplicación, con lo que interactúan los usuarios a traves de una interfaz de usuario en el navegador web.

  • GatewayService: es la puerta de enlace entre la aplicación y los servicios subyacentes.

  • QuestionService: encargado de obtener las preguntas de un servidor externo que en este caso es Wikidata.

  • MongoDB: alberga la base de datos para almacenar usuarios y sus estadísticas.

Mapeo de bloques de construcción a infraestructura
Elemento Descripción

Servidor Azure

Servidor alojado en la nube de Microsoft Azure sobre el que se realiza el despliegue.

Contenedores Docker

Son instancias virtualizadas y aisladas que contienen cada una uno de los microservicios que conforman la aplicación.

WebApp

Microservicio responsable de las vistas de la aplicación y sus interacciones con el usuario.

QuestionService

Microservicio responsable de generar preguntas y respuestas utilizando la información de Wikidata.

UserService

Microservicio encargado de gestionar los diferentes usuarios y sus partidas realizadas.

Navegador Web

Programa sobre el que el cliente visualiza e interactúa con la aplicación web.

8. Conceptos transversales

Content

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

  • models, especially domain models

  • architecture or design patterns

  • rules for using specific technology

  • principal, often technical decisions of an overarching (= cross-cutting) nature

  • implementation rules

Motivation

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

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

Form

The form can be varied:

  • concept papers with any kind of structure

  • cross-cutting model excerpts or scenarios using notations of the architecture views

  • sample implementations, especially for technical concepts

  • reference to typical usage of standard frameworks (e.g. using Hibernate for object/relational mapping)

Structure

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

  • Domain concepts

  • User Experience concepts (UX)

  • Safety and security concepts

  • Architecture and design patterns

  • "Under-the-hood"

  • development concepts

  • operational concepts

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

Possible topics for crosscutting concepts
Further Information

See Concepts in the arc42 documentation.

8.1. Prototipos de pantalla

En la siguiente sección, vamos a mostrar los primeros prototipos de pantalla, aunque pueden estar sujetos a cambios en el futuro.

Pantalla principal La pantalla principal que aparece al entrar en la aplicación, con las opciones de jugar y ver las estadisticas de los juegos solo si estás registrado en la aplicación. Además de las propias opciones de iniciar sesión y registrarse.

Prototipo de pantalla principal

Pantalla de juego Irán apareciendo 5 diferentes preguntas con 4 posibles rspuestas, de las cuales solo una será la correcta. También podremos ver el tiempo que trascurre durante todo el juego.

Prototipo de pantalla de juego

Pantalla de estadísticas Solo se podrá acceder a esta página si estás registrado en la aplicación. Aqui podremos observar diferentes estadisticas en los juego que hayas jugado.

Prototipo de pantalla de destadisticas

9. Decisiones arquitectónicas

Contents

Important, expensive, large scale or risky architecture decisions including rationales. With "decisions" we mean selecting one alternative based on given criteria.

Please use your judgement to decide whether an architectural decision should be documented here in this central section or whether you better document it locally (e.g. within the white box template of one building block).

Avoid redundancy. Refer to section 4, where you already captured the most important decisions of your architecture.

Motivation

Stakeholders of your system should be able to comprehend and retrace your decisions.

Form

Various options:

  • ADR (Documenting Architecture Decisions) for every important decision

  • List or table, ordered by importance and consequences or:

  • more detailed in form of separate sections per decision

Further Information

See Architecture Decisions in the arc42 documentation. There you will find links and examples about ADR.

Aspecto Descripción Decisión Explicación Alternativas

Lenguaje de Programación

Lenguaje en el que se desarrollara la aplicación.

JavaScript

Hemos elegido esta opción porque es la mejor para usar en proyectos con REACT. Es fácil de entender y de manejar.

TypeScript, pero creemos que es mas complejo.

Framework

Marco de trabajo para desarrollar la parte grafica de la aplicación.

React

Optamos por este framework debido a su capacidad para simplificar el proceso de creación de interfaces gráficas.

Angular, Vue…​

Base de Datos

Donde almacenaremos la información de los usuarios.

MongoDB

Decidimos utilizarla porque es una base de datos no relacional que se adapta bien a estructuras de datos flexibles como las que necesitamos para almacenar información de usuarios.

PostgreSQL, Redis, MariaDB, SQLite…​

Arquitectura

La forma en la que se estructura la aplicación.

Microservicios

Es una manera simple de organizar, facil de desacoplar y reutilizar.

Simplemente basada en front-end y back-end.

10. Requerimientos de Calidad

Content

This section contains all quality requirements as quality tree with scenarios. The most important ones have already been described in section 1.2. (quality goals)

Here you can also capture quality requirements with lesser priority, which will not create high risks when they are not fully achieved.

Motivation

Since quality requirements will have a lot of influence on architectural decisions you should know for every stakeholder what is really important to them, concrete and measurable.

Further Information

See Quality Requirements in the arc42 documentation.

10.1. Árbol de Calidad

Content

The quality tree (as defined in ATAM – Architecture Tradeoff Analysis Method) with quality/evaluation scenarios as leafs.

Motivation

The tree structure with priorities provides an overview for a sometimes large number of quality requirements.

Form

The quality tree is a high-level overview of the quality goals and requirements:

  • tree-like refinement of the term "quality". Use "quality" or "usefulness" as a root

  • a mind map with quality categories as main branches

In any case the tree should include links to the scenarios of the following section.

Diagrama de árbol de calidad

10.2. Escenarios de Calidad

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.

Calidad Escenario Acciones de usuario Respuesta

Usabilidad

Un usuario que nunca ha interactuado con la aplicación

El usuario quiere iniciar sesión y posteriormente jugar y que todo sea intuitivo

La aplicación facilita al usuario iniciar/registrar en la aplicación y posteriormente se le muestra la opción para jugar de forma visual

Rendimiento

Un usario, un poco impaciente y ya registrado quiere jugar tranquilamente una partida

Empieza la partida y espera a que se procese la pregunta y respuestas, sin importar cuantos usuarios esten jugando en ese momento

El sistema de obtención de preguntas es ágil y se muestra la pregunta con sus respuestas antes de que el usuario se canse de esperar

Testeable

Un desarrollador esta realizando una nueva funcionalidad del sistema, pero se equivoca y produce fallos en la aplicación

Igualmente realiza un commit en su rama con el objetivo de incorporar la nueva funcionalidad al sistema

Las pruebas automáticas detectan un error de programación e impide que el problema se propague a la aplicación funcional

Disponibilidad

Un usuario quiere jugar a las 03:00 AM, sin que ocurra ninguna caida por mantenimiento o cualquier otro error.

El usuario inicializa la aplicación de forma estandar

La aplicación es funcional pese a no ser una hora habitual

11. Riesgos y Deudas Técnicas

Contents

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

Motivation

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

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

Form

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

Further Information

See Risks and Technical Debt in the arc42 documentation.

11.1. Riesgos Técnicos

11.1.1. Riesgos internos

Riesgo Explicación

Abandono

Durante el desarrollo del proyecto cabe la posibilidad de que alguno de los miembros que conforman el equipo abandone este, provocando un serio problema el ritmo y carga de trabajo de los demás compañeros.

Otras Asignaturas

Las demás asignaturas en la que están matriculados los miembros del equipo puede exigir una carga importante de trabajo por lo que provocar que el equipo no dedique el suficiente tiempo al desarrollo de este proyecto.

Errores de diseño

Los errores que surjan debido al diseño, implementacion o gestion interna del proyecto; nos obligarán a realizar cambios e invertir más horas de las planeadas para solucionar este tipo de problemas.

11.1.2. Riesgos externos

Riesgo Explicación

Caída de Servicios

Nuestra aplicacion web puede verse comprometida a errores si alguno de los servicios utilizados, como por ejemplo Docker, parara de funcionar en algún momento. Ya que los servicios no son creados por nosotros no podemos saber si estarán disponibles en todo momento por lo tanto esto podría bloquear la entrega de alguna de las funcionalidades del proyecto.

Problemas Software

No podemos asegurar que nuestra aplicación pueda ser utilizada por todos los usuarios ya que en ciertos casos dependerá del sistema operativo de cada usuario.

Problemas Hardware

Dependiendo desde el dispositivo que se acceda a la aplicación si este no cumple los requisitos, como la resolución de pantalla, puede ser que la aplicacion no se vea de la forma esperada.

11.2. Deudas Técnicas

Descripción Consideraciones

Pruebas E2E

Se han impletado pruebas e2e pero finalmente solo hemos sido capaces de sacar una adelante con exito. Por falta de tiempo no hemos encontrado los errores en las pruebas por lo que nos hemos visto obligados a eliminarlas.

Botón finalizar partida

Después de finalizar la partida, añadimos un botón con la intención de que al pulsarlo guardara las estadísticas y nos redirigiera a la página principal. Sin embargo, al no lograr que con esta implementación nos pasase los test, optamos por modificarlo para que muestre la opción de elegir si desea guardar las estadísticas y, en dicho caso, muestre un mensaje. Podria dar confusión a los usuarios ya que se puede dar el caso que no sepan como jugar otra partida.

Mostrar tiempo de respuesta

Hemos intentado incorporar como estadísitica el tiempo de respuesta medio de las preguntas, pero lamentablemente no hemos podido lograrlo debido a que optamos por centrarnos en arreglar problemas del proyecto. Esta funcionalidad habría sido beneficiosa para mejorar el apartado de las estadísticas de nuestra aplicación.

Requisitos opcionales

No hemos abordado los requisitos opcionales porque nuestra atención ha estado centrada en desarrollar la parte fundamental de la aplicación y asegurarnos de que funcione correctamente.

Internacionalización de la web

Inicialmente, valoramos adaptar la aplicación a otros idiomas como el inglés pero finalmente no se llevo a cabo. Esto hace que la aplicación sea menos accesible para aquellos usuarios que no tengan el español como lengua principal.

Limpieza y organización de código

Nuestro código podría tener áreas que podrían mejorarse, ya que no se han desarrollado de la manera más eficiente posible. Una estructura más organizada podría facilitar la localización de elementos y la inclusión de comentarios adicionales podría mejorar la comprensión. Esta situación hace que sea complicado mantener, ampliar y depurar el código. Por lo tanto, es crucial realizar revisiones regulares del código, refactorizaciones y actualizaciones de la documentación para garantizar la calidad y la facilidad de mantenimiento del código del proyecto.

12. Testing

12.1. Tests unitarios (TDD)

Para los tests unitarios utilizamos Jest y Testing Library de React para probar los componentes de nuestra aplicación web.

Creamos pruebas separadas para cada componente, con el fin de probar partes aisladas y verificar si cada aspecto de nuestra aplicación funcionaba correctamente, pero enfrentamos algunos problemas en el proceso, ya que resultó ser casi imposible verificar todo, principalmente debido a problemas de tiempo y dificultad para probar los errores.

En el momento de escribir este documento, alcanzamos una cobertura total del 91% con 14 archivos tests para los componentes, 8 de ellos cubiertos al 100%.

12.2. Tests de integración (BDD)

Utilizamos Jest y Puppeteer para realizar pruebas de integración en nuestra aplicación. Diseñamos pruebas e Historias de Usuario con la estructura: "Dado, Cuando, Entonces", lo que resultó en muchas facilidades al implementarlas.

Al final, logramos tener 3 pruebas generales e2e, pero solo conseguimos que funcionase la primera en el despliege.

1 Feature: Registering a new user
Scenario: The user is not registered in the site
    Given An unregistered user
    When I fill the data in the form and press submit
    Then A confirmation message should be shown in the screen
2 Feature: Logging in as a user
Scenario: Logging in with valid credentials
    Given A user that is logged in the application
    When I enter valid username and password
    Then A confirmation message should be shown in the screen
3 Feature: Access the app
Scenario: A registered user enters the app
    Given A user that is logged in the application
    When I navigate to the Home page
    Then I should be able to interact with the app

12.3. Tests de carga

Se ha realizado los siguientes tests de carga con las acciones de:

  1. Registrarse

  2. Iniciar Sesion

  3. Jugar una Partida.

La primera prueba se lanzo solamente con un usuario, podemos observar que se han realizado 11 peticiones donde solo una tardo mas de 800 milisegundos.

Test de carga de 1 usuario

La siguiente prueba se lanzo con 10 usuarios, podemos observar que se han realizado 110 peticiones, la mayoria han pasado en menos de 800 milisegundos y una ha fallado.

Test de carga de 10 usuario

Podemos concluir que a partir de las 100 peticiones, el sistema comienza a tener fallos.

13. Glosario

Contents

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

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

Motivation

You should clearly define your terms, so that all stakeholders

  • have an identical understanding of these terms

  • do not use synonyms and homonyms

Form

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

Potentially more columns in case you need translations.

Further Information

See Glossary in the arc42 documentation.

Término Definición

API Rest

Interfaz de programación de aplicaciones que permite interactuar con un sistema para obtener datos o ejecutar una función, de manera que el sistema comprenda la solicitud y la cumpla.

Arc42

Un marco de arquitectura que proporciona un conjunto de prácticas y plantillas para documentar y diseñar arquitecturas de software.

Docker

Plataforma de código abierto que automatiza el despliegue de aplicaciones dentro de contenedores de software.

MongoDB

Es un sistema de gestión de bases de datos NoSQL de código abierto que permite el almacenamiento de datos de forma flexible y escalable. MongoDB es ampliamente utilizado en diversas aplicaciones, ofreciendo una estructura de datos dinámica que se adapta bien a casos de uso donde se requiere una manipulación ágil de la información.

Saber y Ganar

Programa televisión española de tipo concurso de preguntas y respuestas culturales.

TypeScript

Lenguaje de programación de código abierto desarrollado por Microsoft que es un superset de JavaScript y añade tipos estáticos opcionales a la sintaxis del lenguaje.

WCAG

Son una serie de pautas de accesibilidad web publicadas por la Iniciativa de Accesibilidad Web (WAI) del Consorcio World Wide Web (W3C). Estas pautas explican cómo hacer que el contenido web sea más accesible para las personas con discapacidades.

Web App

Interfaz de usuario en el navegador del cliente. Permite al usuario interactuar con el servidor, enviar solicitudes y recibir respuestas.

WikiData

Base de datos colaborativa libre que almacena datos estructurados para respaldar proyectos de la Fundación Wikimedia.

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.