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 las necesidades importantes y las fuerzas mayores que los arquitectos del software y el equipo de desarrollo deben considerar Esto incluye

  • Objetivos comerciales subyacentes,

  • Características esenciales,

  • Requisitos funcionales esenciales,

  • Objetivos de calidad para la arquitectura y

  • Partes interesadas relevantes y sus expectativas.

1.1. Descripción de los requisitos

  • Registro e Inicio de Sesión de Usuarios: Los usuarios deberán registrarse para participar en los juegos, o iniciar sesión si ya se han registrado previamente.

  • Generación de Preguntas y Respuestas: El sistema proporcionará preguntas de diversas temáticas. Se generarán automáticamente respuestas correctas e incorrectas utilizando datos de Wikidata. Cada pregunta tendrá 4 posibles respuestas.

  • Interacción con el Sistema de Pistas: Los usuarios podrán interactuar con la aplicación para obtener pistas sobre las preguntas Las pistas serán generadas de forma conversacional mediante un modelo de lenguaje (LLM), accediendo a través de una API.

  • Historial de Participación del Usuario: El sistema registrará el historial de los usuarios. Se almacenarán datos como el número de juegos jugados, preguntas acertadas y falladas, y el tiempo utilizado.

  • Límite de Tiempo para Responder: Cada pregunta tendrá un límite de tiempo determinado para ser respondida por los usuarios.

  • API de Acceso a la Información: Se ofrecerá una API documentada para acceder a la información de los usuarios y a las preguntas generadas. Esto facilitará la integración con otros servicios o plataformas.

  • Generación Automática de Contenidos: Las imágenes de las preguntas y las pistas serán generadas automáticamente utilizando datos de Wikidata. Esto garantizará la variedad y el contexto adecuado de las preguntas.

1.2. Objetivos de Calidad

Contenido

Los tres (máximo cinco) objetivos de calidad más importantes para la arquitectura, cuya satisfacción es de máxima importancia para los principales interesados. Nos referimos realmente a los objetivos de calidad de la arquitectura. No los confundas con los objetivos del proyecto. No son necesariamente idénticos.

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

Categorías de Requisitos de Calidad
Motivación

Debes conocer los objetivos de calidad de tus interesados más importantes, ya que influirán en decisiones arquitectónicas fundamentales. Asegúrate de ser muy concreto sobre estas cualidades y evita palabras de moda. Si como arquitecto no sabes cómo se juzgará la calidad de tu trabajo…​

Formato

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

Meta Descripción

Rendimiento

El sistema debe garantizar tiempos de respuesta dentro de los límites aceptables, incluso en condiciones de alta demanda. Se optimizará el uso de recursos para minimizar la latencia y mejorar la experiencia del usuario. Además, se implementarán optimizaciones de consultas para reducir la carga en los servidores y mejorar la velocidad de ejecución de las funciones más críticas.

Escalabilidad

El diseño del sistema debe permitir un crecimiento eficiente, asegurando que pueda manejar un aumento en la cantidad de usuarios y datos sin afectar negativamente el rendimiento.

Seguridad

Se establecerán medidas de seguridad para proteger los datos de los usuarios y prevenir accesos no autorizados. Se implementarán mecanismos de autenticación y estándares básicos para garantizar la integridad y privacidad de la información.

Mantenibilidad

El código del sistema debe ser claro, modular y bien documentado para facilitar futuras modificaciones y mejoras. Se adoptarán buenas prácticas de desarrollo, como la separación de responsabilidades, la reutilización de código y la escritura de pruebas unitarias para garantizar la estabilidad del sistema a lo largo del tiempo. Además, se fomentará el uso de herramientas de control de versiones para gestionar los cambios de manera eficiente.

Usabilidad

Para asegurar una experiencia de usuario óptima, el sistema contará con una interfaz intuitiva y coherente. Se priorizará un diseño claro y accesible, facilitando la navegación. Se tendrán en cuenta principios de usabilidad como la predictibilidad, la coherencia visual y la retroalimentación adecuada, de manera que cualquier usuario, independientemente de su experiencia, pueda utilizar el sistema sin dificultades.

1.3. Stakeholders

Contenido

Descripción explícita de los interesados del sistema, es decir, todas las personas, roles u organizaciones que

  • deben conocer la arquitectura

  • les debe convencer la arquitectura

  • deben 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

Debe conocer a todas las partes involucradas en el desarrollo del sistema o afectadas por el sistema. De lo contrario, puede tener sorpresas desagradables más adelante en el proceso de desarrollo. Estos interesados determinan el alcance y el nivel de detalle de su 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

Cliente

RTVE

Alta disponibilidad, seguridad y cumplimiento de normativas

Compañía Contratada

ChattySw

Entrega a tiempo, dentro del presupuesto y con alta calidad

Equipo de Desarrollo

Andrea Acero Suárez, Ana Díez Díaz, Aitor Gómez Ogueta, Adriana Herrero González, Claudia Nistal Martínez, Javier Sanabria Miranda

Claridad en los requisitos, apoyo continuo del cliente y herramientas adecuadas

Usuarios

Futuros usuarios de la aplicación

Facilidad en el uso, rendimiento eficiente y características claras e innovadoras

2. Restricciones de arquitectura

Contenidos

Cualquier requisito que limite la libertad de los arquitectos de software en sus decisiones de diseño e implementación, o en decisiones sobre el proceso de desarrollo. Estas restricciones a veces van más allá de los sistemas individuales y son aplicables a organizaciones y empresas enteras.

Motivación

Los arquitectos deben saber exactamente dónde tienen libertad en sus decisiones de diseño y dónde deben adherirse a restricciones. Las restricciones siempre deben ser consideradas; sin embargo, pueden ser negociables.

Formato

Tablas simples de restricciones con explicaciones. Si es necesario, puedes subdividirlas en: Restricciones técnicas, Restricciones organizativas y políticas, y convenciones (por ejemplo, guías de programación o versionado, documentación o convenciones de nomenclatura).

Información Adicional

Consulta Architecture Constraints en la documentación de arc42.

Para desarrollar cualquier proyecto de software, aparecen limitaciones y condiciones que debemos tener en cuenta. No tenemos total libertad ni para diseñar el sistema ni para implementarlo. Además, el nivel y la cantidad de restricciones aumentan a medida que el desarrollo evoluciona. Un ejemplo de esto es la mayor dificultad para modificar el modelo de datos a medida que pasa el tiempo.

Es importante que el arquitecto sepa cómo equilibrar los requisitos del proyecto con las restricciones del mismo. Las restricciones encontradas en nuestro proyecto han sido las siguientes:

