About arc42

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

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

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

Note

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

1. Introduction and Goals

Saber y Ganar es el proyecto de Arquitectura de Software desarrollado por el equipo 6A. Los integrantes de este equipo son:

  • Ángel Luis Álvarez Iglesias

  • Álvaro García Miranda

  • Ben James Coleman Kheyyali

  • Eloy Martín Reig

  • Óscar Abad López

  • Sara Fernández González

Con el profesor: Jorge Álvarez Fidalgo

Este proyecto consiste en una aplicación con un juego de preguntas y respuestas. Además los usuarios registrados podrán ver sus estadísticas y las de otros jugadores.

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

1.1. Requirements Overview

  • El sistema permitirá a los usuarios registrarse e iniciar sesión.

  • El sistema permitirá a los usuarios acceder a un juego de preguntas en el que tendrán un tiempo para contestar. Este juego consistirá en una pregunta con cuatro posibles respuestas generado de manera automática.

  • El sistema permitirá a los usuarios ver sus estadísticas así como el historial de sus preguntas respondidas.

  • El sistema permitirá a los usuarios buscar a otros usuarios y ver sus estadísticas de juego.

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.

1.2. Quality Goals

Segun ISO/IEC 25010

Objetivo de Calidad Realización Prioridad

Usabilidad

Para que la aplicación sea usable se buscará mantener un diseño uniforme y basarse en la predictibilidad para que el aprendizaje de uso de la aplicación sea sencillo y para que no se complique la experiencia del usuario.

5

Testabilidad

Se realizarán pruebas lo más exhaustivas posible para asegurar el correcto funcionamiento de todos los servicios presentes en la aplicación.

4

Fiabilidad

Se buscará que el uso de recursos dentro de la aplicación sea lo más optimizado posible para que el funcionamiento de la aplicación no se vea afectado en velocidad o eficacia.

4

Seguridad

Se debe buscar cumplir unos mínimos para que no sea fácil el acceso a cuentas que no te pertenecen y que la información de los usuarios no quede fácilmente expuesta. Pero no es uno de los objetivos clave.

1
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

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 Descripción Expectativas

Cliente

Nuestro cliente es la empresa ficticia HappySw, este papel es realizado por los profesores de la asignatura.

Una aplicación que cumpla todos los requisitos enumerado en 1.1

Equipo de desarrollo

Los alumnos parte de este trabajo que han sido nombrados en la introducción.

Desarrollar una aplicación completa que tenga un reflejo adecuado en la documentación. Tiene que cumplir con los requisitos impuestos y además demostrar el trabajo puesto en el proyecto.

Usuarios

Las personas objetivo de la aplicación que probarían o usarían el producto final. Los jugadores.

Un juego divertido que funcione bien y que haga preguntas diversas para que suponga algún reto.

2. Architecture Constraints

Restricciones de arquitectura Descripción

Tecnología de Desarrollo

El equipo de desarrollo debe desarrollar la aplicación empleando tecnologias web compatibles con los requerimientos y estandares actuales de RTVE.

Plataforma de Implementación

La aplicación deberá implementarse sobre una plataforma de alojamiento web que cumpla con los requisitos de rendimiento, seguridad y escalabilidad de RTVE.

Cumplimiento de Normativas de Privacidad

La arquitectura debe seguir las regulaciones de privacidad de datos actualizadas para garantizar la privacidad de los concursantes.

Compatibilidad con Navegadores

Para garantizar una experiencia de usuario consistente, la aplicación debe ser compatible con un gran abanico de navegadores web seguros.

Seguridad de la Información

La solicitud deberá seguir estas medidas de seguridad: autenticación de concursantes, control de acceso y cifrado de datos; con el fin de proteger la información confidencial de los concursantes, pero permitiéndoles comprobarla.

Escalabilidad

La arquitectura debe ser escalable para manejar un mayor número de concursantes sin comprometer el rendimiento.

Mantenibilidad del Código

La mejor opción es emplear técnicas de desarrollo de software que promuevan un código limpio y bien documentado. Esto facilitará la actualización y el mantenimiento.

Tiempo de Desarrollo

El equipo de desarrollo deberá desarrollar la aplicación cumpliendo los plazos establecidos. Incluso si eso significa utilizar tecnologías de desarrollo alternativas o cambiar las decisiones arquitectónicas originales.

3. System Scope and Context

3.1. Business Context

business

3.2. Technical Context

technical

4. Solution Strategy

Restricciones de arquitectura

Descripción

Solución Estratégica

