Acerca de arc42

arc42, La plantilla de documentación para arquitectura de sistemas y de software.

Por Dr. Gernot Starke, Dr. Peter Hruschka y otros contribuyentes.

Revisión de la plantilla: 7.0 ES (basada en asciidoc), Enero 2017

© Reconocemos que este documento utiliza material de la plantilla de arquitectura arc42, https://www.arc42.org. Creada por Dr. Peter Hruschka y Dr. Gernot Starke.

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

Describe los requerimientos relevantes y las directrices que los arquitectos de software y el equipo de desarrollo deben considerar. Entre estas se incluyen:

  • Objetivos empresariales subyacentes, características esenciales y requerimientos funcionales para el sistema

  • Metas de calidad para la arquitectura

  • Las partes interesadas pertinentes y sus expectativas

Nuestro equipo de desarrollo ha sido contratado por la empresa HappySW para la creación de una aplicación de preguntas y respuestas similar al programa de RTVE "Saber y Ganar". Nuestro objetivo para este proyecto será:

  • Crear una aplicación web con preguntas creadas automáticamente, haciendo así un juego mucho más dinámico y actualizado.

  • Los usuarios podrán crear su propia cuenta para acceder al historial de sus partidas.

1.1. Vista de Requisitos

Contenido

Descripción corta de los requerimientos funcionales, motivaciones, extracto (o resumen) de los requerimientos. Ligar a los documentos de requerimientos determinados (Con número de versión e información de donde encontrarla).

Motivación

Desde el punto de vista de los usuarios finales un sistema es creado o modificado para mejorar el soporte a una actividad de negocio o incrementar su calidad

Forma

Descripción corta textual, probablemente en un formato de caso de uso tabular. Si existen documentos de requerimientos esta vista debe referir a dichos requerimientos

Mantenga estos extractos tan cortos como sea posible. Encuentre el balance entre la legibilidad y la redundancia de este documento respecto a los documentos de requerimientos que se encuentren relacionados.

A continuación se muestran los requisitos de alto nivel para el desarrollo del juego.

Requisito Descripción

Creación de usuarios

Para acceder al juego, el usuario tendrá que estar registrado en la aplicación.

Historial

Un usuario registrado podrá consultar los resultados de sus anteriores partidas a través de un historial.

Preguntas creadas automáticamente

A partir de los datos de Wikidata se crearán las preguntas del juego, asi como sus respuestas.

Condiciones de juego

Habrá un tiempo limitado de respuesta para cada pregunta

Acceso a información por parte del Sistema

El sistema tendrá acceso a la información de los usuarios, además de las preguntas generadas.

Para información más detallada, se puede consultar el documento completo proporcionado por la empresa aquí .

1.2. Metas de Calidad

Contenido

Las tres metas de calidad principales (o hasta cinco) cuyo cumplimiento sea de la mayor importancia para las principales partes interesadas. Nos referimos a las metas de calidad para la arquitectura. No confundir con las metas del proyecto. No necesariamente son idénticas.

Motivación

Debe conocer las metas de calidad de las partes interesadas más importantes, ya que ellos influenciarán las decisiones arquitectónicas principales. Asegúrese de ser muy concreto con las descripciones, evitando buzzwords. Si como arquitecto no conoce la calidad de su trabajo, será juzgado…​

Forma

Una tabla con metas de calidad y escenarios concretos, ordenados por prioridades

Atributo de calidad Descripción

Usabilidad

La interfaz de usuario será sencilla de entender y de usar

Adaptabilidad

La aplicación se podrá usar en distintos dispositivos

Disponibilidad

La aplicación estará disponible y funcionando la mayoría del tiempo

Seguridad

Los datos personales del usuario serán guardados de manera segura

1.3. Partes interesadas (Stakeholders)

Contenido

Vista detallada de las partes interesadas del sistema, es decir, toda persona, rol u organización que:

  • Debe conocer la arquitectura

  • Debe estar convencida de la arquitectura

  • Tiene que trabajar con la arquitectura o con el código

  • Necesitan la documentación de la arquitectura para su trabajo

  • Intervienen en las decisiones acerca del sistema o su desarrollo

Motivación

Debe conocer a todas las partes involucradas en el desarrollo del sistema o que son afectadas por el sistema. De otro modo, se topará con sorpresas desagradables durante el proceso de desarrollo. Estas partes relacionadas o stakeholders determinarán la extensión y el nivel de detalle del trabajo y sus resultados

Forma

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

Rol Contacto con la aplicación Expectativas

Usuarios

Interaccionan directamente con la aplicación

Esperamos que el usuario considere nuestra aplicación divertida, accesible y usable. Además de que las preguntas les parezcan interesantes y no repetitivas