RESTRICCIONES TÉCNICAS

Restricción Descripción

Uso de un LLM

Se utilizará un modelo de lenguaje grande (LLM) para generar automáticamente preguntas y respuestas y permitir obtener pistas.

Wikidata

Las preguntas y respuestas, así como las pistas, se generarán a partir de los datos de Wikidata.

Docker

La web deberá estar desplegada y accesible a través de la Web.

Generación de Preguntas

Las preguntas tendrán una respuesta correcta y varias incorrectas. Las respuestas se generarán automáticamente.

API Usage

Se utilizarán APIs para acceder a la información de usuarios y preguntas generadas.

Frontend Web

El sistema tendrá al menos un frontend web desplegado y accesible a través de la Web.

Límite de tiempo

Las preguntas deben ser respondidas dentro de un plazo de tiempo determinado.

RESTRICCIONES ORGANIZATIVAS

Restricción Descripción

Gestión de Usuarios

Los usuarios podrán registrarse, iniciar sesión y revisar su historial de participación en el sistema.

Grupos de 4-6 personas

Grupos pequeños de alumnos para realizar el trabajo, elegidos por el profesor.

RESTRICCIONES POLÍTICAS

Restricción Descripción

Tema de la Aplicación

La aplicación será similar al programa "Saber y Ganar", por lo que las preguntas estarán relacionadas con imágenes.

Uso de Arc42

El proyecto seguirá el estándar de documentación Arc42.

Repositorio Público

El código fuente estará alojado en un repositorio público en GitHub, y será accesible para los miembros del equipo.

CONVENCIONES

Restricción Descripción

Convenciones de Nombres

El nombre de la aplicación será WIChat.

Uso de Git y Github

Se utilizará Git como sistema de control de versiones, y el repositorio será alojado en GitHub.

Documentación Arc42

Se seguirá la convención de documentación Arc42.

3. Contexto y Alcance

Contenido

El ámbito y contexto del sistema, como su nombre lo indica, delimita el sistema (es decir, su ámbito) de todos sus interlocutores (sistemas y usuarios vecinos, es decir, el contexto del sistema). De este modo, especifica las interfaces externas.

Si es necesario, diferencie el contexto empresarial (entradas y salidas específicas del dominio) del contexto técnico (canales, protocolos, hardware)..

Motivación

Las interfaces de dominio y las interfaces técnicas con los socios de comunicación se encuentran entre los aspectos más críticos de su sistema. Asegúrese de comprenderlas por completo.

Formato

Varias opciones:

  • Varios diagramas de contexto

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

Más información

Vea Context and Scope en la documentación arc42.

3.1. Contexto de Negocio

Contexto de Negocio
Elemento Descripción

Usuario

El concursante que interactúa con la aplicación, juega y recibe pistas.

Base de Datos

Sistema de almacenamiento que guarda información relevante sobre el usuario.

WIChat

Aplicación web principal donde se desarrolla el juego.

Wikidata

Fuente de donde se extraen las preguntas, las imágenes y las respuestas.

LLM_API

API que integra un modelo de lenguaje que se utiliza para generar pistas dinámicas y conversacionales que ayudan al concursante a responder las preguntas.
Contenido

Especificación de todos los interlocutores (usuarios, sistemas informáticos, etc.) con explicaciones de las entradas y salidas o interfaces específicas del dominio. Opcionalmente, puede añadir formatos o protocolos de comunicación específicos del dominio.

Motivación

Todas las partes interesadas deben comprender qué datos se intercambian con el entorno del sistema.

Formato

Todo tipo de diagramas que muestran el sistema como una caja negra y especifican las interfaces del dominio con los socios de comunicación.

Como alternativa (o adicionalmente), puede utilizar una tabla. El título de la tabla es el nombre de su sistema, las tres columnas contienen el nombre del interlocutor, las entradas y las salidas.

3.2. Contexto Técnico

Contenido

Interfaces técnicas (canales y medios de transmisión) que juntan el sistema con su entorno. Además un mapeo del dominio especifico de entrada/salida a los canales, es decir una explicación de qué entrada salida usa cada canal.

Motivación

Muchos stakeholders toman decisiones arquitectónicas basadas en las interfaces técnicas entre el sistema y su contexto. En especial, los diseñadores de hardware o infraestructura deciden estas interfaces técnicas.

Formato

E.g. Diagrama UML de despliegue describiendo canales con los sistemas vecinos, junto a una tabla de mapeo mostrando las relaciones entre canales y la entrada/salida.

3.2.1. Diagrama de Despliegue

Diagrama de Despliegue

3.2.2. Explicación de Interfaces Técnicas

WebApp

Aplicación web hecha con React que aporta al usuario una interfaz con la que interactuar y por medio de la cual hacer las peticiones correspondientes al backend

gatewayservice

API que hace de enlace entre las distintas partes de la aplicación. Funciona como una especie de fachada que sirve para que los distintos microservicios no tengan por qué conocerse entre ellos, para comunicarse solo deben de hacer peticiones al gateway y este hará una redirección de la petición al servicio correspondiente.

authservice

Servicio que se comunica con la base de datos de usuarios a fin de comprobar si los datos introducidos de inicio de sesión se corresponden con un usuario

userservice

Servicio que se comunica con la base de datos de usuarios a fin de añadir usuarios y modificar los datos relativos a los usuarios

Base de Datos "userdb"

Base de datos que almacena toda la información de los usuarios como su nombre de usuario, sus datos de logIn, etc

gameservice

Servicio que guarda la información relativa a las partidas de los usuarios en la base de datos "bd". Además, gestiona los datos de configuración de la partida (topics e idioma), almacenandolos en una caché para un rápido acceso. Estos datos posteriormente son utilizados por el questionservice para obtener las preguntas usando dicha configuración.

Base de Datos "bd"

Base de datos que almacena la información de las partidas jugadas por los usuarios

questionservice

Servicio que genera las preguntas por medio de plantillas para los diferentes topics e idiomas y utiliza Wikidata para la obtención de las respuestas correctas y falsas.

API WikiData

API del servicio web WikiData que aportará a la aplicación las imágenes para el juego, las respuestas a las mismas y las pistas que el LLM utilizará para responder a los usuarios

llmservice

Servicio que, por medio de la respuesta correcta a la pregunta actual de la partida, procesará y responderá a las preguntas que tenga el usuario por medio de pistas, sin dar dicha respuesta correcta directamente

API LLM

Servicio externo que nos permite acceder al modelo de lenguaje y utilizarlo

3.2.3. Mapeo de Canales de Entrada/salida

Canal Entrada Salida

WebApp

Peticiones HTTP del usuario indicando sus acciones