Elaboramos una aplicacíon, basada en Saber y Ganar, en la que los concursantes pueden registrarse para participar, donde en cada ronda tendran que responder varias preguntas, de distintas categorias, donde se guardará un registro con las preguntas respondidas por el usuario y podrá revisar su histórico, también podrá ver que preguntas acerto y cuales falló.

Tecnologías usadas para llevar a cabo

* MongoDB: MongoDB es una base de datos NoSQL de código abierto y orientado a documentos. Guarda la información en estructuras de datos BSON (una especificación similar a JSON) con un esquema dinámico, haciendo que la integración de los datos en ciertas aplicaciones sea más fácil y rápida. * React JS: Es un framework creado por Facebook ampliamente utlizado para crear componentes de la interfaz de usuario. Escogido por el gran volumen de documentación y por tratar de simplicar la creación de interfaces interactivas de usuario. * WikiData: Es una base de conocimientos gratuita modificada tanto por seres humanos como por máquinas, y es de donde obtendremos la información para nuestras preguntas. * IntelliJ IDEA: entorno de desarrollo integrado para el desarrollo de programas informáticos. Se emplea para desarrollar la documetación y para el desarrollo de la aplicación

Diseño

Empleamos un diseño que respetará el estilo mítico del programa de televisión, pero que también cumpliera con lo solicitado, que cada participante tendrá su propia cuenta donde se guardará su información (su puntuación, el hitórico de preguntas…​).

Seguridad

Uno de nuestros principales objetivos a cumplir es la seguridad del usuario, permitiendole acceder a su respectiva información sin riesgos.

Testabilidad

Se realizarán pruebas para cada parte individual de la aplicación, para asegurar el correcto funcionamiento de los diferentes modulos individuales. También se realizarán pruebas tras la unificación del proyecto, con el fin de garantizar que la aplicación final se encuentre en buen estado y no se han producido errores de merge.

4.1. Interfaz

La interfaz gráfica será elegida entre todos los miembros del equipo, decidiendo que diseño o idea se ajusta mejor a la aplicación esperada y que elementos resultan más adecuados. Para ello se tendrán en cuenta las necesidades de los difentes tipos de usuarios.

5. Building Block View

5.1. Whitebox of the Overall System

whitebox-overall-system
Motivation

