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 Metas

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

WIChat es una aplicación basada en el popular concurso "Saber y Ganar" y una versión actualizada de la aplicación WIQ creada por HappySw. El objetivo de este proyecto es añadir funcionalidad y modernizar la aplicación WIQ para mejor la experiencia de usuario cumpliendo con varios objetivos:

  • El aprendizaje por parte de los usuarios de los temas incluidos en las preguntas.

  • Mejorar la interfaz de la aplicación y adaptarla a las nuevas funciones introducidas.

  • Promover la interacción del usuario con la IA para asistirle.

  • Replicar al máximo posible el formato de un concurso de preguntas en WIChat.

1.1. Vista general de los requisitos

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.

La función principal de WIChat es presentar a los usuarios una serie de preguntas que tienen que tratar de responder correctamente, similar al concurso de preguntas "Saber y Ganar".

Las preguntas tendrán un enunciado adjuntado a una imagen y una serie de respuestas posibles. A más preguntas respondidas correctamente, más puntuación.

Los usuarios pueden interactuar con un LLM que le brinde pistas y ayude al usuario.

Requisitos de alto nivel:

  1. El sistema permitirá a los usuarios no registrados registrarse en la aplicación.

    1. El registro pedirá obligatoriamente a los usuarios:

      1. Un nombre de usuario.

      2. Una constraseña.

    2. Si el registro es exitoso, se guardará la información del usuario es base de datos.

    3. Si el registro NO es exitoso, notificará el fallo al usuario.

  2. El sistema permitirá a los usuarios registrados autentificarse en la aplicación.

    1. La autenticación pedirá obligatoriamente a los usuarios:

      1. Un nombre de usuario.

      2. Una contraseña.

    2. Si la autenticación es exitosa, se rederegirá al usuario registrado a la pantalla principal.

    3. Si la autenticación NO es exitosa, notificará el fallo al usuario.

  3. Los usuarios registrados podrán jugar concursos en los que responderán preguntas.

    1. Los concursos tienen un total de 20 preguntas.

    2. Los concursos tiene un límite de tiempo indicado por un temporizador.

      1. Si el usuario se queda sin tiempo, el concurso acaba inmediatamente.

    3. Las preguntas y respuestas se deben generar automáticamente con información conseguida de WikiData.

      1. Las preguntas deben incluir una imagen, un enunciado y varias respuestas incorrectas.

      2. Los datos de la pregunta deben ser guardados en base de datos.

    4. Los usuarios registrados pueden interactuar con un LLM para conseguir pistas sobre la pregunta actual.

    5. Al acabar el concurso, se le mostrará al usuario información sobre el concurso.

      1. Se mostrará cuantas preguntas han sido acertadas.

      2. Se mostrará cuantas pistas se han usado.

      3. Se mostrará cuanto tiempo se ha tardado en acabar el concurso.

  4. Los usuarios registrados podrán consultar un histórico de su participación en el sistema con la siguiente información:

    1. Número de concursos jugados.

    2. Preguntas acertadas y falladas en cada concurso.

    3. Tiempo de juego de cada concurso.

  5. El sistema ofrecerá una API que permita obtener información sobre:

    1. Los usuarios registrados en la aplicación. Se puede obtener la siguiente información:

      1. Su nombre de usuario.

      2. Los concursos que han jugado.

      3. Las preguntas acertadas y falladas en los concursos jugados.

      4. Los tiempos de juego en los concursos jugados.

    2. Las preguntas generadas por la aplicación. Se puede obtener la siguiente información:

      1. Enunciado de la pregunta.

      2. Respuestas generadas, indicando cual es la correcta.

      3. Imagen utilizada en la pregunta.

La aplicación, debido a su enfoque para todos los públicos, debe tener un especial enfoque en la usabilidad. Debe ser fácil de usar y tener una curva de aprendizaje poco inclinada.

1.2. Metas de calidad

Contents

The top three (max five) quality goals for the architecture whose fulfillment is of highest importance to the major stakeholders. We really mean quality goals for the architecture. Don’t confuse them with project goals. They are not necessarily identical.

Consider this overview of potential topics (based upon the ISO 25010 standard):

Categories of Quality Requirements
Motivation

You should know the quality goals of your most important stakeholders, since they will influence fundamental architectural decisions. Make sure to be very concrete about these qualities, avoid buzzwords. If you as an architect do not know how the quality of your work will be judged…​

Form

A table with quality goals and concrete scenarios, ordered by priorities

Atributo de calidad Motivación

Usabilidad