Equipo de desarrollo

Son las personas encargadas de realizar el proyecto

Crear una aplicación sólida y mantenible en el tiempo, aprendiendo nuevas tecnologías

RTVE

Es la empresa contratante

Espera obtener una versión online experimental de un concurso de preguntas y respuestas similar a “Saber y Ganar”

HappySw

Es la empresa de desarrollo de software

Que el equipo de desarrollo realice un producto de buena calidad para que la empresa contratante este satisfecha con el producto final

Profesores Arquitectura del Software

Personas encargadas de evaluar el proyecto

Esperan que el equipo de desarrollo cumpla con los requisitos obligatorios en la aplicación final

2. Restricciones de la Arquitectura

Contenido

Cualquier requerimiento que restrinja a los arquitectos de software en la libertad de diseño y la toma de decisiones sobre la implementación o el proceso de desarrollo. Estas restricciones a veces van más allá de sistemas individuales y son validos para organizaciones y compañías enteras.

Motivación

Los arquitectos deben saber exactamente sus libertades respecto a las decisiones de diseño y en donde deben apegarse a restricciones. Las restricciones siempre deben ser acatadas, aunque en algunos casos pueden ser negociables.

Forma

Tablas de restricciones con sus explicaciones. Si se requiere, se pueden subdividir en restricciones técnicas, organizacionales y/o políticas y convenciones (por ejemplo, guías de versionado o programación, convenciones de documentación o nombrado)

2.1. Restricciones técnicas

Restricción Explicación

API Wikidata

Las preguntas y soluciones a estas deben ser generadas a través de la API de Wikidata, que permite acceder a toda la información alojada en ella. Sin embargo, esta información puede ser poco fiable debido a que es de acceso público y puede ser modificada por cualquiera. También se debe tener en cuenta la estructura de Wikidata a la hora de acceder a los datos, ya que se basa en entidades y relaciones, además del tiempo de acceso a esta API la cual puede ralentizar el juego.

Desplegar la aplicación en un servidor

La aplicación se debe desplegar en un servidor y que esta sea accesible desde un navegador. En este caso, para desplegar la aplicación se usa una máquina virtual creada en Azure, lo que puede suponer un problema si no se usa cuidadosamente ya que se puede agotar el crédito gratuito.

GitHub

Todo el código de la aplicación se alojará en GitHub y se usarán ramas para ejecutar cualquier tipo de cambio significativo a la aplicación. Los commits deben tener nombres explicativos y podría haber conflictos en los merge.

Pruebas

Se crearán pruebas de distintos tipos. La aplicación debe pasar estas pruebas para asegurar su funcionamiento, el fallo de alguna de las pruebas bloqueará el despliegue.

2.2. Restricciones de organización

Restricción Explicación

Equipos de 4-6 personas

El trabajo será repartido entre 4-6 miembros del grupo. Estos deberán coordinarse para llevar a cabo el trabajo en conjunto.

Actas e Issues

Todas las decisiones y trabajo hecho se debe ver reflejado en el GitHub del grupo. Cada semana se deben hacer actas donde se tomen decisiones y se reparta el trabajo, que se verá reflejado en los issues.

Evaluaciones intermedias

Cada 3 semanas el proyecto será evaluado y se tomarán nota de los avances y correcciones que se deben hacer para la siguiente evaluación

2.3. Restricciones políticas

Restricción Explicación

Documentación en formato Arc42

La documentación debe seguir la estructura Arc42.

3. Alcance y Contexto del Sistema

Contenido

El alcance y contexto del sistema - como lo sugiere el nombre - delimita al sistema (es decir, el alcance) de todos sus socios de comunicación (Usuarios y sistemas vecinos, es decir, el contexto del sistema). 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). Con ello se especifican las interfaces externas.

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

Motivación

Las interfases de dominio y las interfases técnicas a los socios de comunicación son de los aspectos más críticos del sistema. Se debe asegurar el entendimiento de ellos.

Forma

Varias opciones:

  • Diagramas de contexto

  • Listas de socios de comunicación y sus interfases.

3.1. Contexto de Negocio

Contenido

La especificación de todos los socios de comunicación (usuarios, sistemas, …​) con explicaciones de las entradas y salidas específicas del dominio o interfases. Opcionalmente puede agregar formatos específicos de dominio o protocolos de comunicación

Motivación

Todas las partes interesadas deben entender que datos son intercambiados con el ambiente del sistema.

Forma

Cualquier forma de diagramas que muestren al sistema como una caja negra y especifiquen las interfases de dominio a los socios de comunicación.

De manera alternativa (o adicional) se puede utilizar una tabla. El título de la tabla es el nombre del sistema, las tres columnas contienen el nombre del socio de comunicación, las entradas y las salidas