Responde con información a través de la interfaz.

gatewayservice

Peticiones REST de los microservicios para realizar acciones en la aplicación

Respuesta con la información/acciones solicitadas obtenida de otros microservicios.

authservice

Datos de inicio de sesión de un usuario

Resultado de comprobación de los datos de inicio de sesión

userservice

Datos a insertar/modificar en la base de datos

Modificación o inserción completa a la base de datos

Base de Datos "userdb"

Instrucciones para consultas o insercioes en base de datos

Resultado de las consultas o confirmación de las inserciones

gameservice

Información de inicio de partida o final de partida

Responde con confirmación de las operaciones o con id de caché para rápido acceso a la configuración de la partida

Base de Datos "bd"

Instrucciones para consultas o inserciones en base de datos

Resultado de las consultas o confirmación de las inserciones

questionservice

Configuración de la partida

Pregunta con las posibles respuestas (correcta e incorrectas)

API Wikidata

Solicitud de imagenes o pistas

Imagen nueva, respuesta o pista sobre la imagen ofrecida con anterioridad

llmservice

Prompt de solicitud de pistas y respuesta correcta a la pregunta

Pista generada por el modelo evitando decir la respuesta correcta

API LLM

Prompt de solicitud de pistas

Respuesta del modelo de lenguaje generada a partir del prompt

4. Estrategia de Solución

4.1. Deciciones tecnológicas

4.1.1. Frontend

  • Motivación: Elegimos JavaScript y React para el desarrollo del frontend por su flexibilidad y su capacidad para crear interfaces dinámicas y altamente interactivas. Dado que uno de los objetivos clave del proyecto es la usabilidad, React facilita el desarrollo de interfaces modernas y centradas en el usuario, lo que optimiza la experiencia. Además, React es ampliamente utilizado y bien soportado, lo que facilita la integración y el mantenimiento.

  • Objetivos de calidad: Usabilidad, Mantenibilidad, Integrabilidad

  • Restricciones clave: El sistema debe ser accesible desde diferentes plataformas y dispositivos, incluyendo navegadores web modernos.

4.1.2. Backend

  • Motivación: Node.js con Express fue elegido para el desarrollo del backend debido a su rendimiento, escalabilidad y naturaleza no bloqueante, lo cual es crucial cuando se manejan múltiples solicitudes simultáneas en una aplicación web. Express, por su parte, es un framework minimalista y permite construir APIs RESTful eficientes, lo que se adapta bien a las necesidades de integración del sistema con diversas APIs externas.

  • Objetivos de calidad: Rendimiento, Escalabilidad, Mantenibilidad

  • Restricciones clave: El sistema debe ser capaz de gestionar múltiples servicios de manera independiente y eficiente, con una comunicación fluida entre ellos.

4.1.3. Base de Datos

  • Motivación: Se optó por MongoDB debido a su capacidad para manejar grandes volúmenes de datos sin requerir un esquema riguroso, lo que permite flexibilidad al trabajar con datos no estructurados y su escalabilidad horizontal. Esta decisión responde a la necesidad de escalabilidad y rendimiento en un sistema que debe ser capaz de crecer de manera flexible a medida que aumenta la cantidad de usuarios y datos.

  • Objetivos de calidad: Escalabilidad, Mantenibilidad, Integrabilidad, Rendimiento

  • Restricciones clave: El sistema debe ser capaz de manejar grandes volúmenes de datos y ser altamente escalable.

4.1.4. APIs Externas

  • Motivación: La elección de SPARQL permite integrar consultas semánticas eficientes a bases de datos con información estructurada. Además, utilizamos la API de Gemini debido a los problemas recurrentes de caídas de los servidores de Empathy, lo que hace que la solución basada en Gemini sea más confiable. Esta decisión ayuda a garantizar la disponibilidad del sistema y evitar puntos de fallo únicos.

  • Objetivos de calidad: Disponibilidad, Fiabilidad, Rendimiento

  • Restricciones clave: La API de Gemini debe integrarse de manera eficiente con el sistema, proporcionando una solución confiable en lugar de las APIs de Empathy que presentan interrupciones.

4.1.5. Contenedores

  • Motivación: Docker fue elegido para la creación de contenedores por su capacidad para simplificar el proceso de despliegue y asegurar la consistencia entre entornos de desarrollo, pruebas y producción. El uso de Docker facilita la escalabilidad del sistema, permitiendo agregar más instancias de servicios según sea necesario y mejorar la disponibilidad del sistema.

  • Objetivos de calidad: Escalabilidad, Disponibilidad, Mantenibilidad

  • Restricciones clave: La infraestructura debe ser fácil de gestionar y desplegar en diferentes entornos sin generar complejidad adicional.

4.1.6. Infraestructura

  • Motivación: AWS es la plataforma de elección debido a su alta disponibilidad, flexibilidad y los servicios gestionados ofrecen escalabilidad automática y balanceo de carga, lo que es clave para lograr una infraestructura robusta. Además, al usar AWS se puede aprovechar su seguridad, fiabilidad y la capacidad de escalar recursos según las necesidades del proyecto.

  • Objetivos de calidad: Disponibilidad, Escalabilidad, Fiabilidad

  • Restricciones clave: El sistema debe ser capaz de escalar horizontalmente y manejar altos volúmenes de tráfico sin sacrificar disponibilidad.

4.1.7. Infraestructura como Código

  • Motivación: Terraform se utilizó para gestionar la infraestructura como código, lo que permite definir y administrar los recursos de AWS de manera repetible y consistente. Esto facilita la creación, actualización y destrucción de recursos de infraestructura de manera automatizada, lo que aumenta la eficiencia y reduce los errores manuales.

  • Objetivos de calidad: Fiabilidad, Eficiencia

  • Restricciones clave: La infraestructura debe ser fácil de gestionar y replicar, y las actualizaciones deben ser controladas para garantizar la estabilidad del sistema.

4.1.8. Modelado

  • Motivación: PlantUML se utiliza para crear diagramas de arquitectura y diseño debido a su simplicidad y la capacidad de generar diagramas automáticamente a partir de texto, lo que facilita la documentación continua y permite mantener actualizados los diagramas a lo largo del desarrollo.

  • Objetivos de calidad: Comunicación, Claridad, Consistencia

  • Restricciones clave: La documentación debe ser fácilmente comprensible y mantenerse actualizada durante todo el ciclo de vida del proyecto.