La aplicación, debido a su enfoque para todos los públicos, debe tener un especial enfoque en la usabilidad. Debe ser fácil de usar y tener una curva de aprendizaje poco inclinada.

Disponibilidad

La aplicación debe estar disponible una gran mayoría del tiempo.

Rendimiento

El tiempo de respuesta de la aplicación debe ser corto para ofrecer una experiencia de juego fluida y disfrutable

Interoperabilidad

WIChat tendrá una API con la que se puede obtener información relevante a los usuarios y las preguntas generadas. El sistema obtendrá información de WikiData y se comunicará con un LLM.

Modificabilidad

El sistema debe ser fácil de cambiar y de añadir nuevas funcionalidades para facilitar futuras actualizaciones.

Sabiendo los atributos de calidad más relevantes, podemos definir unos requisitos no funcionales adecuados.

Requisitos no funcionales:

  1. El tiempo de aprendizaje de un nuevo usuario debe ser menor a 1 hora.

  2. El sistema será compatible con Windows, iOS y Linux.

  3. La aplicación deberá funcionar en navegadores web estándar, asegurando la compatibilidad con versiones recientes de Chrome, Firefox, Safari y Edge.

  4. El sistema debe ser capaz de operar adecuadamente con hasta 1000 usuarios con sesiones concurrentes.

  5. El tiempo para iniciar o reiniciar el sistema no podrá ser mayor a 1 minuto.

  6. El sistema debe emplear Wikidata para construir las preguntas.

  7. El sistema debe emplear un LLM para formular pistas para el usuario.

  8. El tiempo en generar las preguntas de un concurso no debe ser mayor a 20 segundos.

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.

Nombre Metas

Equipo de desarrollo

Desarrolladores que quieren crear una aplicación robusta. Se usan varias tecnologías nuevas que incitan al aprendizaje por parte del equipo.

ChattySw

Empresa responsable de WIChat. Quieren un producto satisfactorio que sea a gusto del cliente y que el desarrollo de la misma sea lo más ágil y lo menos costoso posible.

RTVE

El cliente que pidió el producto. Quiere el mejor producto posible y se beneficia directamente de el.

Usuarios

Los usuarios de la aplicación. Buscan la mejor experiencia de usuario posible y el aprendizaje derivado de las preguntas respondidas.

HappySw

Responsables de la version experimental anterior de WIChat. Competidora de ChattySw.

2. Restricciones de la arquitectura

Contents

Any requirement that constraints software architects in their freedom of design and implementation decisions or decision about the development process. These constraints sometimes go beyond individual systems and are valid for whole organizations and companies.

Motivation

Architects should know exactly where they are free in their design decisions and where they must adhere to constraints. Constraints must always be dealt with; they may be negotiable, though.

Form

Simple tables of constraints with explanations. If needed you can subdivide them into technical constraints, organizational and political constraints and conventions (e.g. programming or versioning guidelines, documentation or naming conventions)

Further Information

See Architecture Constraints in the arc42 documentation.

2.1. Motivación

Es fundamental que los arquitectos de software sean capaces de distinguir dónde tienen libertad de decisión y dónde deben cumplir con ciertas restricciones.

Por ello, en este punto de la documentación se recoge cualquier requisito que limiten la libertad de los arquitectos de software en sus decisiones de diseño, implementación o en el proceso de desarrollo.

Restricciones de negocio

  • Plazos de entrega: El sistema debe estar operativo en un tiempo limitado para cumplir con el contrato con RTVE.

  • Presupuesto: Se debe trabajar dentro de un presupuesto fijo acordado con RTVE.

Restricciones técnicas

  • Estructura: El sistema deberá de contar con un frontend web accesible (mostrará las imágenes y respuestas, además del sistema de pistas que permitirá a los usuarios obtener pistas sobre las imágenes) y una API documentada (permitirá acceder a la información de las preguntas generadas).

  • Infraestructura: La aplicación debe estar desplegada y accesible a través de la web.

  • Generación de contenido: Las preguntas, respuestas y pistas deben generarse automáticamente a partir de datos de Wikidata. Dichas preguntas deberán tener una respuesta correcta y varias distractoras, todas ellas generadas automáticamente por Wikidata.

  • Integración con un LLM: Se utilizará un modelo de lenguaje externo para generar pistas conversacionales (se debe mitigar la generación de respuestas incorrectas o alucinaciones).

Restricciones de dependencias

  • Disponibilidad de APIs externas: Dependencia de Wikidata y del LLM, que pueden tener tiempos de respuesta o restricciones de uso.

3. Contexto y alcance

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.