Contexto de negocio

Socio de Comunicación

Entrada

Salida

Usuario

-

Uso del juego

Base de Datos

Guarda información relevante de la aplicación (usuarios, preguntas base)

Envía la información requerida a la aplicación

API Wikidata

Recibe una consulta relacionada con la pregunta a construir

Envía los datos que la aplicación ha pedido para la pregunta

3.2. Contexto Técnico

Contenido

Las interfases técnicas (medios de transmisión y canales) enlazando al sistema con su ambiente. De manera adicional el mapeo de las entradas/salidas específicas del dominio a los canales, es decir, una explicación acerca de que entrada/salida utiliza cual canal.

Motivación

Muchas partes relacionadas realizan decisiones arquitectónicas basadas en las interfases técnicas entre el sistema y su contexto. Especialmente los diseñadores de infraestructura o hardware deciden estas interfases técnicas.

Forma

Por ejemplo, diagramas UML de despliegue describiendo los canales a sistemas vecinos, junto con una tabla de mapeo mostrando las relaciones entre los canales y las entradas/salidas.

Contexto técnico

Tecnologías utilizadas

Descripción de uso

Azure Cloud

Utilizado para el despliegue de la aplicación

MongoDB

Base de datos NoSQL para guardar la información de la aplicación, como los usuarios y las preguntas base

Navegadores

Permiten al usuario acceder a la aplicación una vez desplegada

React, JavaScript, HTML, CSS

Lenguajes utilizados para la creación del juego

4. Estrategia de solución

Contenido

Un resumen corto y explicación de las estrategias y decisiones fundamentales para la solución que le dan forma a la arquitectura del sistema. Estas incluyen:

  • Decisiones tecnológicas

  • Decisiones acerca de la descomposición a alto nivel de un sistema, por ejemplo, el uso de algún patrón de diseño o de arquitectura.

  • Decisiones en como alcanzar metas de calidad claves

  • Decisiones organizacionales relevantes, como el seleccionar un proceso de desarrollo o delegar ciertas tareas a terceros.

Motivación

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

Forma

Realice la explicación de las decisiones clave de manera breve.

Justifique las decisiones y porque se realizaron de esa manera, basado en el planteamiento del problema, las metas de calidad y restricciones clave. Refiérase a los detalles en las secciones posteriores.

4.1. Decisiones Tecnológicas

  • Microsoft Azure: es una plataforma de computación en la nube que ofrece servicios de infraestructura, plataforma y software como servicio, para poder administrar servicios en línea.

  • MongoDB: es un sistema de bases de datos NoSQL, es decir, una base de datos orientada a documentos. Este almacena datos con formato similar JSON, que no tienen que cumplir con una estructura predefinida.

  • JavaScript: es un lenguaje de programación interpretado, dialecto del estándar ECMAScript. Se utiliza para crear páginas web dinámicas.

  • React: es una biblioteca de JavaScript para construir interfaces de usuario.

  • WikiData: es una base de datos libre, colaborativa y multilingüe, que sirve como una base de datos secundaria y que recopila datos estructurados para dar soporte a Wikipedia, Wikimedia Commons…​

  • Docker: se utiliza para hacer el despliegue de la aplicación.

  • Bootstrap: es un framework de código abierto para el diseño de sitios y aplicaciones web.

4.2. Motivaciones

Hemos escogido TypeScript por su mayor parecido a Java, ya que nuestro equipo en su mayoría lo domina. En cuanto React nos basemos en que fácilmente se puede crear interfaces. El resto de tecnologías son las más óptimas y las preestablecidas, en el proyecto. Realmente estamos a la espera de los resultados de estas decisiones, ya que en su mayoría son tecnologías desconocidas para el equipo.

  • Microsoft Azure: la universidad nos proporciona crédito para Azure, por lo que no tendremos que pagar por el servicio y es una plataforma que ya conocemos por otras asignaturas del grado.

  • MongoDB: el formato de los datos de MongoDB nos facilita mucho el guardado de datos en la aplicación

  • JavaScript: aunque no lo dominamos completamente, es un lenguaje que nos era familiar y muy usado en el desarrollo web, además combinamos su uso con la biblioteca de React.

  • React: esta biblioteca facilita el uso de los componentes de la aplicación y, además el proyecto inicial lo usaba por lo que no se ha tenido que construir la aplicación desde cero.

  • WikiData: su uso es un requisito obligatorio de esta aplicación pero su sistema de consultas SPARQL ha resultado muy útil a la hora de obtener las preguntas de forma dinámica y actualizada para el juego.

  • Docker: ya configurado en el proyecto inicial por lo que pudimos crear contenedores de forma sencilla.

  • Bootstrap: permite crear la interfaz de usuario de forma más sencilla y con diseños más agradables al cliente.