4.1.9. Control de Versiones

  • Motivación: GitHub es la herramienta de control de versiones elegida debido a su popularidad y facilidad de uso, lo que permite la colaboración entre los miembros del equipo de desarrollo. Además, permite una gestión eficiente del código fuente, la revisión y el seguimiento de cambios, lo que es fundamental para mantener la calidad y la integridad del código.

  • Objetivos de calidad: Colaboración, Integridad, Mantenibilidad

  • Restricciones clave: El sistema de control de versiones debe ser accesible para todos los miembros del equipo, y debe permitir una colaboración eficiente.

4.1.10. Pruebas de Carga

  • Motivación: Artillery se utiliza para realizar pruebas de carga y estrés en el sistema, lo que permite evaluar el rendimiento y la escalabilidad del sistema bajo diferentes condiciones de carga. Artillery es una herramienta ligera y escalable que proporciona informes detallados sobre el rendimiento y permite identificar posibles cuellos de botella.

  • Objetivos de calidad: Rendimiento, Escalabilidad

  • Restricciones clave: El sistema debe soportar un alto volumen de tráfico sin afectar la experiencia del usuario ni comprometer la estabilidad.

4.2. Decisiones sobre la Descomposición de Alto Nivel

4.2.1. Patrón Arquitectónico

  • Motivación: El sistema sigue un patrón de microservicios, donde cada componente del sistema se gestiona de manera independiente. Sin embargo, userservice y authservice son los únicos servicios que comparten una misma base de datos, ya que ambos requieren acceso frecuente a la misma información de usuarios y autenticación. Los demás servicios tienen bases de datos propias, lo que mejora la modularidad y la independencia de cada servicio. Este enfoque permite escalabilidad y flexibilidad, y facilita el despliegue y la gestión de los servicios de manera autónoma.

  • Objetivos de calidad: Escalabilidad, Mantenibilidad, Flexibilidad

  • Restricciones clave: La interacción entre los microservicios debe ser eficiente, especialmente entre userservice y authservice, que comparten la base de datos, sin generar dependencias críticas entre los demás servicios.

4.2.2. Descomposición del Sistema

  • Motivación: El sistema se divide en módulos responsables de diferentes partes del proyecto (backend, frontend, base de datos y APIs externas). Cada módulo puede ser desarrollado, desplegado y escalado de manera independiente, lo que mejora la capacidad de mantenimiento y actualización del sistema.

  • Objetivos de calidad: Escalabilidad, Mantenibilidad, Flexibilidad

  • Restricciones clave: La estructura modular debe garantizar que la comunicación entre los servicios sea efectiva y no introduzca cuellos de botella.

4.3. Decisiones sobre cómo lograr los Objetivos Clave de Calidad

4.3.1. Usabilidad

  • Se prioriza la usabilidad al usar React, ya que permite crear interfaces ricas en interactividad y con un rendimiento fluido. La experiencia de usuario es fundamental en este proyecto, y React facilita la creación de interfaces dinámicas que responden de manera eficiente a las acciones del usuario.

4.3.2. Disponibilidad

  • El uso de AWS junto con Docker permite que el sistema sea altamente disponible, ya que facilita la recuperación ante fallos y la escalabilidad automática, lo cual es crucial para mantener el sistema operativo sin interrupciones y manejar picos de tráfico.

4.3.3. Compatibilidad

  • Se eligieron React y Node.js por su compatibilidad con una amplia gama de plataformas y dispositivos, lo que permite que la aplicación sea accesible desde diferentes navegadores y dispositivos, mejorando así la accesibilidad para los usuarios.

4.3.4. Escalabilidad y Rendimiento

  • Para garantizar la escalabilidad y rendimiento, se seleccionaron tecnologías como MongoDB y AWS, que permiten manejar el crecimiento del sistema de manera eficiente. MongoDB ofrece escalabilidad horizontal, mientras que AWS proporciona recursos flexibles que pueden adaptarse a las demandas del sistema. Docker también facilita la replicación de servicios según se requiera.

4.3.5. Seguridad

  • Dado que se prioriza la seguridad del sistema, se implementó un sistema de penalización de IP en el login para mitigar ataques de fuerza bruta. Además, los datos sensibles, como las contraseñas de los usuarios, son encriptados en la base de datos para garantizar que no puedan ser accesibles incluso si los datos son comprometidos.

4.4. Decisiones Organizativas Relevantes

  • Proceso de desarrollo: Se eligió un proceso de desarrollo ágil utilizando GitHub para la gestión del código, tareas y colaboración, lo que facilita la integración continua y las entregas incrementales. Esto se adapta a la necesidad de iterar rápidamente y adaptarse a los cambios durante el desarrollo.

  • Delegación de tareas: Se delegaron tareas de infraestructura y operaciones a AWS (con Terraform) y Docker para asegurar un entorno de producción confiable, escalable y fácil de mantener. Esto reduce la carga operativa sobre el equipo de desarrollo y mejora la eficiencia en la gestión de recursos.

Contents

Un breve resumen y explicación de las decisiones fundamentales y estrategias de solución que dan forma a la arquitectura del sistema. Incluye:

  • decisiones tecnológicas

  • decisiones sobre la descomposición de alto nivel del sistema, por ejemplo, el uso de un patrón arquitectónico o de diseño

  • decisiones sobre cómo lograr los objetivos clave de calidad

  • decisiones organizativas relevantes, por ejemplo, la selección de un proceso de desarrollo o la delegación de ciertas tareas a terceros.

Motivation

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

Form

Mantén las explicaciones de dichas decisiones clave breves.

Motiva lo que se decidió y por qué se decidió de esa manera, basándote en la declaración del problema, los objetivos de calidad y las restricciones clave. Consulta los detalles en las secciones siguientes.

Further Information

Consulta Estrategia de Solución en la documentación de arc42.

5. Vista de Bloques

Content

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

Esta vista es obligatoria para toda documentación de arquitectura. En analogía con una casa, esta es el plano de planta.

Motivation

Mantén una visión general de tu código fuente haciendo que su estructura sea comprensible a través de la abstracción.

Esto te permite comunicarte con tus interesados a un nivel abstracto sin revelar detalles de implementación.

Form

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

Hierarchy of building blocks

Nivel 1 es la descripción de caja blanca del sistema general junto con las descripciones de caja negra de todos los bloques de construcción contenidos.

Nivel 2 amplía algunos bloques de construcción del nivel 1. Por lo tanto, contiene la descripción de caja blanca de bloques de construcción seleccionados del nivel 1, junto con las descripciones de caja negra de sus bloques de construcción internos.

Nivel 3 amplía bloques de construcción seleccionados del nivel 2, y así sucesivamente.

Further Information

Consulta Vista de Bloques de Construcción en la documentación de arc42.

5.1. Nivel 1: Caja blanca del Sistema General