En este capítulo se describe el ámbito de WIChat. Se ven los sistemas de los que depende la aplicación y los usuarios que la usan.

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.

Contexto de negocio WIChat
Usuario

Cualquier usuario que se disponga a usar la aplicación. Los usuarios deben de registrarse antes de acceder al juego. En el juego los usuarios responderán preguntas y aprenderán de ellas. También pueden consultar sus datos históricos en la aplicación.

MongoDB

Todos los datos relevantes a la aplicación se guardarán en una base de datos MongoDB.

Gemini

Los usuarios pueden interactuar con el LLM "Gemini" a través de WIChat para pedir pistas y asistencia para responder preguntas.

WikiData

La información necesaria para que la aplicación genere las preguntas automáticamente es obtenida de la API de WikiData. De esta se sacan los enunciados de las preguntas, las respuestas correctas e incorrectas y las imágenes que se adjuntan a las preguntas.

3.2. Contexto técnico

Contents

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

Motivation

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

Form

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

Contexto técnico WIChat

La arquitectura de WIChat es una estructura basada en microservicios:

Users

El paquete users se divide en dos paquetes, "Auth service" que se encarga de la autenficación de los usuarios ya registrados y "Users service", que se encarga del registro de nuevos usuarios. Ambos se comunican con la base de datos para guardar o obetener información.

Question service

Es el servicio encargado de comunicarse con la API de WikiData para generar las preguntas y respuestas mostradas a los usuarios. Las preguntas generadas son guardadas en base de datos para el historial de los usuarios.

Gateway service

El gateway se encarga de recibir las peticiones y redirigirlas al servicio correspondiente.

WIChat API

Ofrece datos sobre los usuarios de la aplicación y las preguntas generadas.

4. Estrategia de solución

4.1. Decisiones tecnológicas

Las siguientes tecnologías han sido usadas a lo largo del desarrollo de nuestra aplicación:

  • TypeScript: Hemos elegido usar TypeScript como el lenguaje de la aplicación debido a su gran similitud con JavaScript y su agregado de tipado estático y sus características como detección de errores en tiempo de compilación. Además de que soporta interfaces y tipos personalizados y el editor VSCode proporciona autocompletado inteligente gracias a los tipos. También si en algún punto del desarrollo quisieramos convertir el código a JavaScript nos sería mucho más cómodo.

  • MongoDB: Hemos elegido usar MongoDB para la base de datos de la aplicación debido a que tiene un modelo de datos flexible ya que no requiere esquema fijo, es fácil de modificar y además usa BSON (Binary JSON), lo que permite que no se requiera un alto conocimiento por ejemplo en SQL y se almacenen los datos de manera eficiente.

  • Gemini: Usamos Gemini como LLM de la aplicación ya que disponemos de una ApiKey de este, lo que nos permite poder procesar texto, imágenes, audios o vídeos con él. También puede analizar imágenes y responder preguntas sobre ellas en tiempo real, lo cual es bastante conveniente para el tipo de aplicación que deseamos hacer.

  • Wikidata: Nos sirve para usar los distintos datos que nos proporciona de manera totalmente gratuita. Cuenta con una traducción automática de datos y soporta más de 400 idiomas. Ofrece una API pública para consultar datos desde aplicaciones web o móviles y es compatible con tecnologías como TypeScript y JavaScript.

  • GitHub: Para subir el proyecto y sus respectivos cambios y poder tener un lugar de trabajo conjunto nos hemos decantado por GitHub porque nos permite un historial completo de los cambios que va a realizar cada miembro a lo largo del tiempo, así como la facilidad de trabajar en paralelo mediante el uso de ramas y que los distintos commits del proyecto se guardarán en la nube por si hubiera algún problema en el desarrollo. También cabe destacar el uso de issues y el de pull requests que nos sirven para revisar distitos cambios antes de fusionarlos con la rama principal del proyecto.

  • React: Hemos elegido React para construir nuestras interfaces de usuario debido a que aunque sea una biblioteca de JavaScript es perfectamente utilizable en conjunto a TypeScript. React divide la interfaz de usuario en pqueños componentes reutilizables que facilitan el mantenimiento y escalabilidad del código. Además que al haber trabajado ya con JavaScript y HTML React es fácil de aprender y de usar.

  • Docker: Tecnología usada para desplegar el proyecto y todos sus distintos módulos en la web. Usamos docker ya que es el que se nos ha enseñado a utilizar en el laboratorio y además es un sistema portable que lo único que necesitamos es tener docker instalado para que funcione. Además de la eficiencia que nos permite empaquetar los contenedores en un período de tiempo razonable.

  • Node.js: Es una plataforma que nos permite ejecutar JavaScript en el servidor. Usamos Node.js debido a que viene incluido con NPM, es decir, con un gestor de paquetes que facilita la instalación y gestión de bibliotecas y módulos para nuestra aplicación ya que cuenta con una gran cantidad de módulos para cualquier cosa. También lo usamos debido a que nos permite crear servidores web rápidos que pueden manejar un gran número de conexiones simultáneas.

  • Express: Es un framework de JavaScript que se utiliza para desarrollar aplicaciones web y Apis en Node.js. Lo usamos debido a que es uno de los frameworks más populares para construir aplicaciones del lado del servidor debido a su simplicidad, flexibilidad y alto rendimiento.