4.3. Decisiones sobre cómo alcanzar los objetivos clave de calidad

  • Usabilidad: Será una aplicación sencilla, sin demasiados distractores y con los enlaces necesarios para el funcionamiento correcto del juego únicamente. Se tratará de que resulte intuitiva y fácil de usar.

  • Seguridad: Se configurarán los endpoints para que un usuario no autentificado pueda acceder a partes restringidas de la aplicación. Además los usuarios serán guardados con su contraseña encriptada.

  • Disponibilidad: El uso de Azure nos garantiza un 99,9% de disponibilidad, aunque hay que restar la dependencia que tenemos con otros servicios como Wikidata o MongoDB, de todas maneras se tratará de que la aplicación tenga la mayor disponibilidad posible.

  • Utilizaremos el patrón MVC(Modelo, Vista, Controlador): Facilita la modularidad, la reutilización y el mantenimiento del código, provocando una aplicación eficiente.

4.4. Decisiones organizativas:

  • Las tareas se reparten teniendo en cuenta las habilidades de cada uno de los integrantes del equipo y su disponibilidad.

  • Los miembros del equipo mantenemos comunicación más directa a través de WhatsApp y Discord para las dudas que surjan u otras decisiones que haya que tomar en conjunto.

  • Si un miembro del equipo tiene problemas con su tarea, entre los integrantes del grupo se resolverá.

  • Durante el laboratorio de la asignatura, se realizarán reuniones en las que se expondrá el trabajo realizado y si alguno ha tenido algún problema con su tarea.

  • Si algún miembro decide abandonar el proyecto, se repartirán sus tareas pendientes entre los miembros restantes.

5. Vista de Bloques

Contenido

La vista de bloques muestra la descomposición estática del sistema en bloques de construcción (módulos, componentes, subsistemas, clases, interfases, paquetes, bibliotecas, marcos de desarrollo, capas, particiones, funciones, macros, operaciones, estructuras de datos,…​) así como sus dependencias (relaciones, asociaciones,…​)

Esta vista es obligatoria para cualquier documentación de arquitectura. Es la analogía al plano de una casa.

Motivación

Mantener una visión general de su código fuente haciendo su estructura comprensible de manera abstracta.

Esto permite comunicar a las partes interesadas en un nivel abstracto sin entrar en detalles de implementación.

Forma

La vista de bloques comprende una colección jerárquica de cajas negras y cajas blancas (ver figura de abajo) y sus descripciones.

Jerarquía de bloques de construcción

Nivel 1 comprende la descripción de Caja Blanca del sistema en general junto con las descripciones de Caja Negra de todos los bloques contenidos.

Nivel 2 hace zoom a los bloques de construcción del Nivel 1. Entonces contiene la descripción de Caja Blanca de los bloques de construcción seleccionadas del nivel 1,junto con las descripciones de caja negra de sus bloques de construcción internas.

Nivel 3 Hace zoom a los bloques selectos del nivel 2, y así sucesivamente.

Scope & Context

5.1. Sistema General de Caja Blanca

Aquí se describe la descomposición del sistema en general usando la siguiente plantilla de caja blanca. Contiene:

  • Un diagrama general

  • La motivación para la descomposición

  • Descripciones de caja negra de los bloques de construcción contenidos. Para estos se ofrecen las siguientes alternativas:

    • Usar una tabla para una revisión pragmática y corta de todos los bloques de construcción contenidos y sus interfaces

    • Usar una lista de descripciones de caja negra de los bloques de construcción acorde a la plantilla de caja negra (ver abajo). Dependiendo de la herramienta utilizada, esta lista podría constar de sub-capítulos (en archivos de texto), sub-páginas (en un wiki) o elementos anidados (en una herramienta de modelado).

  • (opcional:) Interfases importantes, que no están explicadas en las plantillas de caja negra de un bloque de construcción, pero que son muy importantes para entender la caja blanca. En el peor de los casos se deberá especificar y describir la sintaxis, semántica, protocolos, manejo de errores, restricciones, versiones, calidades, compatibilidades necesarias, entre otras. En el mejor de los casos bastará con ejemplos o la firma de los mismos.

Nombre Descripción

Wikidata

Para formular las preguntas se extraerá información de WikiData a través de su API.

Base de datos

Se guarda información importante, como los datos de los usuarios y sus historiales.

Users

Permite a los usuarios registrarse e identificarse, además de iniciar la aplicación.

Cliente

Accede a la aplicación y interactúa con ella a través de la interfaz de usuario.

5.2. Sistema general de caja negra

Inserte las explicaciones de las cajas negras del nivel 1:

Si usa la forma tabular solo describa las cajas negras con nombre y responsabilidad acorde al siguiente esquema:

Nombre Responsabilidad

<caja negra 1>

 <Texto>

<caja negra 2>

 <Texto>

Si utiliza una lista de descripciones de cajas negras entonces llene una plantilla de caja negra por cada bloque de construcción importante. El título es el nombre de la caja negra.

Nombre Descripción

Aplicación

Toda la aplicación se encapsula aquí.

5.2.1. <Caja Negra 1>

Aquí se describe la <caja negra 1> acorde a la siguiente plantilla:

  • Propósito/Responsabilidad

  • Interfases, cuando no son extraídas como párrafos separados. Estas interfases pueden incluir características de calidad y rendimiento.

  • (Opcional) Características de Calidad / Rendimiento de la caja negra, por ejemplo, disponibilidad, comportamiento en ejecución, …​

  • (Opcional) Ubicación archivo/directorio

  • (Opcional) Requerimientos satisfechos (si se necesita contar con la trazabilidad a los requerimientos).

  • (Opcional) Incidentes/problemas/riesgos abiertos

Level1
Nombre Descripción

Vista

Toda la parte gráfica de la aplicación y que se comunica con el usuario. Se comunica con el controlador a base de eventos producidos por el usuario.

Modelo

Lleva a cabo todos los cálculos necesarios para el funcionamiento de la aplicación. También se comunica con los sistemas para conseguir la información necesaria.

Controlador

Comunica la vista y el modelo. Es el encargado de controlar el flujo de la aplicación.

6. Vista de Ejecución

Contenido

La vista de ejecución describe el comportamiento concreto y la interacción de los bloques de construcción del sistema en forma de escenarios en las siguientes áreas:

  • Casos de uso o características importantes: ¿Cómo los ejecutan los bloques de construcción?

  • Interacciones en interfases externas críticas: ¿Cómo cooperan los bloques de construcción con los usuarios y sistemas vecinos?

  • Administración y operación: Carga, inicialización, detención.

  • Escenarios de error y excepción.

Observación: El criterio principal para la elección de los escenarios posibles (flujos de trabajo, secuencias) es su relevancia arquitectónica. No es importante describir un gran número de escenarios. Se debe documentar una selección representativa.

Motivación

Debe entenderse como las instancias de los bloques de construcción del sistema realizan su trabajo y se comunican en tiempo de ejecución. Deben capturarse principalmente los escenarios que comuniquen a las partes relacionadas que tengan problemas para comprender los modelos estáticos en la documentación (Vista de Bloques de Construcción, Vista de Despliegue).

Forma

Hay muchas notaciones para describir los escenarios, por ejemplo: * Lista numerada de pasos (en lenguaje natural). * Diagramas de flujo o de actividades * Diagramas de secuencia * BPMN o EPCs (Cadenas de procesos de eventos) * Máquinas de estado * …​.

6.1. Registrar usuario

Un usuario se registra para poder jugar.

Registrar usuario

6.2. Iniciar sesión

Un usuario que ya está registrado, inicia sesión con su usuario y contraseña para jugar.

Iniciar sesión

6.3. Ver historial

Un usuario quiere ver su historial del juego.

Ver historial

6.4. Jugar y generación de preguntas

Un usuario procede a jugar, se generan las preguntas y a continuación iniciará el juego.

Jugar

7. Vista de Despliegue

Contenido

La vista de despliegue describe:

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

  2. El mapeo de los bloques de construcción (software) en dichos elementos de infraestructura.

Comúnmente los sistemas son ejecutados en diferentes ambientes, por ejemplo, ambiente de desarrollo, de pruebas, de producción. En dichos casos deberían documentarse todos los ambientes relevantes.

Deberá documentarse la vista de despliegue de manera especial cuando el software se ejecute como un sistema distribuido con mas de una computadora, procesador, servidor o contenedor o cuando se diseñen los procesadores y chips de hardware propios.

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

Motivación

El software no corre sin hardware. El hardware subyacente puede influenciar el sistema o algunos conceptos entrecruzados. Por ende, es necesario conocer la infraestructura.

Forma

Quizá el más alto nivel de diagrama de despliegue esté contenido en la sección 3.2. como contexto técnico con la propia infraestructura como UNA caja negra. En esta sección se deberá realizar un acercamiento a ésta caja negra utilizando diagramas de despliegue adicionales:

  • UML provee diagramas de despliegue para expresar la vista. úselos, probablemente con diagramas anidados.

  • Cuando las partes relacionadas de Hardware prefieran otro tipo de diagramas además de los diagramas de despliegue, permítales usar cualquier tipo que permita mostrar los nodos y canales de la infraestructura.

7.1. Nivel de infraestructura 1