WIQ es una aplicación Web en la que los usuarios puedan registrarse y entrar a jugar. El juego consiste en responder una serie de preguntas de diferentes tipos y temáticas obteniendo un premio por cada pregunta acertada. Un aspecto importante del sistema es que las preguntas serán generadas automáticamente a partir de los datos de Wikidata (https://www.wikidata.org/).

Contained Building Blocks
Nombre Responsabildad

Usuario

Interactúa con la aplicación.

WIQ

Aplicación con la que interactúa el usuario. Se comunica con Wikidata para generar preguntas automáticamente.

Wikidata

Base de datos colaborativa de conocimiento libre que almacena datos estructurados.
level-1
Motivation

Muestra los principales componentes de WIQ.

Contained Building Blocks
Nombre Responsabildad

Usuario

Interactúa con el frontend web de la aplicación.

Frontend Web

Componente responsable de la interfaz de usuario del sistema. Proporciona acceso a las funcionalidades del sistema a través de un navegador web.

Backend

Contiene la lógica de negocio y la gestión de datos del sistema. Expone endpoints para interactuar con los clientes a través de API.

MongoDB

Sistema de gestión de bases de datos NoSQL, que utiliza un modelo de datos flexible basado en documentos JSON con esquemas dinámicos.

Wikidata

Base de datos colaborativa de conocimiento libre que almacena datos estructurados.

6. Runtime View

6.1. Runtime Level 1

6.1.1. Registro de usuario

El registro de usuarios en la aplicación se gestiona a través del microservicio de usuario (userservice). El usuario introduce un nombre y una contraseña y, si el usuario se crea correctamente, se muestra un mensaje de confirmación. En caso contrario, se muestra un mensaje de error.

runtime 6 1 1

6.1.2. Inicio de sesión

El inicio de sesión de la aplicación se gestiona a través del microservicio de autenticación (authservice). El usuario introduce sus credenciales y, si los datos son verídicos, se muestra una vista de la aplicación con las opciones disponibles.

runtime 6 1 1

7. Deployment View

Content

The deployment view describes:

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

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

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

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

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

Motivation

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

Form

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

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

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

Further Information

See Deployment View in the arc42 documentation.

7.1. Infrastructure Level 1

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

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

  • important justifications or motivations for this deployment structure

  • quality and/or performance features of this infrastructure

  • mapping of software artifacts to elements of this infrastructure

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

<Overview Diagram>

Motivation

<explanation in text form>

Quality and/or Performance Features

<explanation in text form>

Mapping of Building Blocks to Infrastructure

<description of the mapping>

7.2. Infrastructure Level 2

Here you can include the internal structure of (some) infrastructure elements from level 1.

Please copy the structure from level 1 for each selected element.

7.2.1. <Infrastructure Element 1>

<diagram + explanation>

7.2.2. <Infrastructure Element 2>

<diagram + explanation>

…​

7.2.3. <Infrastructure Element n>

<diagram + explanation>

8. Cross-cutting Concepts

Content

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

  • models, especially domain models

  • architecture or design patterns

  • rules for using specific technology

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

  • implementation rules

Motivation

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

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

Form

The form can be varied:

  • concept papers with any kind of structure

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

  • sample implementations, especially for technical concepts

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

Structure

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

  • Domain concepts

  • User Experience concepts (UX)

  • Safety and security concepts

  • Architecture and design patterns

  • "Under-the-hood"

  • development concepts

  • operational concepts

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

Possible topics for crosscutting concepts
Further Information

See Concepts in the arc42 documentation.

8.1. <Concept 1>

<explanation>

8.2. <Concept 2>

<explanation>

…​

8.3. <Concept n>

<explanation>

9. Architecture Decisions

Contents

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

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

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

Motivation

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

Form

Various options:

  • ADR (Documenting Architecture Decisions) for every important decision

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

  • more detailed in form of separate sections per decision

Further Information

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

10. Quality Requirements

A continuación se muestra el árbol de atributos de calidad, cuyas hojas son los escenarios de calidad descritos en la tabla.

10.1. Quality Tree

Quality Tree

10.2. Quality Scenarios

Table 1. Quality Scenarios
Atributo de Calidad Descripción

SC1

Para mantener la usabilidad de la aplicación, se buscará mantener un diseño uniforme.

SC2

Para no complicar el aprendizaje de uso, la experiencia del usuario se basará en la predictabilidad.

SC3

Se realizarán pruebas exhaustivas para asegurar el correcto funcionamiento de todos los servicios presentes en la aplicación.

SC4

Para mantener la fiabilidad, se buscará un uso de recursos optimizado.

SC5

Se buscará un rendimiento eficiente y rápido para no afectar la experiencia de usuario.

SC6

En cuanto a la seguridad, se bloqueará el acceso a cuentas ajenas.

SC7

Se mantendrán los datos de usuario privados y seguros.
Nota del editor:

A medida que se desarrolla el proyecto, se actualizará esta sección con escenarios de calidad más específicos.

11. Risks and Technical Debts

A continuación, se presentan en formato tabla los riesgos y posibles deudas técnicas consideredas por el equipo de desarrollo.

Table 2. Development Team Risks
Riesgo Descripción Medida Preventiva

Faltas de comunicación entre los miembros del equipo.

Las faltas de comunicación podrán causar conflictos en la aplicación desarrollada, que supone una deuda técnica.

Se hará uso de varias vías de comunicación para evitar faltas y despejar dudas. Ejemplos de estos son Discord y WhatsApp.

Posible abandono de algún miembro del equipo.

El abandono debido a la carga de trabajo incurrirá una deuda técnica que deberá compensar el resto de miembros del equipo.

Se repartirán las tareas en grupos de trabajo de 2 o más miembros para minimizar el impacto que supondría un abandono.

Inexperiencia con las tecnologías empleadas.

Debido a la posible inexperiencia con las tecnologías empleadas en el proyecto, se pueden producir deudas técnicas.

Para minimizar el impacto, se recomienda investigar y probar las tecnologías para alcanzar un grado de control mínimo sobre ellas.
Table 3. Software Risks
Riesgo Descripción Medida Preventiva

Conflictos en el repositorio GitHub.

El acceso múltiple y simultáneo al repositorio desde varios usuarios supone un riesgo de sobreescritura y conflictos de código.

Se hará uso de ramas de trabajo para realizar las tareas, además de las vías de comunicación para coordinar las modificaciones al repositorio.

Conflictos con los programas desarrollados.

El trabajo en paralelo sobre los módulos de la aplicación supone un riesgo de conflicto si no hay estándares para código común a dichos módulos.

Se planteará una plantilla de código o nomenclatura de clases, métodos, etc común para aquellos módulos que tengan puntos en común.
Nota del editor:

A medida que se desarrolla el proyecto, se actualizará esta sección con los riesgos o deudas técnicas consideradas para los ámbitos de la aplicación.

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>