building block view1
Motivación

La aplicación WiChat tiene la estructura básica para generar preguntas desde WikiData, plantearlas al usuario y, si lo desea, puede recibir pistas generadas por un modelo de lenguaje.

Contained Building Blocks
Nombre Descripción

Usuario

Usuario de la aplicación que interactúa con ella.

WiChat

El sistema a implementar, tomará la información necesaria de WikiData para generar preguntas y generará pistas con el uso de un LLM.

WikiData

Tiene la información necesaria para generar preguntas genéricas de varias temáticas para las partidas de los usuarios.

Gemini

Es un modelo de lenguaje que se utiliza para generar pistas basadas en las preguntas generadas, proporcionando respuestas coherentes y contextuales.

5.2. Nivel 2

building block view2
Motivación

Esto muestra el flujo principal de datos de la aplicación y también la decisión arquitectónica de usar microservicios a los cuales se conectará la Interfaz de Usuario.

Contained Building Blocks
Nombre Descripción

Interfaz de Usuario

Proporciona una interfaz que el usuario final de la aplicación puede utilizar.

Microservicios

Proveen un backend para la Interfaz de Usuario, manteniendo la aplicación modular, mantenible, reutilizable y fácil de distribuir.

5.3. Nivel 3

building block view3
Motivación

En este diagrama podemos ver los microservicios que proporcionarán todas las operaciones necesarias para que la aplicación funcione como el usuario se espera.

Contained Building Blocks
Nombre Descripción

Game Service

Es el microservicio que se encargará de la creación, mantenimiento y finalización de juegos, registrará todos los juegos y las puntuaciones de los usuarios.

User Service

Es un microservicio que proporciona a la Interfaz de Usuario todos los datos necesarios relacionados con los usuarios, como su perfil y estadísticas.

Auth Service

Es un microservicio que los usuarios pueden usar para iniciar sesión en la aplicación. Funciona mediante autenticación por token para que sea compatible entre microservicios.

Question Service

Su propósito principal es ser una abstracción sobre la API de WikiData, de modo que el microservicio Game Service pueda solicitarle preguntas directamente en lugar de tener que interactuar con la API de WikiData.

LLM Service

Es un microservicio que utiliza un modelo de lenguaje para generar pistas basadas en las preguntas proporcionadas, asegurando respuestas coherentes y contextuales para mejorar la experiencia del usuario.

Game Data y User Data

Son las bases de datos principales de la aplicación y juntas almacenarán todos los datos persistentes importantes de la aplicación.

6. Vista en tiempo de ejecución

Contents

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

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

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

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

  • error and exception scenarios

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

Motivation

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

Form

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

  • numbered list of steps (in natural language)

  • activity diagrams or flow charts

  • sequence diagrams

  • BPMN or EPCs (event process chains)

  • state machines

  • …​

Further Information

See Runtime View in the arc42 documentation.

6.1. Un usuario se registra en el sistema

User Registration Sequence

6.2. Un usuario juega al juego de las preguntas y solicita pistas

Question Game with Hint Sequence

6.3. El usuario quiere ver su historial de la partida

Game History Sequence

7. Vista de Despliegue

Contenido

La vista de despliegue describe:

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

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

A menudo, los sistemas se ejecutan en diferentes entornos, como el entorno de desarrollo, entorno de pruebas y entorno de producción. En tales casos, debes documentar todos los entornos relevantes.

Es especialmente importante documentar 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 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 capturar.

Motivación

El software no funciona sin hardware. Esta infraestructura subyacente puede y va a influir en un sistema y/o en algunos conceptos transversales. Por lo tanto, es necesario conocer la infraestructura.

Formato

Es posible que un diagrama de despliegue de alto nivel ya esté contenido en la sección 3.2 como contexto técnico, con tu propia infraestructura representada como UNA caja negra. En esta sección se puede hacer zoom en esa caja negra utilizando diagramas de despliegue adicionales:

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

  • Si tus stakeholders (de hardware) prefieren otros tipos de diagramas en lugar de un diagrama de despliegue, permíteles usar cualquier tipo que sea capaz de mostrar nodos y canales de la infraestructura.

Información Adicional

Consulta la Deployment View en la documentación de arc42.

7.1. Infraestructura Nivel 1

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

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

  • Las justificaciones o motivaciones importantes para esta estructura de despliegue.

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

  • La asignación de los artefactos de software a los elementos de esta infraestructura.

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

Vista de Despliegue Nivel 1
Motivación

  • Escalabilidad: AWS permite escalar horizontalmente mediante la creación de múltiples instancias de contenedores según la demanda.

  • Disponibilidad: La infraestructura de AWS facilita la alta disponibilidad a través de balanceadores de carga y zonas de disponibilidad.

  • Integración con servicios externos: La integración con Wikidata y LLM_API permite extender las capacidades de la plataforma sin complejidad adicional.

Características de Calidad y Rendimiento

  • Bajo tiempo de respuesta: La cercanía geográfica de los servidores AWS al usuario final reduce la latencia.

  • Mantenibilidad: Docker facilita la gestión de versiones de los microservicios y la rápida recuperación ante fallos.

Asignación de artefactos de software a la infraestructura

  • Microservicios: Desplegados como contenedores Docker dentro de AWS.

  • Frontend (Web Browser): Ejecutado en el dispositivo del usuario, interactuando con la API del backend alojada en AWS.

  • Base de Datos MongoDB: Desplegada en un contenedor propio dentro de AWS.

7.2. Infraestructura Nivel 2

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

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

Vista de Despliegue Nivel 2
Microservicios

  • WebApp: Servicio que sirve la aplicación frontend y se comunica con el GatewayService.

  • GatewayService: Actúa como punto de entrada único para el frontend, enrutando solicitudes a los microservicios adecuados.

  • Question Service: Gestiona las llamadas a Wikidata para conseguir las preguntas.

  • UserService: Maneja las operaciones con los usuarios.

  • AuthService: Gestiona la autenticación y autorización de usuarios.

  • Game_Service: Controla la lógica de la aplicación (modelo de dominio, conexión con la base de datos).

  • LlmService: Se conecta con la API de Gemini y gestiona el funcionamiento del LLM.

  • Base de Datos: Almacena información de usuarios, partidas y preguntas.

8. Conceptos transversales

Content

Esta sección describe las regulaciones generales y las ideas de solución que son relevantes en múltiples partes (= transversales) de tu sistema. Estos conceptos suelen estar relacionados con múltiples bloques de construcción. Pueden incluir muchos temas diferentes, tales como:

  • modelos, especialmente modelos de dominio

  • patrones de arquitectura o diseño

  • reglas para el uso de tecnologías específicas

  • decisiones principales, a menudo técnicas, de naturaleza global (= transversales)

  • reglas de implementación