Describa (Usualmente en una combinación de diagramas, tablas y texto):

  • La distribución del sistema en múltiples ubicaciones, ambientes, computadoras, procesadores, …​ así como las conexiones físicas entre ellos

  • La motivación o justificación de importancia para la estructura de despliegue

  • Características de Calidad y/o rendimiento de la infraestructura

  • El mapeo de los artefactos de software a los elementos de la infraestructura.

Para múltiples ambientes o despliegues alternativos copie esta sección para todos los ambientes relevantes.

Motivación

Debido a los diferentes requisitos especificados para esta aplicación se ha decido seguir la estructura descrita más abajo. Se han escogido las herramientas de acuerdo a los medios disponibles ya que no se dispone de presupuesto para este proyecto y, además, algunas de ellas, como Azure, ya eran conocidas por el equipo por lo que es más sencillo su uso.

Características de Calidad/Rendimiento

Para una disponibilidad de la aplicación a los clientes desde un navegador de forma sencilla, se ha decido usar un servicio en la nube como Azure.

Mapeo de los Bloques de Construcción a Infraestructura

A continuación se muestra el diagrama de despliegue de esta aplicación:

Deployment View

7.2. Nivel de Infraestructura 2

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

Copie la estructura del nivel 1 para cada elemento elegido.

En el siguiente diagrama se ve más a fondo el despliegue de nuestra aplicación, así como los distintos componentes que forman el proyecto. Además se puede ver el uso de docker como forma de contenedor para después desplegarlo en Azure Cloud.

Deployment View

8. Conceptos Transversales (Cross-cutting)

Contenido

Esta sección describe de manera general, las principales ideas de solución y regulación que son relevantes en multiples partes (→ cross-cutting/transversales) del sistema. Dichos conceptos están relacionados usualmente a múltiples bloques de construcción. Pueden incluir diversos temas, tales como:

  • Modelos de dominio

  • Patrones de arquitectura o patrones de diseño

  • Reglas de uso para alguna tecnología específica.

  • Decisiones técnicas principales o generales

  • Reglas de implementación

Motivación

Conceptos que forman la base para la integridad conceptual (consistencia, homogeneidad) de la arquitectura. Entonces, son una contribución importante para alcanzar la calidad interna del sistema.

Algunos de estos conceptos no pueden ser asignados a bloques de construcción individuales (por ejemplo seguridad). Este es el lugar en la plantilla provisto para una especificación cohesiva de dichos conceptos.

Forma

La forma puede ser variada:

  • Papeles conceptuales con cualquier tipo de estructura

  • Modelo transversal (cross-cutting) de fragmentos o escenarios usando notación de las vistas arquitectónicas

  • Implementaciones de muestra, especialmente para conceptos técnicos.

  • Referencias a uso típico en frameworks estándar (por ejemplo, el uso de Hibernate para mapeo Objeto/Relacional) The form can be varied:

Estructura

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

  • Conceptos de dominio

  • Conceptos de experiencia de usuario (UX)

  • Conceptos de seguridad

  • Patrones de diseño y arquitectura * 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

  • "Bajo el capó"

  • Conceptos de desarrollo

  • Conceptos de operación

Nota: Puede ser difícil asignar conceptos individuales a un tema específico de la lista

Posibles temas para conceptos transversales

Modelo de la aplicación:

clase Usuario {
    username: String
    password: String
    createdAt: String
}

clase Record {
    username: String
    correctQuestions: int
    totalQuestions: int
    totalTime: int
    doneAt: Date
}

clase Pregunta {
    pregunta: String
    correcta: String
    incorrectas: Array<String>(3)
}

8.1. Arquitectura principal

Hemos decidido utilizar una arquitectura de microservicios, dividiendo la aplicación en módulos. Estos módulos a su vez, se estructurarán con el patrón MVC.

8.2. Reglas de implementación

Como es un proyecto en equipo creemos que la colaboración es lo más importante, por eso hemos decidido comentar lo máximo posible nuestro propio código para que sea entendible por otras personas/compañeros de equipo.

8.3. Interfaz de usuario.

Queremos crear una aplicación accesible para todos los usuarios, que sea simple de entender y de jugar, que lo máximo que tengas que pensar sean las preguntas del juego.

8.4. Privacidad

Los usuarios se tienen que autenticar para poder utilizar la aplicación, además sus contraseñas están encriptadas.

9. Decisiones de Diseño

Contenido

Decisiones arquitectónicas importantes, costosas, a larga escala o de riesgo incluyendo sus razonamientos. Con "Decisiones" nos referimos a la elección de una alternativa basada en cierto criterio.