4.2. Herramientas de apoyo

  • Visual Studio Code: Es el IDE que hemos usado los miembros del equipo por defecto ya que es un entorno con el que estamos familiarizados y que además contiene todos los mecanismos que necesitamos para trabajar con el proyecto y entre nosotros en el repositorio remoto.

  • Draw.io: A la hora de crear diagramas como los de bloques nos hemos decantado por esta herramienta online, debido a su facilidad de uso y varios tipos de plantillas para crear diagramas así como que es totalmente gratuita.

  • PlantUML: También para los diagramas hemos usado esta herramienta. Es totalmente gratuita y funciona escribiendo el diagrama UML en formato de texto y generándolo después en formato gráfico.

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.

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. Visión general

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.

BuildingBlock
Motivación

Esta es la visión general en la cual el usuario usa WIQ, que es la estructura general del proyecto y a su vez interactua con Wikidata para obtener los datos para poder desarrollar la aplicación

5.1.1. Componentes

Nombre Responsabilidad

Usuario

Usuario que interactuará con la aplicación.

Wichat

Responsable de la gestión del juego.

WikiData

Permite generar preguntas y respuestas, proporcionando la información.

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.

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

5.2. Nivel 2

BuildingBlock2

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

5.2.1. Componentes

Nombre Responsabilidad

Usuario

Usuario que interactuará con la aplicación.

Webapp

Interfaz de la aplicación, que permite proporciona al usuario lo necesario para moverse por la aplicación: registrarse, iniciar sesión o jugar.

GatewayService

Sirve como punto de entrada para la aplicación, además de realizar las distintas llamadas a los diferentes servicios según el usuario lo requiera.

AuthService

Servicio de autenticación responsable de verificar los datos del usuario al iniciar sesión.

UserService

Servicio que se encarga de la gestión de los usuarios, añadir a la base de datos y validar los datos introducidos.

LlmService

Servicio responsable de realizar las llamadas a la api de llm y gestionar sus respuestas y comportamientos.

HistoryService

Servicio encargado de trabajar junto con la database para gestionar el historial de partidas del usuario.

WikiService

Servicio responsable de lanzar las querys a Wikidata para obtener la información.

UserData

Base de datos mongodb cuya función es guardar información sobre los usuarios.

QuestionData

Base de datos mongodb cuya función es almacenar las preguntas devuletas por wikidata.

GeminiApi

Api proporcionada para interactuar con el modelo de lenguaje de Google Gemini.

…​describes the internal structure of building block 1.

5.3. Nivel 3-Servicio de Usuario

BuildingBlockuserservice

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

Nombre Responsabilidad

AuthService

Solicitará a la base de datos un usuario para poder autentificarlo, verificará que el usuario suministrado por la base de datos nos proporcione la contraseña correcta para poder acceder al juego.

UserService

Se encargará de todo lo relacionado con añadir usuarios a la base de datos. Se encargará de verificar el formato de los datos proporcioandos por el usuario para crearse una nueva cuenta, así como que la contraseña coincida con la validación de esta misma.

UserDb

La base de datos que se encargará de almacenar a los usuarios de la aplicación con su respectiva información como nombre, correo y la contraseña encriptada para más seguridad.

Specifies the internal structure of building block x.1.

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

  • Para poder jugar un usuario debe estar registrado

  • Para registrarse se necesita un nombre de usuario y una contraseña

User registration diagram

6.2. Inicio de sesión

  • Un usuario ya registrado inicia sesión para poder jugar

  • El usuario debe introducr su nombre y contraseña correctos

Log in diagram

6.3. Generación de preguntas en una partida

  • Las preguntas necesarias para el juego son sacadas de WikiData

Play diagram

7. Diagrama de Despliegue

Content

Esta vista describe:

  1. La infraestructura técnica utilizada para ejecutar WIChat, con elementos como entornos, servidores, contenedores Docker, canales de comunicación y protocolos de red.

  2. La asignación de los bloques de software a esta infraestructura.

