About arc42

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

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

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

Note

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

1. Introducción y Objetivos

Describe los requisitos relevantes y las fuerzas impulsoras que los arquitectos de software y el equipo de desarrollo deben considerar. Estos incluyen:

  • objetivos empresariales subyacentes,

  • características esenciales,

  • requisitos funcionales esenciales,

  • objetivos de calidad para la arquitectura y

  • partes interesadas relevantes y sus expectativas.

La aplicación WIChat permite a los usuarios participar a un concurso online de preguntas y respuestas similar a "Saber y Ganar".

El usuario ve una imagen en pantalla y puede seleccionar diferentes opciones para adivinar de que lugar se trata.

El usuario puede recibir pistas sobre la imagen hablando con el chat con inteligencia artificial incluido en el juego.

Tanto las pistas como las imágenes son generadas automaticamnete a partir de Wikidata (https://www.wikidata.org/)

1.1. Resumen de Requisitos

Contenido

Breve descripción de los requisitos funcionales, fuerzas impulsoras y un extracto (o resumen) de los requisitos. Enlace a documentos de requisitos existentes (si los hay) con número de versión e información sobre dónde encontrarlos.

Motivación

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

Forma

Breve descripción textual, probablemente en formato tabular de casos de uso. Si existen documentos de requisitos, este resumen debe referirse a ellos.

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

Más Información

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

  • Se deberá poder acceder desde la web.

  • El sistema mostrará imagenes, las respuestas y un sistema de pistas.

  • Los usuarios podrán registrarse en el sistema.

  • Los usuarios registrados podrán ver su historial de participaciones.

  • Se podrá interactuar con la aplicación para obtener pistas gracias a un modelo de lenguaje.

  • Las preguntas y las pistas serán genrados automaticamente a partir de los datos de Wikidata.

  • El sistema permitirá acceder a los datos de los usuarios y de las preguntas generadas mediante una API.

  • Habrá un plazo de tiempo determinado para responder a las preguntas.

1.2. Objetivos de Calidad

Contenido

Los tres principales (máximo cinco) objetivos de calidad para la arquitectura cuya realización es de mayor importancia para las partes interesadas principales. Nos referimos específicamente a objetivos de calidad para la arquitectura. No los confundas con los objetivos del proyecto; no son necesariamente idénticos.

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

Categorías de Requisitos de Calidad
Motivación

Debes conocer los objetivos de calidad de tus partes interesadas más importantes, ya que influirán en decisiones arquitectónicas fundamentales. Sé muy concreto acerca de estas cualidades y evita términos ambiguos. Si como arquitecto no sabes cómo se juzgará la calidad de tu trabajo…​

Forma

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

Prioridad Objetivos de calidad Escenarios concretos

1

Seguridad

Los datos de los usuarios (credenciales, historial de juegos) deben estar cifrados. El sistema debe prevenir ataques comunes (SQL injection, XSS).

2

Usabilidad

Los usuarios deben poder interactuar con el sistema de manera intuitiva, registrarse, jugar y obtener pistas con la menor dificultad posible. El tiempo de respuesta para mostrar una pregunta o pista no debe superar los 2 segundos.

3

Fiabilidad

El sistema debe garantizar una disponibilidad del 99%. Las pistas generadas por el LLM deben ser correctas en un 95% de los casos, minimizando alucinaciones y respuestas erróneas.

4

Rendimiento

El sistema debe soportar hasta 100 usuarios concurrentes sin degradación del rendimiento. El tiempo de respuesta de la API de Wikidata y del LLM no debe superar los 1000 ms en el 95% de las solicitudes.

5

Mantenibilidad

El código debe estar documentado y modularizado, permitiendo que todos los implicados en el desarrollo puedan trabajar con ello lo mejor posible.

1.3. Partes Interesadas

Contenido

Descripción explícita de las partes interesadas del sistema, es decir, todas las personas, roles u organizaciones que:

  • deberían conocer la arquitectura,

  • deben ser convencidos de la arquitectura,

  • tienen que trabajar con la arquitectura o con el código,

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

  • deben tomar decisiones sobre el sistema o su desarrollo.

Motivación

Debes conocer a todas las partes involucradas en el desarrollo del sistema o afectadas por él. De lo contrario, podrías enfrentarte a sorpresas desagradables más adelante en el proceso de desarrollo. Estas partes interesadas determinan el alcance y el nivel de detalle de tu trabajo y sus resultados.

Forma

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

Rol/Nombre Contacto Expectativas

Profesor/Jose Emilio Labra Gayo

http://labra.weso.es/

Que se emplee el conocimiento lo mejor posible para tomar las decisiones arquitectónicas más adecuadas favoreciendo el aprendizaje.

Profesor/Pablo González

https://pglez82.github.io/

Que se emplee el conocimiento lo mejor posible para tomar las decisiones arquitectónicas más adecuadas favoreciendo el aprendizaje.

Profesor/Irene Cid Rico

https://www.linkedin.com/in/irene-cid-81158148/

Que se emplee el conocimiento lo mejor posible para tomar las decisiones arquitectónicas más adecuadas favoreciendo el aprendizaje.

Universidad/Uniovi

http://uniovi.es/

Que se emplee el conocimiento lo mejor posible para tomar las decisiones arquitectónicas más adecuadas favoreciendo el aprendizaje.

Cliente/RTVE

https://www.rtve.es/

Que las decisiones arquitectónicas sean las más adecuadas para que la aplicación funcione de la manera que esperan.

Empresa/ChattySw

http://ChattySw.es/

Que las decisiones arquitectónicas sean las más adecuadas para que la aplicación funcione de la manera que esperan los clientes.

Empresa/Empathy

https://empathy.ai/

Interesada en que durante el desarrollo se utilice su tecnología de procesamiento de lenguaje natural de la manera más eficiente y adecada para que tengamos un buen aprendizaje y para realizar pruebas que aporten la mayor parte .

Alumno/Jorge Puente García

https://github.com/JorgeePG

Que las decisiones arquitectónicas sean las más adecuadas y que tengan una aplicabilidad dentro de las posibilidades de los desarrolladores.

Alumno/Claudia Rodriguez Fuertes

https://github.com/claudiaRFS

Que las decisiones arquitectónicas sean las más adecuadas y que tengan una aplicabilidad dentro de las posibilidades de los desarrolladores.

Alumno/German García de la Llana

https://github.com/germandelallana

Que las decisiones arquitectónicas sean las más adecuadas y que tengan una aplicabilidad dentro de las posibilidades de los desarrolladores.

Alumno/Iván García García

https://github.com/Ivigaga

Que las decisiones arquitectónicas sean las más adecuadas y que tengan una aplicabilidad dentro de las posibilidades de los desarrolladores.

2. Restricciones arquitectonicas

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.

2.1. Restricciones de documentación

Restricción Descripción

Arc42

El proyecto debe seguir la estructura de documentación de Arc42.

2.2. Restricciones técnicas

Restricción Descripción

Acceso a datos

La información de los usuarios deberá ser accesible a través de una API para garantizar la seguridad de los datos.

APIs externas

La aplicación hará uso de la API de Wikidata para obtener los datos necesarios y generar imágenes y preguntas de los lugares. Además, se integrará con la API del LLM externo Empathy AI para generar pistas sobre las imagenes de forma conversacional.

Despliegue

La aplicación debe estar desplegada y accesible en la web.

Pruebas

La aplicación debera de pasar una serie de pruebas para asegurar su correcto funcionamiento.

2.3. Organizativas

Restricción Descripción

Evaluación

El proyecto será evaluado cada tres semanas, por lo que cada módulo avanzará a través de varias versiones, las cuales estarán alineadas con las evaluaciones parciales.

Git y GitHub

El uso de Git como sistema de control de versiones es obligatorio. El proyecto se alojará en un repositorio público en la plataforma GitHub, y todo el trabajo realizado, así como las decisiones tomadas deben reflejarse en dicho repositorio.

Equipo

El equipo estará formado por 4 personas.

Reuniones

Se realizará obligatoriamente una reunión semanal.

3. Alcance y contexto del sistema

Contents

Context and scope - 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.

WIChat es una aplicación web de preguntas y respuestas basada en imágenes, desarrollada por ChattySw para RTVE. La aplicación permite a los usuarios registrarse, jugar y obtener premios por responder correctamente a preguntas sobre imágenes generadas automáticamente. Además, tendrá integrado un modelo de lenguaje (LLM) que proporcionará pistas para ayudar a los concursantes a responder correctamente.

Diagram 3.1: Contexto de negocio

Usuario: Identidad que iteractúa con el sistema.

WiChat: Maneja las entradas del usuario y se conecta a las APIs externas.

Wikidata: Proporciona datos precisos y actualizados que se utilizan para generar las preguntas y respuestas de la aplicación.

LLM: Modelo de inteligencia artificial que procesa las consultas de los usuarios, generando respuestas coherentes y relevantes basadas en el contexto y los datos obtenidos de Wikidata y la base de datos.

Base de datos: Almacena los datos de los usuarios, estadísticas de juegos y registros de consultas.

3.2. Technical Context

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.

Diagram 3.2: Contexto Tencológico

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.

4.1. Decisiones tecnológicas

Para el desarrollo de la aplicación se decidió utilizar las siguientes tecnologías:

  • JavaScript será el lenguaje de programación principal.

    • Se ha tomado esta decisión debido a la facilidad de integración con las tecnologías seleccionadas para el desarrollo de la aplicación.

  • React.js para construir interfaces de usuario.

    • Se ha seleccionado React.js por su facilidad de uso y su capacidad para crear interfaces de usuario interactivas y usables.

  • Node.js para construir el back-end.

    • Se ha seleccionado Node.js por su capacidad para manejar múltiples conexiones simultáneas y su facilidad de integración con otras tecnologías.

  • GitHub para el control de versiones.

    • Se ha seleccionado GitHub por su facilidad de uso y su capacidad para gestionar proyectos de software de forma colaborativa.

  • Docker para la contenerización de la aplicación.

    • Se ha seleccionado Docker por su capacidad para crear contenedores ligeros y portátiles que pueden ejecutarse en cualquier entorno.

  • Azure para el despliegue de la aplicación.

    • Se ha seleccionado Azure por su capacidad para escalar la aplicación de forma automática y su facilidad de integración con otras tecnologías.

  • Wikidata API.

    • Se ha seleccionado Wikidata API para obtener información sobre las imágenes de forma programática.

  • Empathy API.

    • Modelo largo de lenguaje (LLM) para ofrecer la posibilidad de obtener pistas de las imagenes de forma conversacional.

Se han considerado otras tecnologías para el desarrollo back-end como Spting Boot, pero finalmente se decidió utilizar JavaScript por su enfoque en el desarrollo ágil junto con la facilidad de integración con Node.js y React.js.

4.2. Descomposición de alto nivel

4.3. Decisiones para alcanzar objetivos de máxima calidad

Objetivo de calidad

Decisión

Seguridad

Se ha decidido seguir las mejores prácticas de seguridad en el desarrollo de la aplicación, como la validación de datos de entrada y la protección contra ataques de inyección de código.

Usabilidad

Se realizaran pruebas de usabilidad con usuarios reales. Serán al menos 4 tandas de 3 usuarios cada una, teniendo en cuenta qe se aborden diferentes intervalos de edad y de con diferente manejo de la informática.

Fiabilidad

Se ha tomado la decisión de realizar pruebas de regresión y pruebas de integración para garantizar la fiabilidad de la aplicación.

Rendimiento

Se realizarán pruebas de carga para garantizar el rendimiento de la aplicación para poder tener al menos 100 usuarios a la vez.

Mantenibilidad

Se utilizarán patrones de diseño y buenas prácticas de programación para garantizar la mantenibilidad de la aplicación.

Eficiencia

Se optimizará el uso de recursos para garantizar que la aplicación funcione de manera eficiente donde se despliegue, además de usar los recursos externos también de manera eficiente.

Portabilidad

La aplicación se desarrollará utilizando tecnologías y frameworks multiplataforma, asegurando que pueda desplegarse en diferentes entornos (Windows, Linux, macOS) sin generar problemas.

4.4. Decisiones de organización relevantes

El flujo de trabajo se organizará en reuniones semanales, que se llevarán a cabo según sea necesario. Una de las reuniones se realizará durante la clase de laboratorio y se centrará en decisiones y tareas menores. Las reuniones posteriores se relaizarán de manera remota y estarán dedicadas a deciones mas detalladas y exhaustivas.

Cada tarea asignada, así como problemas encontrados, se documentará como un Issue en GitHub. Además se utilizará GitHub Projects para la organización de las tareas del equipo. No habrá una división estricta entre front-end y back-end, todos los miembros del equipo trabajarán en ambas áreas. Para cada tarea asiganada, se creará una rama específica, y el trabajo realizado se volcará una rama develop mediante pull requests. Una vez que se haya completado una funcionalidad, se fusionará la rama develop con la rama master.

5. Vista de bloques de construcción

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

Diagram 5.1: Resumen del Sistema

Motivation

El propósito principal del sistema es ejecutar un juego de preguntas con imágenes utilizando información obtenida dinámicamente de la Wikidata API y además teniendo la posibilidad de interactuar con un LLM para solicitar su ayuda. Esto permite a los usuarios interactuar con datos reales y actualizados, mejorando la experiencia de usuario y la utilidad de la aplicación.

Bloques de construcción contenidos
Building Blocks Description

WICHAT

Parte principal de la aplicación, que controla el juego y la conexión con el resto de bloques.

BD

Base de datos encargada de almacenar los datos relacionados con los usuarios.

Wikidata

Fuente de datos a la que se conecta la aplicacion para obtener las imágenes de las preguntas.

LLM

Modelo de lenguaje con el que el usuario puede interactuar para obtener pistas sobre las preguntas del juego.
Interfaces importantes

  • Frontend ↔ API Gateway: Interfaz RESTful para la comunicación entre el frontend y el backend.

  • API Gateway ↔ Backend: Interfaz interna para enrutar solicitudes a los microservicios.

  • Backend ↔ Base de Datos: Interfaz para acceder y gestionar los datos almacenados.

Insert your explanations of black boxes from level 1:

If you use tabular form you will only describe your black boxes with name and responsibility according to the following schema:

Name Responsibility

<black box 1>

 <Text>

<black box 2>

 <Text>

If you use a list of black box descriptions then you fill in a separate black box template for every important building block . Its headline is the name of the black box.

==== <Name black box 1>

Here you describe <black box 1> according the the following black box template:

  • Purpose/Responsibility

  • Interface(s), when they are not extracted as separate paragraphs. This interfaces may include qualities and performance characteristics.

  • (Optional) Quality-/Performance characteristics of the black box, e.g.availability, run time behavior, …​.

  • (Optional) directory/file location

  • (Optional) Fulfilled requirements (if you need traceability to requirements).

  • (Optional) Open issues/problems/risks

<Purpose/Responsibility>

<Interface(s)>

<(Optional) Quality/Performance Characteristics>

<(Optional) Directory/File Location>

<(Optional) Fulfilled Requirements>

<(optional) Open Issues/Problems/Risks>

==== <Name black box 2>

<black box template>

==== <Name black box n>

<black box template>

==== <Name interface 1>

…​

==== <Name interface m>

5.2. Nivel 2

Here you can specify the inner structure of (some) building blocks from level 1 as white boxes.

You have to decide which building blocks of your system are important enough to justify such a detailed description. Please prefer relevance over completeness. Specify important, surprising, risky, complex or volatile building blocks. Leave out normal, simple, boring or standardized parts of your system

Diagram 5.2: Desglose Wichat

Contained Building Blocks
Building Blocks Description

WICHAT App

Parte central del proyecto, encargada de comunicar al usuario con el resto de servicios de la aplicación.

Question Generator Service

Parte de la aplicación encargada de conectarse a Wikidata y obtener imagenes e información para las preguntas del juego.

User Service

Parte encargada de tratar la información del usuario: puntuación, historial…​. Se conecta al base de datos para almacenar esta información.

Authentication Service

Parte encargada de administrar la autentificación de usuarios. Se conecta a la base de datos para almacenar y comprobar los nombres y contraseñas.

LLM Service

Parte encargada de la comunicación con el modelo de lenguaje. Envía la información necesaria para obtener las pistas del jugador y devolverlas.

5.3. Level 3

Here you can specify the inner structure of (some) building blocks from level 2 as white boxes.

When you need more detailed levels of your architecture please copy this part of arc42 for additional levels.

5.3.1. White Box <_building block x.1_>

Specifies the internal structure of building block x.1.

<white box template>

5.3.2. White Box <_building block x.2_>

<white box template>

5.3.3. White Box <_building block y.1_>

<white box template>

6. Vista 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. Registro

Diagrama 6.1: Registro

Inicio de sesión

----

Diagrama 6.2: Login

6.2. Jugar

Diagrama 6.3: Jugar

6.3. Consultar historial

Diagrama 6.4 Ver historial

6.4. Interactuar con el chat

Diagrama 6.5: Jugar

7. Vista de Despliegue

Contenido

La vista de despliegue describe:

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

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

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

Especialmente, documenta una vista de despliegue si tu software se ejecuta como un sistema distribuido con más de una computadora, procesador, servidor o contenedor, o cuando diseñas y construyes tus propios procesadores y chips de hardware.

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

Motivación

El software no se ejecuta sin hardware. Esta infraestructura subyacente puede influir en el sistema y/o en algunos conceptos transversales. Por lo tanto, es necesario conocer la infraestructura.

Formato

Es posible que un diagrama de despliegue de nivel más alto ya esté incluido en la sección 3.2 como contexto técnico, mostrando tu propia infraestructura como UNA caja negra. En esta sección, puedes hacer zoom en esa caja negra utilizando diagramas de despliegue adicionales:

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

  • Si los interesados en el hardware prefieren otros tipos de diagramas en lugar de un diagrama de despliegue, permite que utilicen cualquier formato que pueda mostrar nodos y canales de la infraestructura.

Información Adicional

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

7.1. Nivel de Infraestructura 1

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

  • Distribución de un sistema en múltiples ubicaciones, entornos, computadoras, procesadores, etc., así como las conexiones físicas entre ellos.

  • Justificaciones o motivaciones importantes para esta estructura de despliegue.

  • Características de calidad y/o rendimiento de esta infraestructura.

  • Asignación de artefactos de software a elementos de esta infraestructura.

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

Diagram 7.1: Infraestructura

Motivación

El sistema se desplegará en una infraestructura distribuida (Azure) para garantizar escalabilidad, alta disponibilidad y rendimiento. Esto permite que los componentes del sistema se ejecuten en diferentes entornos (desarrollo, pruebas y producción) y se adapten a las necesidades de los usuarios finales.

Características de Calidad y/o Rendimiento

  • Seguridad y Privacidad: La infraestructura se desplegará en la nube de Azure, que cuenta con certificaciones de seguridad y privacidad. Además, se utilizarán mecanismos de seguridad cifrado y autenticación para proteger los datos y la información del sistema.

  • Escalabilidad: La infraestructura está diseñada para escalar horizontalmente, lo que permite añadir más recursos o contenedores según la demanda.

  • Alta Disponibilidad: Se utilizará un sistema de virtualización en la nube para favorecer la disponibilidad.

  • Portabilidad: La infraestructura se basa en contenedores Docker, lo que permite que los componentes del sistema se ejecuten en cualquier entorno.

Asignación de Bloques de Construcción a la Infraestructura

  • Frontend: Desplegado en un servidor web (Apache) al que puedan acceder los usuarios.

  • Backend: Los microservicios (AuthService, UserService, LLM) se ejecutarán en contenedores Docker.

  • Base de Datos: Se utilizará una base de datos mongoDB para toda la gestión de los datos de la aplicación.

  • API Gateway: actúa como punto de entrada único para todas las solicitudes del usuario. Está desplegado en Azure utilizando el servicio Azure API Management, que permite gestionar, monitorizar y proteger las APIs del sistema.

7.2. Nivel de Infraestructura 2

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

Copia la estructura del nivel 1 para cada elemento seleccionado.

7.2.1. <Docker (Contenedores)>

Diagram 7.2: Docker

Explicación:

Docker es la tecnología utilizada para empaquetar los microservicios en contenedores. Cada contenedor incluye:

  • Imágenes Docker: Contienen el código, las dependencias y la configuración necesaria para ejecutar cada microservicio.

  • Volúmenes: Para persistir datos (por ejemplo, logs o archivos temporales).

  • Redes Docker: Para facilitar la comunicación entre contenedores.

<diagrama + explicación>

==== <Elemento de Infraestructura 2>

<diagrama + explicación>

…​

==== <Elemento de Infraestructura n>

<diagrama + explicación>

8. Conceptos tranversales

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. Modelo del dominio

Diagram 8.1: Modelo del dominio

8.2. Conceptos de experiencia de usuario (UX)

Aunque el desarrollo aún no ha comenzado, se tiene como objetivo crear una aplicación intuitiva, accesible y atractiva, que permita a los usuarios disfrutar de la experiencia de juego de manera fluida.

  • Diseño Responsivo: La aplicación se adaptará a diferentes dispositivos y tamaños de pantalla.

  • Accesibilidad: Cumplimiento de estándares WCAG para garantizar que la aplicación sea usable por personas con discapacidades.

  • Feedback Visual: Proporcionar retroalimentación visual inmediata para las acciones del usuario.

  • Prototipos: "url prototipos"

8.3. Conceptos de seguridad y protección

Aún sin desarrollar. Sin embargo, se contemplan las siguientes consideraciones iniciales:

  • Autenticación y Autorización: Se buscará realizrar una correcta autenticación de usuarios.

  • Protección de Datos: Garantizar la privacidad de los usuarios.

  • Cifrado: Uso de HTTPS para la transmisión de datos y cifrado de datos sensibles.

8.4. Patrones de arquitectura y diseño

Serán utilizados dos patrones:

API Gateway: Este actúa como punto de entrada único para todas las solicitudes que realice el usuario delegandolas en sus servicios correspondientes.

Patrón de Micoservicios: Cada componente, como AuthService, UserService y LLM, es un servicio independiente que se enfoca en una funcionalidad específica, facilitando el mantenimiento del sistema.

Consultar los patrones utilizado en " "

8.5. Conceptos técnicos

Aún sin desarrollar. Sin embargo, se contemplan las siguientes tecnologías y herramientas:

  • Lenguajes de Programación: JavaScript para el frontend.

  • Frameworks: React para el frontend.

  • Bases de Datos: MongoDB para la gestión de datos.

  • Despliegue: Uso de Docker para la contenerización y orquestación de servicios.

8.6. Conceptos de desarrollo

Hemos decidido empezar nuestro proyecto de cero pero basándonos en proyectos del año anterior. Esto nos permitirá tener una base más sólida para implementar la nueva funcionalidad de pistas generadas por la AI y poder incluso realizar una desarrollo mas eficiente.

  • Metodología Ágil: Uso de Scrum para la gestión del proyecto.

  • Control de Versiones: Uso de Git y GitHub para el control de versiones y colaboración.

  • Integración Continua: Con total intención de automatizar pruebas y despliegues.

8.7. Conceptos operativos

  • Monitorización: Es importante asegurarse de que el sistema funcione correctamente en todo momento. Para ello, se utilizarán herramientas que permitan supervisar el rendimiento del sistema, detectar errores y medir el uso de recursos. Esto nos ayudará a identificar problemas antes de que afecten a los usuarios.

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.

Para documentar las decisiones arquitectónicas se han usado las páginas de la wiki de GitHub. A continuación se muestra una lista con las decisiones tomadas y un enlace a su documentación.

9.1. Decisiones

10. Requisitos de calidad

Content

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

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

Motivation

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

Further Information

See Quality Requirements in the arc42 documentation.

10.1. Árbol de calidad

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 10.1: Árbol de calidad

10.2. Escenarios de calidad

Escenarios de uso:

Objetivo de calidad Escenario Sistema

Usabilidad

Un usuario inicia la aplicación por primera vez

La interfaz guía al usuario con un diseño intuitivo y sencillo, permitiéndole registrarse facilmente y comenzar a utilizar la aplicación sin dificultades.

Seguridad

Un usuario introduce sus credenciales e inicia sesión en la aplicación

Valida las credenciales y si son correctas, genera un token de autenticación seguro, permitiendole el acceso a la aplicación

Fiabilidad

Un usuario completa el formulario de registro

Si algún campo está incompleto o incorrecto muestra un mensaje claro indicando el error y no permite proceder hasta que el usuario corrija el error.

Rendimiento

Varios usuarios juegan simultaneamente en la aplicación

Mantiene los tiempos de respuesta rápidos sin que los usuarios sufran interrupciones o esperas

Manteniabilidad

Un miembro del equipo realiza cambios en el codigo para agregar una nueva funcionalidad

El código está estructurado por módulos de tal forma que pemite agregar nuevas funcionalidades facilmente sin afectar en otras áreas de la aplicación

Portabilidad

Un usuario inicia la aplicación en un dispositivo móvil

La aplicación se ejecuta correctamente en el dispositivo

Eficiencia

Un usuario carga una página con múltiple contenido multimedia como imágenes

La página se carga rápidamente sin comprometer la experencia del usuario
Contents

Concretization of (sometimes vague or implicit) quality requirements using (quality) scenarios.

These scenarios describe what should happen when a stimulus arrives at the system.

For architects, two kinds of scenarios are important:

  • Usage scenarios (also called application scenarios or use case scenarios) describe the system’s runtime reaction to a certain stimulus. This also includes scenarios that describe the system’s efficiency or performance. Example: The system reacts to a user’s request within one second.

  • Change scenarios describe a modification of the system or of its immediate environment. Example: Additional functionality is implemented or requirements for a quality attribute change.

Motivation

Scenarios make quality requirements concrete and allow to more easily measure or decide whether they are fulfilled.

Especially when you want to assess your architecture using methods like ATAM you need to describe your quality goals (from section 1.2) more precisely down to a level of scenarios that can be discussed and evaluated.

Form

Tabular or free form text.

11. Risks and Technical Debts

Contents

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

Motivation

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

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

Form

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

Further Information

See Risks and Technical Debt in the arc42 documentation.

11.1. Riesgos

Riesgo Descripcion

Bajo conocimiento de algunas herramientas y lenguajes

Algunos miembros del grupo nunca han trabajado o no tienen mucha experiencia con algunas de las herramientas o lenguajes utilizados para el desarrollo de la aplicación. Esto puede llevar a errores o retrasos debido a su falta de conocimiento.

Nunca se ha trabajado con un LLM

Esta es la primera vez que el equipo trabaja con un modelo de lenguaje o con ese en particular. Esto puede llevar a un retraso debido a la necesidad de obtener información sobre el funcioanmiento de este.

Tiempos de respuesta de Wikidata y el LLM

Al ser parte integral de la aplicación la conexión con Wikidata y el modelo de lenguaje si hay algún problema en la conexión que haga que sus tiempos de respuesta sean demasiado largos esto puede repercutir en nuestra aplicación.

Trabajo en equipo

Los miembros del equipo no se conocen ni han trabajado en conjunto anteriormente, se desconoce las formas de trabajo y nivel de compromiso de cada uno. Hay que tener en cuenta la posibilidad de abandono de uno de los integrantes.

11.2. Deuda Técnica

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

ADR

Architectural Decision Record. Documento que describe una decisión arquitectónica tomada, incluyendo el contexto, las opciones consideradas y la justificación de la elección.

API

Application Programming Interface. Conjunto de reglas y definiciones que permiten la comunicación entre diferentes sistemas o aplicaciones.

LLM

Large Language Model. Modelo de inteligencia artificial que ha sido entrenado con enormes cantidades de texto para poder entender, generar y responder en lenguaje natural.