Se debe usar el juicio para decidir si una decisión arquitectónica debe ser documentada en esta sección central o si sería preferible documentarla localmente (Por ejemplo, dentro de una plantilla de caja blanca de un bloque de construcción).

Evite la redundancia. Tomar de referencia la sección 4, donde ya se capturaron las decisiones más importantes para la arquitectura.

Motivación

Las partes relacionadas del sistema deben comprender y trazar las decisiones.

Forma

Varias opciones:

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

  • Mayor detalle en secciones separadas por cada sección.

  • Registro de Decisiones de Arquitectura (ADR por sus siglas en inglés) para cada decisión importante.

Problema Decisión Explicación

Base de datos

Usar MongoDB

Usaremos MongoDB porque ya está implementado en el sistema de login de usuarios.

Frontend

React

Usaremos React para crear las interfaces de usuario debido a su facilidad de uso.

BackEnd

Node.js

Escogimos Node.js debido a su compatibilidad.

Arquitectura

MVC

El modelo MVC nos permite separar las capas para mantener el código ordenado, mantenible y es familiar para los integrantes del grupo.

Arquitectura

Microservicios

El modelo de microservicios se ajusta muy bien a las necesidades de la aplicación.

10. Requerimientos de Calidad

Contenido

Esta sección describe todos los requerimientos de calidad como un árbol de calidad con escenarios. Los más importantes ya han sido descritos en la sección 1.2 (Metas de Calidad).

Aquí se capturan los requerimientos de calidad con menor prioridad, que no crearán altos riesgos en caso de que no sean cubiertos con totalidad.

Motivación

Dado que los requerimientos de calidad tendrán mucha influencia en las decisiones arquitectónicas deben tomarse en cuenta los elementos importantes para las partes relacionadas que sean concretas y medibles.

10.1. Árbol de Calidad

Contenido

El árbol de calidad (Definido en ATAM - Método de análisis de compensación de arquitectura por sus siglas en inglés) con escenarios de calidad/evaluación como hojas.

Motivación

La estructura de árbol con prioridades provee un vistazo general para un gran número de requerimientos de calidad.

Forma

El árbol de calidad es un vistazo a alto nivel de las metas de calidad y requerimientos:

  • Un refinamiento del término de "calidad" a manera de árbol. Utilice "calidad" o "utilidad" como raíz.

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

En cualquier caso incluya ligas a los escenarios de las siguientes secciones.

Quality Tree

10.2. Escenarios de calidad

Contenido

Concretar requisitos de calidad (que pueden ser vagos o implícitos) utilizando escenarios de calidad.

Estos escenarios describen lo que debería pasar 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 caso de uso), que describen la reacción en tiempo de ejecución de un sistema a un determinado estímulo. Esto incluye también escenarios que describen la eficiencia o el rendimiento del sistema. Por ejemplo: El sistema reacciona a la petición de un usuario en un segundo.

  • Escenarios de cambios, describen la modificación del sistema a su ambiente inmediato. Por ejemplo: Cuando se implementa funcionalidad adicional o requerimientos para el cambio de un atributo de calidad.

Motivación

Los escenarios crean requerimientos de calidad concretos y permiten medirlos de manera mas sencilla o decidir si han sido cumplidos.

Cuando se requiere evaluar la arquitectura utilizando métodos como ATAM se necesitan describir las metas de calidad (de la sección 1.2) de manera más precisa hasta un nivel de escenarios que pueden ser discutidos y evaluados.

Forma

Texto en forma libre o tabular.

Descripción

Atributo de calidad

Escenario

La aplicación tendrá una interfaz de usuario sencilla, con botones que indiquen que es cada cosa, y colores que harán que se entienda mejor

Usabilidad

El usuario quiere utilizar la aplicación con facilidad

La aplicación podrá ser usada en distintos dispositivos

Adaptabilidad

Un usuario podrá usar la aplicación en móvil, tablet u ordenador

La aplicación estará disponible el 95% del tiempo.

Disponibilidad

Un usuario accede a la aplicación a las 6 de la tarde y esta estará disponible

Los datos de cada usuario estarán guardados de forma segura

Seguridad

El usuario quiere que solo él pueda acceder a sus datos

11. Riesgos y deuda técnica

Contenido

Una lista de los riesgos técnicos o deuda técnica identificada, ordenada por prioridad.

Motivación

"El manejo de riesgos es administración de proyectos para gente adulta" (Tim Lister, Atlantic Systems Guild.)

Esto debiera ser el lema para la detección sistemática y la evaluación de riesgos y deuda técnica en la arquitectura, que será requerida por las partes relacionadas administrativas (por ejemplo, administradores de proyectos, propietarios de producto) como parte de la planeación y medición de riesgos en general.

Forma