Motivación

Los conceptos forman la base de la integridad conceptual (consistencia, homogeneidad) de la arquitectura. Así, son una contribución importante para lograr las cualidades internas de tu sistema.

Algunos de estos conceptos no pueden asignarse a bloques de construcción individuales, por ejemplo, seguridad o protección.

Forma

La forma puede variar:

  • documentos conceptuales con cualquier tipo de estructura

  • extractos de modelos transversales o escenarios utilizando notaciones de las vistas de arquitectura

  • implementaciones de muestra, especialmente para conceptos técnicos

  • referencia al uso típico de marcos estándar (por ejemplo, usar Hibernate para el mapeo objeto-relacional)

Estructura

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

  • Conceptos de dominio

  • Conceptos de experiencia de usuario (UX)

  • Conceptos de seguridad y protección

  • Patrones de arquitectura y diseño

  • "Bajo el capó"

  • Conceptos de desarrollo

  • Conceptos operacionales

Nota: puede ser difícil asignar conceptos individuales a un tema específico de esta lista.

Posibles temas para conceptos transversales
Más información

Consulta Conceptos en la documentación de arc42.

8.1. Arquitectura de microservicios

Hemos decidido que nuestra arquitectura se basará en microservicios, lo que significa que cada parte de la aplicación se dividirá en un servicio que realiza una función específica. Los servicios pueden comunicarse entre sí utilizando sus respectivas API. Además, en nuestra arquitectura tienen mucha importancia el papel del API Gateway, cuya función es servir como intermediario en la interacción entre servicios, de forma que estos solo se encuentren ligeramente acoplados al gateway y no a múltiples servicios diferentes.

8.2. Experiencia del usuario

La aplicación será un sitio web donde los usuarios podrán jugar a WICHAT. La funcionalidad básica consiste en mostrar una imagen y una pregunta, y el usuario deberá seleccionar la opción correcta. Además es el propio usuario el que, si se encuentra atascado en una pregunta, puede hacer una consulta, pidiendo una pista, a un modelo de lenguaje.

8.3. Persistencia

En cuanto a la gestión de datos en la aplicación, cabe mencionar que en todos los casos usamos MongoDB. El microservicio game_service gestiona la base de datos del juego, las preguntas y el historial de partidas, mientras que el microservicio user se encarga de la base de datos de los usuarios.

Bases de datos en MongoDB

8.4. Seguridad

Para garantizar la seguridad de los usuarios, la aplicación cifra sus contraseñas antes de almacenarlas en la base de datos utilizando el algoritmo bcrypt, lo que asegura que las contraseñas no se guarden de manera visible ni en texto claro. Además, se realiza una validación para asegurarse de que los campos esenciales, como el nombre de usuario y la contraseña, estén presentes en la solicitud antes de crear un nuevo usuario, lo que garantiza que los datos necesarios sean correctos y completos. Además, añadimos un control de fuerza bruta para el login. Si se falla múltiples veces seguidas al intentar hacer login, se bloquea la IP durante varios minutos.

8.5. Pruebas

Para evitar errores en nuestra aplicación, realizaremos pruebas que cubrirán tanto el frontend como el backend. Se realizarán las pruebas de aquellas funcionalidades de alta relevancia en la aplicación, no pruebas muy específicas que puedan tener poca relevancia en el funcionamiento (como comprobar si un botón cambia de color cuando se pulsa). En su lugar, nos centraremos en pruebas más generales que aseguren que todo funciona correctamente, aunque en algunos casos incluiremos aspectos más detallados si es necesario, pero solo para funcionalidades que no son cruciales.

8.6. Internacionalización

Hemos decidido adaptar la aplicación para que esté disponible en español e inglés, permitiendo que los usuarios elijan su idioma preferido.

9. Architecture Decisions

Durante el desarrollo de la aplicación, se han tomado diversas decisiones arquitectónicas que afectan tanto a la elección de tecnologías como a la estructura general del proyecto. A continuación, se detallan las principales decisiones, sus ventajas y desventajas, así como las razones detrás de cada una de ellas.

9.1. Uso de JavaScript

  • Decisión: Utilizar JavaScript como lenguaje de programación principal para la aplicación.

  • Ventajas:

    • Universalidad: JavaScript es ampliamente utilizado tanto en el front-end como en el back-end (a través de Node.js), lo que facilita el trabajo con un solo lenguaje.

    • Popularidad: La comunidad y recursos disponibles son vastos, lo que facilita la resolución de problemas y el aprendizaje.

    • Gran ecosistema: Hay muchas bibliotecas y frameworks disponibles, lo que acelera el desarrollo.

  • Desventajas:

    • Problemas de rendimiento: Para tareas muy intensivas de CPU, JavaScript puede no ser la opción más eficiente en comparación con otros lenguajes más cercanos al hardware como C++ o Rust.

9.2. Uso de React para el Front-End

  • Decisión: Utilizar React para la construcción del front-end.

  • Ventajas:

    • Componente reutilizable: React promueve la creación de componentes reutilizables, lo que facilita la gestión de interfaces complejas.

    • Curva de aprendizaje moderada: Comparado con otros frameworks front-end, React es relativamente sencillo de aprender y tiene una gran comunidad de desarrolladores.

    • Ecosistema robusto: React tiene un vasto ecosistema de herramientas y bibliotecas (como React Router, Redux, etc.) que mejoran la productividad.

  • Desventajas:

    • No todo el equipo estaba familiarizado con React: Algunos miembros del equipo no tenían experiencia previa con React, lo que aumentó el tiempo inicial de formación y aprendizaje.

9.3. Uso de MongoDB

  • Decisión: Utilizar MongoDB como base de datos NoSQL.

  • Ventajas:

    • Flexible y escalable: MongoDB permite el almacenamiento de datos sin un esquema fijo, lo que facilita la escalabilidad y adaptabilidad de los datos en una estructura de aplicación cambiante.

    • Facilidad de uso: El modelo de documentos en JSON es intuitivo y fácil de manejar, especialmente cuando se trata de grandes cantidades de datos no estructurados.

  • Desventajas:

    • Falta de experiencia en bases de datos NoSQL: El equipo no estaba completamente familiarizado con MongoDB, ya que su experiencia previa había sido mayormente con bases de datos relacionales.