Dado que WIChat está compuesto por múltiples servicios y utiliza tecnologías externas, es crucial documentar su despliegue para garantizar su mantenimiento, escalabilidad y correcto funcionamiento.

Motivación

El software no puede ejecutarse sin infraestructura. Esta infraestructura subyacente afecta la arquitectura del sistema y conceptos transversales como seguridad y rendimiento. Es importante entender y documentar estos aspectos.

Forma

Se presenta un diagrama de despliegue que muestra los servicios dentro de contenedores Docker, las conexiones entre ellos y su interacción con bases de datos y servicios externos.

Further Information

Ver Deployment View en la documentación de arc42.

Diagrama de Despliegue

7.1. Motivación

En WIChat, los usuarios interactúan a través de una interfaz web basada en React. Esta aplicación se comunica con un backend desplegado en un servidor en Azure, donde cada componente funciona dentro de contenedores Docker. El Gateway Service actúa como el núcleo del sistema, distribuyendo las solicitudes entre los servicios internos (AuthService, UserService, QuestionService, HistoryService, WIChat_API,Wikidata API) y servicios externos (Gemini API y Wikidata). Los datos se almacenan en MongoDB, ejecutándose en un contenedor Docker en el mismo servidor. El sistema garantiza la seguridad mediante conexiones HTTPS y autenticación con API Keys, mientras que la arquitectura basada en contenedores facilita la escalabilidad y modularidad.

7.2. Características de Calidad y Rendimiento

  • Escalabilidad: Cada servicio está encapsulado en un contenedor Docker, lo que permite escalar horizontalmente según la demanda.

  • Seguridad: Todas las comunicaciones se realizan mediante HTTPS y las interacciones con servicios externos requieren API Keys.

  • Modularidad: La separación de servicios en microservicios facilita el mantenimiento y la extensibilidad del sistema.

7.3. Mapeo de Componentes a la Infraestructura

Servicio Descripción

WebApp

Aplicación frontend en React que permite la interacción del usuario con el sistema.

Gateway Service

Punto de entrada de la aplicación. Orquesta las solicitudes entre los servicios internos y externos.

Auth Service

Responsable de la autenticación de los usuarios.

User Service

Maneja la gestión de usuarios, incluyendo registros y perfiles.

Question Service

Obtiene preguntas desde Wikidata, las procesa y las almacena en la base de datos.

History Service

Gestiona y almacena el historial de participación de los usuarios.

WIChat API

Proporciona información sobre los usuarios de la aplicación y las preguntas que se generan.

Wikidata API

API para acceder a Wikidata.

MongoDB

Base de datos utilizada para almacenar: - Información de usuarios (perfiles, credenciales). - Preguntas y respuestas generadas. - Historial de participación y partidas.

Gemini API

API de modelo de lenguaje utilizada para generar pistas en tiempo real.

Wikidata

Fuente externa de información utilizada para la generación automática de preguntas.

8. Conceptos transversales

Content

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

  • models, especially domain models

  • architecture or design patterns

  • rules for using specific technology

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

  • implementation rules

Motivation

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

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

Form

The form can be varied:

  • concept papers with any kind of structure

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

  • sample implementations, especially for technical concepts

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

Structure

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

  • Domain concepts

  • User Experience concepts (UX)

  • Safety and security concepts

  • Architecture and design patterns

  • "Under-the-hood"

  • development concepts

  • operational concepts

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

Possible topics for crosscutting concepts
Further Information

See Concepts in the arc42 documentation.

8.1. Modelo de Dominio

DiagramaDeClases
Nombre Descripción

Usuario

El usuario de la aplicación podrá acceder a un historial donde se guarden los datos de sus partidas anteriores, así como poder jugar la cantidad de juegos que el usuario vea necesario.

Historial

Contendrá tanto las preguntas falladas y acertadas de su usuario, como el número de juegos que ha jugado y los distintos tiempos que ha tardado en completar cada juego en segundos.

Juego

Será la clase encargada de toda la lógica de negocio, el usuario interactuará con el juego y el juego irá dándole preguntas al usuario para que este responda. A raíz de las respuestas del usuario el juego, al finalizarse, guardará los datos en el historial del usuario en concreto.

Pregunta

Las preguntas serán las que vea el usuario en pantalla, dependen enteramente de juego. Las preguntas tendrán una descripción y una lista de opciones de las cuales solo una será la correcta.

8.2. Seguridad

