About arc42
arc42, the template for documentation of software and system architecture.
Template Version 8.2 EN. (based upon AsciiDoc version), February 2025
Created, maintained and © by Dr. Peter Hruschka, Dr. Gernot Starke and contributors. See https://arc42.org.
1. Introducción y Objetivos
El proyecto WIChat es una iniciativa llevada a cabo en la Universidad de Oviedo, bajo la solicitud de la empresa de desarrollo de software ChattySW y contratada por RTVE, con el propósito de desarrollar una versión online del concurso de preguntas y respuestas "Saber y Ganar".
El equipo comprometido con este desarrollo está formado por:
-
Bruno Isla Sierra
-
Guillermo Villacorta Moro
-
Jorge Blanco Sánchez
-
Marcelo Díez Domínguez
-
Pablo Urones Clavera
En la aplicación, los usuarios podrán registrarse y participar en un juego de preguntas. Dicho juego consistirá en que la aplicación mostrará una imagen y los jugadores deberán adivinar preguntas sobre el lugar representado. Como novedad de la aplicación, se ofrecerá la posibilidad de obtener pistas sobre la imagen mediante una conversación con un chatbot.
1.1. Descripción de los requisitos
-
Los usuarios deberán registrarse en la aplicación para jugar, o bien iniciar sesión en una cuenta ya existente.
-
Los usuarios registrados podrán acceder a un historial de su participación.
-
La información de las preguntas será generada por el sistema automáticamente basándose en datos extraídos de Wikidata.
-
Cada una de las preguntas tendrá 4 respuestas posibles, siendo solo una respuesta correcta y el resto distractoras o incorrectas.
-
Los usuarios contarán con un plazo de tiempo determinado para responder las preguntas.
1.2. Objetivos de calidad
| Objetivo de calidad | Descripción |
|---|---|
Rendimiento |
Se buscará que los tiempos de espera de la aplicación sean reducidos, para que el usuario pueda disfrutar de una experiencia fluida y con las mínimas interrupciones posibles. |
Testeabilidad |
Nuestra aplicación podrá ser testeable, es decir, estará sometida a una serie de pruebas que realizaremos para garantizar el correcto funcionamiento del sistema. También nos ayudará a identificar errores y solucionarlos. |
Usabilidad |
La aplicación deberá ser intuitiva y fácil de usar, para que cualquier usuario pueda disfrutar de la experiencia sin necesidad de instrucciones previas. El ojetivo es que el usuario pueda navegar sin dificultades y se sienta cómodo en la aplicación. |
Mantenibilidad |
Se tratará de cuidar la arquitectura de la aplicación para futuras nuevas implementaciones, modificaciones o correcciones. Se buscará que el código sea limpio y fácil de entender, para que cualquier miembro del equipo pueda trabajar en él. También se revisará periódicamente la documentación para mantenerla actualizada. |
1.3. Partes interesadas (Stakeholders)
| Rol/Nombre | Contacto | Expectativas |
|---|---|---|
Equipo de desarrollo (Estudiantes) |
Bruno Isla Sierra, Guillermo Villacorta Moro, Jorge Blanco Sánchez, Marcelo Díez Domínguez, Pablo Urones Clavera |
Desarrollar un sistema de preguntas y respuestas, mejorando sus habilidades de programación, desarrollo y trabajo en equipo. |
Usuarios |
Cualquier usuario de la aplicación |
Participar en una aplicación intuitiva y fácil de usar/entender. |
Profesores |
Jose Emilio Labra Gayo, Pablo González, Irene Cid Rico |
Evaluar el resultado final de la aplicación, además de ayudar a los estudiantes con el desarrollo de la aplicación. |
RTVE |
Radiotelevisión Española |
Cumplimiento de los requisitos establecidos para presentar la aplicación a sus espectadores. |
2. Restricciones arquitectónicas
En este apartado se enumerarán y describirán brevemente las restricciones que condicionan las decisiones arquitectónicas de la aplicación. Se debe tener en cuenta que, aunque no todas tienen la misma importancia, todas condicionan en menor o mayor medida la arquitectura o forma final que tendrá el proyecto.
2.1. Restricciones técnicas y estructurales
Restricción |
Descripción |
Documentación |
La documentación del proyecto debe realizarse utilizando la plantilla Arc42. |
Control de versiones |
El control de versiones se realizará mediante Git y se alojará en GitHub. |
Host |
La aplicación será desplegada en un host de Docker. |
API |
Se utilizará una API de WikiData para obtener información a la hora de generar preguntas (distintas fotografías) y respuestas. |
2.2. Restricciones organizativas y de proceso
Gestión de tareas |
Se utilizará la funcionalidad de Github "Github Issues" para asignar y gestionar las tareas de cada miembro del equipo. |
Reuniones de equipo |
Se realizará por lo menos una reunión semanal durante las horas de clase, en nuestro caso los martes de 9 a 11 a.m. en la Escuela de Ingeniería Informática. Además, reuniones extras se podrán llevar a cabo cuando se estime necesario, de forma tanto presencial como telemática. |
Control de decisiones |
En cada reunión, un miembro (el cual se irá rotando) rellenará un acta en el que se recogerán las decisiones tomadas, así como cualquier otra información que sea relevante. |
División de ramas |
Cada componente del equipo trabajará en una rama propia, la cual se fusionará con la rama develop una vez se haya completado la tarea asignada, y con la rama master una vez se vaya a lanzar una nueva versión revisada de la aplicación. |
3. Contexto y Alcance
3.1. Contexto Empresarial
WIChat es una aplicación web desarrollada por la empresa ChattySw para RTVE con el propósito de modernizar y ampliar la experiencia de juego en línea basada en concursos de preguntas y respuestas. La aplicación se inspira en el formato televisivo de "Saber y Ganar", proporcionando una plataforma interactiva donde los usuarios deben identificar lugares a partir de imágenes generadas automáticamente desde Wikidata.
El sistema añade una innovación clave respecto a versiones anteriores al integrar un modelo de lenguaje (LLM) que permite a los jugadores obtener pistas conversacionales sobre las imágenes, mejorando así la experiencia de usuario.
Los principales objetivos comerciales de WIChat son:
-
Mejorar la experiencia de los usuarios: Ofreciendo una plataforma de aprendizaje interactivo y entretenido.
-
Fomentar la participación: Incentivar a los jugadores mediante recompensas por respuestas correctas y rankings competitivos.
-
Expandir la accesibilidad y el alcance del juego: Implementando internacionalización y soporte para múltiples idiomas.
-
Aprovechar tecnologías de inteligencia artificial: Generando automáticamente preguntas, respuestas y pistas basadas en datos estructurados.
3.2. Contexto tecnico
WIChat es una aplicación web compuesta por diversos módulos y tecnologías que permiten su funcionamiento fluido y escalable. La arquitectura se basa en un enfoque de microservicios, con integración de APIs para la generación de preguntas y el procesamiento de lenguaje natural.
Componentes principales:
-
Frontend Web: Desarrollado con tecnologías modernas siendo está React.js para garantizar una interfaz interactiva y dinámica.
-
Backend:
API RESTful para gestionar autenticación, preguntas y estadísticas de los usuarios.
Integración con una base de datos para almacenamiento de información.
-
Módulo de generación de preguntas:
Obtiene datos desde Wikidata.
Genera preguntas y respuestas (correctas e incorrectas) automáticamente.
-
Sistema de pistas conversacionales:
Implementado con un modelo de lenguaje grande (LLM) accesible vía API.
-
Gestión de usuarios:
Registro e inicio de sesión mediante OAuth o autenticación tradicional.
-
Despliegue y monitoreo:
Infraestructura basada en contenedores Docker para escalabilidad.
Integración con herramientas de CI/CD de GitHub para automatización del despliegue de documentanción y Microsoft Azure para despliegue de la Apliación.
Este enfoque técnico garantiza que WIChat sea una plataforma robusta, escalable y fácil de mantener, alineada con los requisitos del proyecto.
4. Estrategia de solución
4.1. Decisiones tecnológicas
-
Git: Sistema de control de versiones.
-
GitHub: Servicio basado en la nube que aloja el sistema de control de versiones, Git.
-
JavaScript: Lenguaje de programación interpretado, dialecto del estándar ECMAScript. Se utiliza para crear páginas web dinámicas.
-
React: Biblioteca de JavaScript para construir interfaces de usuario.
-
Node.js: Entorno de ejecución para JavaScript en el servidor, con alto rendimiento y velocidad, ideal para aplicaciones en tiempo real.
-
CSS: Lenguaje de programación gráfico orientado a definir la representación de un documento.
-
MongoDB: Sistema de bases de datos no relacional, orientada a documentos.
-
Wikidata: Base de datos libre, colaborativa y multilingüe que se usara para sacar información para las preguntas.
-
Modelo largo de lenguaje (LLM): modelo de inteligencia artificial basado en aprendizaje profundo, diseñado para procesar y generar texto en lenguaje natural.
-
Docker: se utiliza para hacer el despliegue de la aplicación.
-
Maquina Virtual: por decidir
4.2. Decisiones sobre cómo alcanzar los objetivos clave de calidad
-
Rendimiento: Se buscará minimizar los tiempos de procesamiento de datos y tareas, para así mejorar la experiencia del usuario.
-
Testeabilidad: El equipo testeará la aplicación manual y automáticamente mediante pruebas de cobertura (unitarias e integración), pruebas de aceptación (e2e) y pruebas de carga.
-
Usabilidad: La aplicación será clara, intuitiva y familiar para el usuario.
-
Mantenibilidad: La aplicación será mantenible gracias al diseño por componentes, lo que nos permitirá tener un código con baja acoplamiento y alta mucha cohesión, ayudándonos a que realizar cambios sea más sencillo y rápido. La documentación se revisará para tenerla actualizada.
4.3. Decisiones organizativas relevantes
-
Los miembros del equipo mantenemos comunicación a través de WhatsApp y Discord para las dudas que surjan u otras decisiones que haya que tomar entre todos los miembros del equipo.
-
Se realizan reuniones semanales en las que se expone el trabajo realizado, si alguno ha tenido algún problema y se revisarán las tareas que tiene cada miembro del equipo.
-
Utilizamos un tablero Kanban dentro de GitHub para organizar las tareas que cada miembro del equipo tiene que realizar/está realizando.
5. Vista de Bloques
La vista por bloques muestra como se descompone el contexto general del sistema en diferentes bloques, los cuales representan los diversos aspectos de la aplicación. De esta forma se obtiene una imagen visual y clara tanto del sistema como de su interior.
5.1. Sistema General Whitebox
- Motivación
-
WIChat es la estructura general del sistema, donde los usuarios se registran, participan en el juego o visualizan su historial de partidas, entre otras funcionalidades.
| Actores | Descripción |
|---|---|
Usuario |
Cliente/Usuario de la aplicación que interactúa con ella. |
WIChat |
Sistema desarrollado para el uso de los espectadores/usuarios. |
Wikidata |
API que genera la información de las preguntas y la proporciona al sistema. |
5.2. Nivel 2
- Motivación
-
Muestra el funcionamiento interno de la aplicación y el flujo de datos entre la WebApp, los Microservicios, la Base de Datos y Wikidata.
| Actores | Descripción |
|---|---|
Usuario |
Cliente/Usuario de la aplicación que interactúa con ella. |
WIChat |
Sistema desarrollado para el uso de los espectadores/usuarios. |
WebApp |
Contiene la interfaz de usuario y la rama de desarrollo (frontend y backend respectivamente). |
Microservicios |
Servicios que se encargan de las funcionalidades del sistema. |
Base de Datos |
Base de datos que almacena la información sobre los usuarios y las preguntas. |
Wikidata |
API que genera la información de las preguntas y la proporciona al sistema. |
5.3. Nivel 3
- Motivación
-
Muestra el funcionamiento interno de la aplicación y el flujo de datos entre la WebApp, los Microservicios, la Base de Datos y Wikidata.
| Actores | Descripción |
|---|---|
Usuario |
Cliente/Usuario de la aplicación que interactúa con ella. |
WIChat |
Sistema desarrollado para el uso de los espectadores/usuarios. |
WebApp |
Contiene la interfaz de usuario y la rama de desarrollo (frontend y backend respectivamente). |
Microservicios |
Servicios que se encargan de las funcionalidades del sistema. |
AuthService |
Gestiona la autenticación de usuarios (inicio de sesión). |
UserService |
Gestiona la creación de nuevos usuarios. |
HistoryService |
Gestiona el historial de los usuarios. |
QuestionService |
Gestiona la creación de las preguntas. |
Base de Datos |
Base de datos que almacena la información sobre los usuarios y las preguntas. |
Wikidata |
API que genera la información de las preguntas y la proporciona al sistema. |
6. Vista de ejecución
En el diagrama anterior se muestra como un usuario válido, interactúa con la aplicación.
Tras iniciar sesión la aplicación genera una pregunta con su imagen correspondiente y se la mostrará al usuario. El usuario podrá responder a la pregunta, haciendo uso o no del LLM, y una vez que responda la pregunta, la aplicación le mostrará si la respuesta fue correcta o no.
7. Vista de despliegue
- Motivación
-
El objetivo de la vista de despliegue es conocer cómo el producto software se distribuye sobre la infraestructura hardware. Siendo importante conocer su vista por los siguientes motivos:
-
Facilitar la identificación de posibles cuellos de botella y puntos de fallo.
-
Proveer una base para la planificación de la capacidad y la escalabilidad.
-
Ayudar en la resolución de problemas y en el mantenimiento del sistema.
-
- Mapeo de los servicios a la infraestructura
-
- Servicios API de terceros
-
-
WIKIDATA API: Servidor API externo que provee información gráfica para las preguntas.
-
LLM: Chat Bot que ofrece ayuda al usuario.
-
- Servicios de la aplicación en servidor propio
-
-
Authentication Service: Valida que el usuario esté autenticado.
-
User Service: Provee información de los usuarios.
-
Questions Generator Service: Genera preguntas para el usuario.
-
History Service: Guarda el historial de preguntas del usuario.
-
Database: Base de datos que almacena la información de los usuarios y las preguntas.
-
- Servicio en el cliente
-
-
Web Browser: Interfaz de usuario que permite la interacción del usuario con el sistema.
-
8. Conceptos transversales
8.1. Gestión de Proyecto
-
Metodología de desarrollo
Se utilizara una metodología agil en el proyecto intentando seguir scrum de la mejor manera posible.
-
Tareas y proridades
Las tareas y prioridades se gestionaran mediante la una planificación en GitHub y se recogeran en un acta durante cada reunion semanal.
8.2. Arquitectura y patrones de diseño
El proyecto sigue una arquitectura de microservicios, que es un patrón de diseño el cual estructura una aplicación como una colección de servicios acoplados de manera flexible. Esto hace que la aplicación sea más escalable y fácil de mantener.
…
8.3. Libreria ChatBotify
Libreria encargada de la gestion del chatbot, se encargara de la gestion de las peticiones del usuario y respuestas del chatbot.
8.4. Modelo de dominio
Se desarrollara segun la aplicación avance
9. Decisiones arquitectónicas
En este apartado se tratarán de justificar las decisiones relacionadas con la arquitectura de la aplicación, de una forma en la que se pueda comprender el porqué de cada una de ellas desde el punto de vista de cualquier usuario.
Decisión |
Justificación |
Git para el control de versiones |
Escogemos Git como sistema de control de versiones por ser la principal opción en el mercado y por ser un sistema de control de versiones distribuido, lo que nos permite trabajar de forma más eficiente y simple. |
GitHub para gestión de código compartido en la nube |
Se trata del servicio Git basado en la nube más popular y con más funcionalidades, lo que nos permite tener un control total sobre los cambios de nuestra aplicación, además de tener la seguridad de que no vamos a perder ni una línea de código, aunque esta se sobreescriba en algún momento. |
Utilización de JavaScript |
La mayor parte de integrantes del grupo tiene experiencia previa en este lenguaje, por lo que se conoce la versatilidad y utilidad de este lenguaje para el desarrollo de aplicaciones web. |
BD con MongoDB |
Es una de las principales soluciones del mercado, y ha sido elegida por su facilidad de uso y por la previa experiencia de alguno de los componentes con esta base de datos. |
Despliegue con Node.js |
Se ha escogido por ser un entorno de ejecución para JavaScript en el servidor, con alto rendimiento y velocidad, ideal para aplicaciones web en tiempo real como la que nos concierne. |
Desarrollo con React |
Se ha escogido por ser una de las opciones más populares a la hora de desarrollar JavaScript con interfaces de usuario. |
Wikidata para la obtención de información |
Esta era una opción clara por ser una base de datos libre, colaborativa y multilingüe, con la que conseguir la información para las diferentes preguntas será muy sencillo. |
Uso de la LLM de Empathy |
Se utilizará la LLM de Empathy para poder generar respuestas en tiempo real con el chatbot de inteligencia artificial que se implementará en la aplicación. |
10. Requisitos de calidad
10.1. Árbol de calidad
10.2. Escenarios de calidad
Requisito de calidad |
Escenario de calidad |
Prioridad |
Rendimiento |
Los tiempos de espera o respuesta de la aplicación sean reducidos, para que el usuario pueda disfrutar de una experiencia fluida y con las mínimas interrupciones posibles. Se buscará que los tiempos sean no superirores a 1 segundo. |
Medio |
Testeabilidad |
Nuestra aplicación podrá ser testeable, es decir, estará sometida a una serie de pruebas que realizaremos para garantizar el correcto funcionamiento del sistema. El 80% del código tendrá cobertura con pruebas unitarias exitosas. También nos ayudará a identificar errores y solucionarlos. |
Medio-Alto |
Usabilidad |
La aplicación deberá ser intuitiva y fácil de usar, para que cualquier usuario pueda disfrutar de la experiencia sin necesidad de instrucciones previas. Se usarán paletas de colores aptas para daltónicos. El ojetivo es que el usuario pueda navegar sin dificultades y se sienta cómodo en la aplicación. Registrase como nuevo usuario será un proceso sencillo y rápido que no requerirá más de 1 minuto. |
Alto |
Mantenibilidad |
Se tratará de cuidar la arquitectura de la aplicación para futuras nuevas implementaciones, modificaciones o correcciones. Se buscará que el código sea limpio y fácil de entender, para que cualquier miembro del equipo pueda trabajar en él. También se revisará periódicamente la documentación para mantenerla actualizada. Se puede añadir una funcionalidad sin modificar más del 10% del código. |
Medio-Alto |
11. Riesgos y Deuda Técnica
11.1. Riesgos
| Riesgo | Descripción | Prioridad |
|---|---|---|
Dependencia de Wikidata |
Si la API de Wikidata falla o se vuelve inestable, la generación de preguntas podría paralizarse y verse afectado el sistema. |
Alta |
Generación incorrecta de pistas |
Las "alucinaciones" del modelo de lenguaje pueden generar pistas confusas en el chatbot, afectando a la experiencia del usuario. |
Alta |
Rendimiento y escalabilidad |
Los tiempos de respuesta y la capacidad para manejar múltiples usuarios simultáneos podrían verse afectados en caso de que el sistema no esté bien optimizado. |
Alta |
Seguridad |
Si el sistema de registro y la API no están bien protegidos, podría haber riesgos de acceso no autorizado a datos sensibles de los usuarios. |
Alta |
Falta de pruebas |
Si no se implementan las pruebas adecuadas entre el frontend, backend y la API externa, podrían surgir errores no detectados. |
Media |
Desactualización de datos |
Si los datos de Wikidata no se actualizan regularmente, las preguntas podrían volverse confusas o imprecisas con el tiempo. |
Baja |
… |
… |
… |
11.2. Deuda Técnica
| Deuda Técnica | Descripción |
|---|---|
… |
… |
12. Glosario
| Término | Definición |
|---|---|
API |
Application Programming Interface. Conjunto de reglas y especificaciones que las aplicaciones pueden usar para comunicarse entre sí. |
LLM |
Large Language Model. Es un modelo de IA poderoso que aprende del lenguaje humano y puede usarse en diversas aplicaciones para generar y comprender texto. |