9.4. Uso de Docker

  • Decisión: Utilizar Docker para la contenedorización de la aplicación.

  • Ventajas:

    • Portabilidad: Docker permite empaquetar la aplicación en contenedores que se pueden ejecutar en cualquier entorno sin preocuparse por las dependencias del sistema.

    • Consistencia: Garantiza que la aplicación se ejecute de la misma manera en desarrollo, pruebas y producción.

    • Despliegue simplificado: Los contenedores Docker facilitan el despliegue y escalado de la aplicación.

  • Desventajas:

    • Falta de experiencia con Docker: Algunos miembros del equipo no tenían experiencia previa con Docker, lo que al principio requirió un tiempo adicional de aprendizaje.

9.5. Uso de Cache (Game)

  • Decisión: Implementar un sistema de cache para almacenar y gestionar los datos del juego.

  • Ventajas:

    • Mejora el rendimiento: La caché mejora considerablemente la velocidad de acceso a los datos más frecuentes, reduciendo la carga sobre la base de datos.

    • Reducción de latencia: Permite que las respuestas del juego sean rápidas, mejorando la experiencia del usuario.

  • Desventajas:

    • Sincronización de la caché: Mantener la coherencia entre los datos en la base de datos y los datos en caché puede ser complejo, especialmente cuando los datos cambian con frecuencia.

9.6. Uso de Question Templates

  • Decisión: Utilizar templates de preguntas para gestionar la estructura y formato de las preguntas del juego.

  • Ventajas:

    • Flexibilidad: Los templates permiten una gestión dinámica de las preguntas, lo que facilita la creación y modificación de preguntas sin necesidad de cambiar el código.

    • Reutilización: Los templates permiten crear diferentes tipos de preguntas basadas en un formato común.

  • Desventajas:

    • Complejidad de implementación: La creación de un sistema dinámico de templates requiere una estructura adicional que puede aumentar la complejidad de la aplicación.

9.7. Uso de i18next para Internacionalización

  • Decisión: Implementar i18next para la internacionalización (i18n) de la aplicación.

  • Ventajas:

    • Soporte de múltiples idiomas: Permite traducir la aplicación a diferentes idiomas sin tener que modificar el código fuente.

    • Facilidad de integración: La biblioteca se integra bien con frameworks como React y tiene una buena documentación.

  • Desventajas:

    • Mantenimiento de archivos de traducción: Es necesario mantener actualizados los archivos de traducción y asegurarse de que se sincronicen correctamente con el desarrollo de la aplicación.

9.8. Uso de WikiData

  • Decisión: Utilizar WikiData como fuente de datos colaborativa y libre.

  • Ventajas:

    • Acceso libre a grandes cantidades de datos: WikiData ofrece una fuente confiable y estructurada de información que puede ser utilizada en múltiples aplicaciones.

    • Actualización constante: WikiData se actualiza regularmente con datos nuevos de diversas fuentes.

  • Desventajas:

    • Calidad y precisión variable: Debido a la naturaleza colaborativa de WikiData, la fiabilidad y precisión de los datos pueden ser inconsistentes, especialmente en áreas donde los usuarios pueden editar libremente.

9.9. Uso de la Plantilla Arc42

  • Decisión: Documentar la arquitectura utilizando la Plantilla Arc42.

  • Ventajas:

    • Estructura clara y completa: Arc42 proporciona una estructura bien definida para documentar la arquitectura del software, facilitando la comprensión y comunicación entre los equipos.

    • Enfoque modular: Ayuda a desglosar la arquitectura en partes manejables y claras.

  • Desventajas:

    • Exceso de detalles: En proyectos más pequeños o simples, la plantilla puede ser más detallada de lo necesario, lo que podría hacer que la documentación sea demasiado compleja y difícil de mantener.

9.10. Microservicios UserService y AuthService con la misma base de datos

  • Decisión: Utilizar la misma base de datos para los microservicios UserService y AuthService.

  • Ventajas:

    • Compartición de datos: Ambos servicios manejan datos relacionados, como información de usuarios y credenciales. Usar la misma base de datos facilita la integración y sincronización entre estos servicios.

    • Reducción de complejidad: Evita la duplicación de datos y facilita las operaciones de lectura/escritura, ya que no es necesario manejar múltiples bases de datos para información similar.

  • Desventajas:

    • Posible acoplamiento: Utilizar la misma base de datos podría generar un acoplamiento no deseado entre los microservicios, lo que podría dificultar su escalabilidad o evolución independiente en el futuro.

9.11. Decisión de empezar el proyecto desde cero

  • Decisión: Decidimos empezar el proyecto desde cero en lugar de reutilizar un proyecto del año pasado.

  • Ventajas:

    • Aprovechamiento de nuevas tecnologías: Comenzar desde cero nos permite adoptar tecnologías más modernas y ajustadas a las necesidades actuales del proyecto.

    • Mejor calidad del código: Empezar de nuevo nos permitió evitar la deuda técnica acumulada en el proyecto anterior y asegurarnos de que la calidad del código sea más alta desde el principio.

  • Desventajas:

    • Mayor tiempo de desarrollo: Empezar de cero llevó más tiempo en comparación con la reutilización de partes del proyecto anterior. Sin embargo, a largo plazo, este enfoque permitirá una mayor flexibilidad y escalabilidad.

9.12. Conclusión

Las decisiones arquitectónicas que se tomaron a lo largo del desarrollo del proyecto han sido cuidadosamente consideradas para garantizar un sistema escalable, eficiente y fácil de mantener. A pesar de que algunos de los miembros del equipo no estaban familiarizados con ciertas tecnologías, como Docker o MongoDB, las decisiones se basaron en las necesidades actuales del proyecto y en las tendencias tecnológicas que ofrecen ventajas a largo plazo. Estas decisiones no solo buscan cumplir con los requisitos inmediatos, sino también permitir un crecimiento sostenible del sistema en el futuro.

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.

Escenario Requisito Objetivo

Esc1

Rendimiento

Mantener el tiempo de respuesta en pocos segundos.

Esc2

Escalabilidad

El sistema debe escalar sin afectar el rendimiento.

Esc3

Seguridad

Implementar medidas de seguridad robustas, incluyendo el bloqueo de acceso tras cinco intentos fallidos, el cifrado de contraseñas y la transmisión segura de información sensible del sistema mediante tokens de sesión ocultos.

Esc4

Mantenibilidad

Modularidad y facilidad de integración.

Esc5

Usabilidad

Debe haber reglas y guías en otro idioma para comprender el sistema, además de una interfaz amigable para el usuario.

10.2. Escenarios de calidad

Id Escenario

Esc1

Un gran número de usuarios accede a la aplicación simultáneamente. El sistema debe mantener en pocos segundos el tiempo de respuesta.

Esc2