La aplicación contará con un sistema de registro e inicio de sesión con contraseña que se almacenará encriptada en la base de datos para mayor privacidad del usuario. En el sistema de logueo se requerirá la doble autentificación de la contraseña y comprobar que ambos campos coincidan.

8.3. Interfaz de Usuario

Uso de ayuda: Nuestra interfaz de usuario contará con menús de ayuda para que los usuarios puedan acceder a ellos si se sienten perdidos o no entienden algo del funcionamiento de la aplicación. Estos menús estarán disponibles en todo momento y en la parte superior de la pantalla.

Usabilidad: El juego tendrá un formato parecido al de saber y ganar, ya que es el formato más cómodo para los usuarios y el más fidedigno a la vida real. Esto lo hacemos así debido a que es mucho mejor que el usuario sepa ya de antemano al ver la interfaz de usuario que es un juego de tipo "concurso de la tele" que experimentar con cosas raras y que el usuario se vea abrumado por la novedad.

Interacción en tiempo real: El usuario podrá ver si ha acertado o no la pregunta al momento de su respuesta, ya que esto es lo más amigable para el usuario y así puede llevar un conteo de las preguntas que ha respondido correctamente.

8.4. Arquitectura

Para la arquitectura inicial contamos con una aplicación divida en microservicios que engloban y encapsulan las distintas funcionalidades de la aplicación, esta es una buena manera de simplificar la creación y la gestión de una aplicación compleja, ya que cada funcionalidad es realizada por sistemas independientes. Algunos ejemplos de estos microservicios pueden ser el de Gestión de Usuarios que se encarga del registro, el inicio de sesión y todo lo relacionado con el usuario en la aplicación.

8.5. Procesos de Desarrollo

Testing: Se realizan pruebas unitarias relacionadas con cada funcionalidad del proyecto para asegurar su correcto funcionamiento.

Deployment: Es el proceso de poner en funcionamiento la aplicación para que se pueda ejecutar y acceder a ella. Para realizar el deployment utilizamos Docker para construir las imágenes de los servicios y subirlas al repositorio.

8.6. "Under-the-hood"

Persistencia: Los datos de los usarios y su historial de partidas quedarán almacenados en una base de datos para asegurar su integridad y disponibilidad.

Extensibilidad: La aplicación está diseñada para facilitar añadir nuevos contenidos y funcionalidades, esto lo conseguimos en gran parte gracias a la arquitectura basada en microservicios que dividen las funcionalidades en módulos independiente

9. Decisiones Arquitectónicas

9.1. Motivación

Las decisiones arquitectónicas de WIChat han sido tomadas con el objetivo de garantizar que la aplicación sea escalable, modular, segura y fácil de mantener. Dado que WIChat es una aplicación web interactiva que integra varias tecnologías y servicios externos, es fundamental que su arquitectura facilite tanto el desarrollo como el despliegue y la futura evolución del sistema.

9.2. Decisiones Claves

9.2.1. Arquitectura Basada en Microservicios

Motivación: Se ha optado por una arquitectura basada en microservicios para dividir la aplicación en módulos independientes que puedan gestionarse y escalarse de manera separada. Esta decisión se tomó considerando la complejidad de la aplicación y la necesidad de hacerla flexible ante futuras ampliaciones.

Consecuencias: Cada funcionalidad clave del sistema (autenticación, gestión de usuarios, generación de preguntas, etc.) está encapsulada en un servicio independiente, lo que facilita su mantenimiento y evolución. Se puede escalar individualmente cada servicio según su demanda, optimizando el uso de recursos. Se introduce la necesidad de gestionar la comunicación entre servicios, lo que aumenta la complejidad del sistema en comparación con una arquitectura monolítica. Se requiere un Gateway Service para orquestar las llamadas entre servicios y gestionar aspectos como autenticación y seguridad.

9.2.2. Uso de React para la Interfaz de Usuario

Motivación: Para la interfaz de usuario, se ha decidido utilizar React debido a su capacidad de construir aplicaciones web dinámicas y modulares. Al ser una biblioteca ampliamente utilizada en el desarrollo frontend, permite aprovechar su ecosistema y herramientas para mejorar la experiencia de usuario.

Consecuencias: React permite dividir la interfaz en componentes reutilizables, lo que facilita el mantenimiento y la evolución del sistema. La aplicación puede ofrecer una experiencia fluida gracias a su modelo de renderizado eficiente.

9.2.3. Base de Datos en MongoDB

Motivación: Para el almacenamiento de datos, se ha elegido MongoDB por su flexibilidad y capacidad de manejar información semiestructurada sin necesidad de definir un esquema rígido. Esto resulta ideal para gestionar datos de usuarios, preguntas generadas dinámicamente y registros históricos de partidas.