Lista de riesgos y/o deuda técnica, que podría incluir una medidas sugeridas para minimizar, mitigar o evitar riesgos o reducir la deuda técnica.

11.1. Riesgos

Riesgo Explicación

Trabajo en equipo

La falta de coordinación y comunicación puede llevar a malos resultados en el trabajo. Tampoco tenemos experiencia trabajando en una aplicación desde 0.

Abandono de miembros del equipo

Si uno o más miembros abandonan el equipo de desarrollo, la carga de trabajo para el resto se incrementará y, por tanto, aumentará la probabilidad de errores y deuda técnica por falta de tiempo.

Falta de experiencia con WikiData

No estamos muy familiarizados con WikiData y su estructura. Tenemos que aprender a hacer queries a la API de WikiData.

Desconocimiento de algunas tecnologías utilizadas como NodeJS o React

Hasta el desarrollo de esta aplicación no habíamos trabajado con estas tecnologías y, por tanto, pueden ocasionar errores o retrasos durante el aprendizaje de las mismas.

11.2. Deuda Técnica

Se ha ocasionado deuda técnica en el proyecto debido en gran medida a la falta de tiempo y al abandono de 4 miembros del equipo, 2 de ellos nunca se presentaron y los otros 2 abandonaron la asignatura durante el desarrollo. A continuación se indican las principales decisiones tomadas que han ocasionado deuda técnica en este proyecto:

Deuda Técnica Explicación

Pruebas de carga

No se han podido realizar pruebas de carga ya que por los factores anteriormente indicados, decidimos priorizar las pruebas unitarias y las de end to end frente a las de carga.

Requisitos opcionales

Se ha priorizado aquellos requisitos obligatorios frente a los opcionales, pudiendo realizar solo uno de estos.

Rendimiento de las preguntas

Nos gustaría haber tenido el rendimiento como atributo de calidad pero debido al abandono de varios miembros del grupo se decidió dar prioridad a terminar el proyecto completo, que a mejorar otros aspectos como el rendimiento.

12. Pruebas realizadas

A continuación se recogen los diferentes tipos de pruebas realizados para garantizar el correcto funcionamiento de la aplicación y cumplir con el límite de coverage del 80% que se requería para el proyecto.

12.1. Pruebas Unitarias

Se han realizado un total de 43 pruebas unitarias repartidas entre los servicios y componentes de la aplicación. Se ha utilizado la librería Jest para realizar estas pruebas, además de otras más especializadas dependiendo del test como la librería de testing de React para los componentes o Axios para simular las llamadas a los endpoints.

Con estos test se ha conseguido cubrir un 90'9% del código presente en la aplicación, proporcionando una alta fiabilidad del correcto funcionamiento de la misma. A continuación se muestra el resumen proporcionado por SonarCloud sobre la calidad de nuestro código:

12 SonarCloud Coverage

12.2. Pruebas E2E (End to End)

Se han realizado 5 pruebas E2E a las funciones más importantes de la aplicación: Login, register, Game y Record. Estas pruebas se han realizado utilizando las librerías de Puppeteer y Jest-Cucumber, las cuales nos permiten probar su funcionalidad utilizando Chromium.

13. Glosario

Contenido

Los términos técnicos y de dominio más importantes que serán utilizados por las partes relacionadas al discutir el sistema.

También se puede usar el glosario como fuente para traducciones si se trabaja en equipos multi-lenguaje.

Motivación

Deberían definirse claramente los términos, para que todas las partes relacionadas:

  • Tengan un entendimiento idéntico de dichos términos

  • No usen sinónimos y homónimos

Forma

  • Crear una tabla con las columnas <Término> y <Definición>.

  • Se pueden agregar más columnas en caso de que se requieran traducciones.

Término Definición

GitHub

Plataforma de desarrollo colaborativo. Todo el código del equipo, su trabajo realizado y sus reuniones se documentan aquí.

MongoDB

Es un sistema de base de datos NoSQL, orientado a documentos. La base de datos de nuestra aplicación esta hecha con MongoDB.

MVC

Modelo de arquitectura de software. Las aplicaciones que siguen este modelo se dividen en 3 capas, Modelo, Vista y Controlador.

Node.js

Es un entorno en tiempo de ejecución para la capa del servidor basado en JavaScript. La usaremos para gran parte de el back-end de la aplicación.

Query

Conjunto de palabras o frase que se utiliza cómo término de búsqueda. Usaremos queries para conseguir información de la base de datos o de WikiData.

React

Biblioteca JavaScript diseñada para crear interfaces de usuario. La usaremos para hacer el front-end de la aplicación.

WikiData

Base de conocimientos con una gran cantidad de datos. Extraeremos datos de WikiData a través de la API que nos proporciona. Construiremos las preguntas con estos datos.