Crecimiento del número de usuarios en los primeros meses de lanzamiento de la aplicación. El sistema escala sin afectar al rendimiento. Los tiempos de respuesta siguen siendo lo más cortos posibles.

Esc3

Un usuario malintencionado quiere acceder a datos privados usando un ataque de fuerza bruta en la autenticación. Tras intentarlo cinco veces se le prohíbe acceder a la aplicación.

Esc4

El equipo de desarrollo tiene que añadir una nueva funcionalidad a la aplicación. La funcionalidad debe implementarse sin afectar negativamente a otras áreas del sistema.

Esc5

Un usuario nuevo entra en la aplicación. Este usuario no habla español. Además es la primera vez que accede al sistema, por tanto debe haber un apartado de reglas en su idioma para que entienda que puede hacer en la aplicación.

11. Riesgos y Deuda Técnica

Contenidos

Lista de riesgos y deudas técnicas identificadas, ordenadas por prioridad

Motivación

“La gestión de riesgos es la gestión de proyectos para adultos” (Tim Lister, Atlantic Systems Guild).

Este debería ser tu lema para la detección y evaluación sistemática de riesgos y deudas técnicas en la arquitectura. Esta información será necesaria para los interesados en la gestión (por ejemplo, gerentes de proyecto, propietarios de productos) como parte del análisis general de riesgos y la planificación de medición.

Formato

Lista de riesgos y/o deudas técnicas, probablemente incluyendo medidas sugeridas para minimizar, mitigar o evitar riesgos, o reducir deudas técnicas.

Más Información

Ver Risks and Technical Debt en la documentación arc42.

Riesgo Descripción

Inexperiencia del equipo en diseño arquitectónico y sistemas modulares

El equipo de desarrollo cuenta con experiencia limitada en el diseño de arquitecturas de software y en la implementación de sistemas de gran escala con múltiples módulos interconectados, como los basados en microservicios

Inexperiencia en el uso de Node.js

El equipo de desarrollo cuenta con experiencia limitada en Node.js, lo que puede derivar en dificultades para aplicar buenas prácticas en la arquitectura y seguridad del backend. Esto podría afectar la estabilidad, escalabilidad y mantenimiento del sistema.

Lagunas del LLM

El LLM en ocasiones tiene lagunas y proporciona outputs con información errónea a preguntas largas

Inexperiencia en el uso de Docker y tecnologías de contenedorización

El equipo de desarrollo tiene experiencia limitada en el uso de Docker y tecnologías de contenedorización. Esto puede derivar en configuraciones ineficientes, dificultades en la gestión de contenedores y errores en el despliegue del sistema, afectando la estabilidad y la portabilidad del proyecto.
Deuda Técnica Descripción

Servicio de Autenticación y de Usuarios Comparten Base de Datos

Los microservicios authservice y userservice comparten la misma base de datos pues ambos tienen que acceder a los datos de los usuarios.

Esto implica que los microservicios están más acoplados entre sí, ya que comparten el acceso a la base de datos. Debido a esto, podrían volverse más difíciles de escalar a medida que la aplicación crece.

Para evitar problemas en este aspecto trataremos de mantener una clara separación de responsabilidades entre los servicios, asegurándonos de que cada servicio solo modifique los datos que le corresponden

12. Glosario

Contenido

Los términos técnicos y de dominio más importantes que utilizan tus stakeholders al hablar del sistema.

También puedes usar el glosario como fuente de traducciones si trabajas en equipos multilingües.

Motivación

Debes definir claramente tus términos para que todos los stakeholders:

  • tengan una comprensión idéntica de estos términos

  • no utilicen sinónimos ni homónimos

Formato

Una tabla con las columnas <Término> y <Definición>.

Se pueden agregar más columnas si necesitas traducciones.

Información adicional

Consulta Glossary en la documentación de arc42.

Term Definition

LLM (Modelo Largo de Lenguaje)

Modelo de inteligencia artificial, conversacional en el caso de este proyecto, que recibe un input, lo procesa y, en base a una serie de instrucciones e información de la cual dispone con anterioridad, ofrece un output al usuario

API (Interfaz de Programación de Aplicaciones)

Conjunto de reglas y herramientas que permiten que diferentes programas o sistemas se comuniquen entre sí. Es como un "mensajero" que recibe solicitudes, las envía al sistema adecuado y devuelve la respuesta

Wikidata

Base de conocimiento libre y abierta que puede ser leída y editada tanto por humanos como por máquinas. Es utilizada como fuente de información para la generación de las preguntas en el sistema

SPARQL

Lenguaje de consulta diseñado para interactuar con bases de datos que utilizan el modelo RDF (Resource Description Framework), en nuestro caso utilizado para hacer consultas a Wikidata

Git

Sistema de control de versiones que permite rastrear cambios en el código, colaborar con otros desarrolladores y gestionar diferentes versiones de un proyecto. Funciona como un "historial" que guarda cada modificación, facilitando la recuperación de versiones anteriores y el trabajo en equipo sin sobrescribir el trabajo de otros

Github

Plataforma en la nube que permite almacenar, compartir y colaborar en proyectos que usan Git. Facilita el trabajo en equipo mediante herramientas para gestión de código, control de versiones, seguimiento de problemas y automatización de tareas

REST

Estilo de arquitectura para diseñar servicios web que permite la comunicación entre sistemas a través de Internet. Usa peticiones HTTP (como GET, POST, PUT, DELETE) para intercambiar datos

React

Biblioteca de JavaScript para construir interfaces de usuario interactivas y dinámicas

MongoDB

Sistema de gestión de bases de datos no relacional basado en documentos. Almacena la información de los datos en documentos en formato BSON (Binary JSON)

Microservicio

Componente autónomo y desacoplado de una aplicación más grande. Cada microservicio tiene una responsabilidad única y puede ser desarrollado, desplegado y escalado de manera independiente. Estos servicios se comunican entre sí a través de interfaces bien definidas, generalmente usando protocolos ligeros como HTTP o mensajería asíncrona

Docker

Plataforma de código abierto que permite automatizar el despliegue, la ejecución y la gestión de aplicaciones dentro de contenedores. Los contenedores son entornos aislados y ligeros que permiten ejecutar aplicaciones de manera consistente, independientemente del entorno en el que se encuentren, ya sea en un servidor local, en la nube o en diferentes sistemas operativos

Terraform

Herramienta de infraestructura como código (IaC) de código abierto que permite definir, provisionar y gestionar infraestructuras a través de archivos de configuración escritos en un lenguaje declarativo llamado HCL (HashiCorp Configuration Language). Lo utilizamos para describir de manera codificada los recuross necesarios para nuestro despliegue en AWS.