Consecuencias: Se pueden almacenar datos en un formato flexible, lo que facilita cambios futuros en la estructura de la base de datos. Se simplifica la escalabilidad, ya que MongoDB permite distribuir datos en múltiples servidores. Al ser una base de datos NoSQL, es necesario adoptar estrategias para mantener la consistencia y optimizar consultas.

9.2.4. Uso de Docker para Contenerización

Motivación: Para asegurar un entorno de desarrollo y producción consistente, se ha optado por contenerizar los servicios utilizando Docker. Esto permite desplegar la aplicación en cualquier servidor sin preocuparse por configuraciones específicas del sistema operativo.

Consecuencias: Cada microservicio se ejecuta en su propio contenedor, lo que facilita el despliegue y mantenimiento. Se mejora la portabilidad de la aplicación, ya que puede ejecutarse en distintos entornos sin cambios significativos. Se requiere gestionar adecuadamente los contenedores y la orquestación de servicios, lo que puede agregar complejidad al desarrollo y despliegue.

9.2.5. Integración con Wikidata y un Modelo de Lenguaje (LLM)

Motivación: Uno de los pilares de WIChat es la generación automática de preguntas basadas en información de Wikidata. Además, se ha integrado un modelo de lenguaje (LLM) para proporcionar pistas y mejorar la interacción con los usuarios.

Consecuencias: Se reduce la necesidad de intervención manual en la creación de preguntas, automatizando el proceso y permitiendo una mayor variedad de contenidos. Se introduce una dependencia con servicios externos, lo que puede afectar la disponibilidad y latencia del sistema en caso de problemas en estas APIs. Es necesario implementar mecanismos para validar y filtrar la información generada, evitando errores o inconsistencias en las preguntas y respuestas.

9.2.6. Seguridad mediante HTTPS y doble autenticación

Motivación: Dado que WIChat maneja información de usuarios, es esencial garantizar su seguridad. Para ello, todas las comunicaciones se realizan a través de HTTPS y se emplea doble factor para loguearse.

Consecuencias: Se protege la información personal de los usuarios mediante el cifrado de datos en tránsito. Se previenen accesos no autorizados mediante un sistema de doble autenticación.

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

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.

Árbol de atributos de calidad

10.2. Quality Scenarios

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.

10.2.1. Usabilidad y experiencia de usuario

  • Interactividad fluida: La aplicación debe ser intuitiva y fácil de usar, es decir, los usuarios deben poder navegar entre preguntas, acceder a pistas y responder sin dificultades. El tiempo de respuesta del sistema debe ser bajo para evitar frustración.

  • Accesibilidad y diseño web: El sistema debe ser totalmente accesible desde la web.

10.2.2. Rendimiento

  • Tiempo de respuesta: El tiempo para obtener pistas, preguntas y procesar las respuestas debe ser mínimo. Con esto nos referimos a las consultas a APIs externas para la obtención de información de Wikidata y la generación de respuestas o pistas por parte del LLM.

10.2.3. Seguridad

  • Protección de la información del usuario: El sistema debe garantizar la seguridad de los datos personales de los usuarios relacionados con el histórico de su participación en el sistema.

  • Autenticación y autorización: El acceso a funcionalidades de usuario como consultar el número de juegos, preguntas acertadas/falladas… debe estar protegido mediante autenticación segura.

10.2.4. Mantenibilidad

  • Código limpio y documentado: El código fuente debe ser legible, bien estructurado y documentado para facilitar su mantenimiento y extensión. La calidad del código será evaluada mediante revisiones periódicas y el uso de herramientas de análisis estático de código.

  • Actualizaciones y despliegues continuos: La aplicación debe seguir un ciclo de vida de desarrollo ágil, con integración y despliegue continuos (CI/CD), permitiendo que las nuevas funcionalidades y correcciones sean implementadas de manera fluida y sin afectar a los usuarios finales.

10.2.5. Pruebas y calidad del software

  • Cobertura de pruebas: El sistema debe contar con un conjunto completo de pruebas unitarias e integración.

  • Pruebas de aceptación: Se deben realizar pruebas de aceptación (end-to-end).

  • Pruebas de carga: El sistema debe someterse a pruebas de carga.

11. Riesgos y Deuda Técnica

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

A continuación se expresan algunos riesgos encontrados que suponen un peligro al desarrollo del proyecto y pueden retrasarlo o mermar su calidad.

Riesgo Descripción Mitigación

Poco o nulo conocimiento de las tecnologías usadas

Varias de las tecnologías usadas en el proyecto son nuevas para el equipo de desarrollo, lo que puede llevar a mal uso de estas y un código deficiente.

Tratar de informarse bien de estas tecnologías mediante documentación, tutoriales u otras herramientas externas.

Poca experiencia en gestión de proyectos

Al ser uno de los primeros proyectos a mayor escala hecho por los desarrolladores, la gestión, decisiones y desarrollo del proyecto puede no ser el mejor posible.

Identificar los riesgos de proyectos pasados y escuchar las experiencias de compañeros y los consejos de los profesores puede ayudar a evitar los errores más comunes y encaminar el proyecto.

Trabajo en equipo deficiente

La falta de experiencia en proyectos puede llevar a un trabajo en equipo no muy favorable, ya sea por falta de comunicación, falta de organización o reparto ineficiente de las tareas.

Promover la comunicación, ayuda y cooperación entre los miembros del equipo.

Uso ineficiente del control de versiones

Aunque GitHub no es una tecnología nueva, contiene muchas funciones complejas y nuevas que aunque resultan útiles, pueden causar confusión.

Informarse de las posibilidades que ofrece GitHub y promover un buen uso de este.

Fechas de entregas

Debido a las estrictas fechas de entrega, puede llevar a prisa en las entregas y atajos poco recomendables.

Llevar un registro constante del trabajo realizado y promover el trabajo constante semana a semana.

Abandono de miembros del equipo

Alguno de los miembros del grupo puede abandonar el proyecto, perjudicando el ritmo del desarrollo y dejando tareas desasignadas.

Minimizar el "factor del autobús", revisando el trabajo de otros compañeros y asignando el trabajo a varios compañeros.

11.2. Deuda Técnica

Atajos o compromisos que se han tomado para acortar el tiempo de desarrollo o bajar la complejidad de la implementación.

Debido a la etapa temprana del proyecto, no se ha acumulado excesiva deuda técnica. Sin embargo, con las decisiones que se tomen a lo largo del proyecto, la deuda técnica aumentará y este apartado se actualizará.

Deuda Técnica Descripción

Comienzo del desarrollo desde la base creada por los profesores

Usamos una base para el proyecto con varios microservicios ya incorporados y con algunas tecnologías ya usadas. Al ser código no desarrollado por el equipo, puede resultar en confusión e implementación deficiente.

Uso de TypeScript

Decidimos utilizar TypeScript gracias a su implementación de tipos y detección de errores en tiempo de compilación, sin embargo el proyecto base está implementado en JavaScript y no sabemos el impacto que puede tener esta decisión en relación con otros componentes.

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.

Term Definition

Base de Datos

Sistema para almacenar, gestionar y recuperar datos de manera eficiente. Es un conjunto de datos conectados entre sí, que están estructurados de tal forma que se pueden consultar, actualizar y manipular fácilmente.

LLM

Modelo de Lenguaje Grande. Es un tipo de modelo de inteligencia artificial entrenado con una gran cantidad de datos textuales. Estos modelos están diseñados para entender, generar y manipular texto en lenguaje natural como si estuvieran conversando de manera coherente en respuesta a diferentes entradas.

Usabilidad

Facilidad con la que los usuarios pueden interactuar con una aplicación o sistema para lograr sus objetivos de manera eficiente, efectiva y satisfactoria.

GitHub

GitHub es una plataforma de desarrollo colaborativo para alojar proyectos utilizando el sistema de control de versiones Git.

Microservicios

Enfoque arquitectónico y organizativo para el desarrollo de software donde el software está compuesto por pequeños servicios independientes que se comunican a través de API bien definidas.

API

Conjunto de reglas o protocolos que permite a las aplicaciones informáticas comunicarse entre sí para intercambiar datos, características y funcionalidades.

JavaScript

Lenguaje de programación que los desarrolladores utilizan para hacer páginas web interactivas.

TypeScript

Lenguaje de programación que añade funcionalidad adicional a JavaScript.

Docker

Plataforma de contenedorización que nos permite desarrollar y ejecutar la aplicación en contenedores. Facilita la gestión de dependencias y despliegues, asegurando una buena consistencia entre entornos de desarrollo, prueba y producción.

Arc42

Plantilla para la documentación y diseño arquitectónico del software de nuestra aplicación. Nos proporciona una estructura estandarizada que ayuda a describir la arquitectura de la aplicación de manera clara y fácil de comprender.

PlantUML

Herramienta utilizada para crear diagramas a partir de texto, que permite generar diagramas de secuencia, de clases…​