1. Introduction and Objectives

1.1. Requirements Summary

WIChat is an enhanced version of the experimental quiz application developed last year by HappySw for RTVE. The main improvement is the incorporation of a chatbot powered by a large language model (LLM), allowing contestants to interact and receive hints during the game. The application automatically generates questions and images using data from Wikidata, offering a wide variety of topics and visual content. It also includes features such as user registration, individual game rankings, global rankings among all users, options to modify account data, and display of general user information. All of this makes the game more engaging and personalized. WIChat is a web platform designed to be scalable, flexible, and easy to maintain, providing an interactive, fun, and educational experience for users.

1.2. Essential Functional Requirements

  • User Registration and Authentication:

    • Users can create accounts and log in to participate in the quiz.

  • Question and Answer Game:

    • Menu to select the type of question and the maximum response time per question.

    • Display of images to contestants, who must guess the place or topic shown.

    • Inclusion of image-related questions within the chatbot.

    • Users are rewarded for each correct answer.

  • Interactive Hint Functionality:

    • Users can request hints about the answers through conversational interaction.

    • Hints will be generated by an external large language model (LLM).

  • Automatic Content Generation:

    • Images and hints will be automatically generated using data retrieved from Wikidata.

  • Global Ranking System:

    • Users can view their position in the global ranking.

    • The ranking displays percentage of correct answers, total time spent per game, email, game number within the ranking, and date and time of the game.

    • Data is sorted from highest to lowest based on the percentage of correct answers; in case of a tie, the total time spent determines the ranking.

  • Personal Ranking System:

    • Users can view all their played games in a personal ranking displayed in the home menu.

    • The personal ranking displays the number of correct and incorrect answers, total time spent per game, and the date and time of each game.

    • Data is sorted from highest to lowest based on the number of correct answers; in case of a tie, the total time spent determines the ranking.

    • Unlike the global ranking, the personal ranking does not display the user’s email, as it is not relevant since it only includes their own games.

    • Clicking on a game result opens a pop-up showing the list of questions for that game, including the number of correct and incorrect answers and the total time spent. Clicking on each question opens a pop-up showing the question and the correct answer; if the user answered incorrectly, the wrong answer will also be displayed.

  • Personal Account Management Section:

    • Users can change their password from the personal account management menu.

    • Users can view their personal data as well as general statistics from all their played games.

    • They can also view a graph displaying the results of their last 10 games; hovering over each point shows the specific data for each game. The Y-axis represents the percentage of correct answers per game.

  • Administrator Menu:

    • Administrators can view the list of users registered in the application.

    • For each registered user, their email and username are displayed.

    • Administrators can delete non-admin users via a delete button shown next to each user’s email.

  • Frequently Asked Questions:

    • Users can access a FAQ section explaining how the application works and how to use it.

    • This option will be available within the Help section in the navigation menu.

1.3. Main Drivers

  • Improvement of User Interaction:

    • The inclusion of conversational hints aims to increase user engagement and participation.

  • Content Automation:

    • Automatic generation of images and hints reduces manual work and helps keep the content updated and diverse.

  • Alignment with Modern Technologies:

    • Integrating an LLM and using Wikidata places the application at the forefront of technology, which is key for RTVE as an innovative public entity.

  • User Experience:

    • Aiming for greater user involvement and interaction with the application through new, highly useful and interesting functionalities.

1.4. Motivation

From the end-user’s perspective, the WIChat system is designed to enhance the experience of participants in the "Saber y Ganar" program. The main goal of modifying the system is to increase participant interaction by allowing them to obtain hints conversationally through an external large language model (LLM). This enriches the gaming experience and facilitates participation by offering "assistance" via the chatbot.

The system is designed to provide better support to players through hints generated by the chatbot, while also improving the overall game quality by integrating advanced technology for automatic generation of images and hints based on Wikidata data. This ensures the content is relevant, updated, and non-repetitive, providing users with a richer and more engaging experience.

1.5. Quality Objectives

Quality Objective Specific Scenario

High Availability

The system must be available 24/7 with minimal downtime for maintenance.

Scalability

The architecture must allow adding more servers without service interruption, efficiently handling traffic spikes during high demand periods.

Security

The application must ensure the protection of user data, especially passwords, during registration and login processes.

Performance

The response time to display a question and its options must be less than 2 seconds.

Integration with Wikidata

Images and hints must be correctly generated from Wikidata data without errors.

Usability

The user interface must be intuitive, with clear instructions on how to participate and request hints.

1.6. WIChat System Stakeholders

  1. End Users:

    • 1.1. Role: Contestants.

      • Responsibility: Understand the basic architecture of the game to interact with questions, hints, and functionalities of the application. No deep technical knowledge is required.

    • 1.2. Role: System Administrators.

      • Responsibility: Understand the architecture to manage system maintenance and security, perform deployments, and monitor performance. They must also manage the user administration menu, being able to delete users who are not administrators.

  2. Software Developers:

    • Role: Frontend and backend developers.

    • Responsibility: Understand the architecture in depth to implement system functionalities such as image generation and chatbot hint integration.

  3. Software Architects:

    • Role: Technical architects responsible for the system’s infrastructure.

    • Responsibility: Have a deep understanding of the architecture and make key decisions on system scalability, security, and modularity.

  4. Testers:

    • Role: Responsible for ensuring system quality.

    • Responsibility: Understand the architecture and work organization to ensure the game operates correctly and images and hints are properly generated.

Table 1. Project Stakeholders
Role/Name Contact Expectations

Software developers, architects, and testers

Daniel Alberto Alonso Fernández
David Álvarez Cabezas
Alejandro Fernández García
Mario García Prieto

Collaborate effectively throughout all stages of the project, ensuring clean and maintainable code. Focus on scalability, performance, and integration of external systems. Perform thorough and automated testing. Document and share design decisions and best practices.

Client

Radio Televisión Española (RTVE)

Expect a stable and appealing web solution that increases user participation and provides an entertaining and interactive gaming experience.

ChattySW (Development Company)

Internal development team of ChattySW

Deliver a robust and interactive application that integrates AI-based hints for the game. Ensure availability, performance, and security. Maintain clear communication with RTVE and meet project deadlines.

System Administrator

IT team responsible for system maintenance

Ensure system uptime, security, and performance. Manage deployments, monitor server load, and provide technical support. Also manage application users and their permissions.

Regular User (Player)

People who register and participate in the quiz

Participate in the game by answering image-based questions and using the conversational hint system. Provide feedback on usability and user experience.

2. Architecture Constraints

2.1. Technical constraints

Name Description

FrontEnd

The system shall have at least one frontend for user interaction.

Question Generation

Questions should be generated automatically from wikidata.

User Management

The system shall have a user management system that allows for login, registration, and historical consultation.

LLM

We will use an LLM for hint generation based on an image that we will send.

Deployment

We will use docker for local deployment.

Monitoring and Metrics

The system shall include monitoring and metrics collection using Prometheus and Grafana to ensure system reliability and performance.

2.2. Organizational constraints

Name Description

Github

We will use github to host the project repository, from which each member will work on a branch for their implementations.

Class Meetings

For the meetings we will use the classrooms to meet and discuss the work to be done and the work we have done during the week. There is also a whatsapp group where we will communicate with each other in case we need to meet outside the classroom.

2.3. Convention Constraints

Name Description

Project documentation

We will use the Arc42 template for the documentation which will be written in English in its entirety.

Code Reviews

All code changes must go through a pull request and be reviewed by at least one team member before merging into the main branch.

3. Context and Scope

3.1. Business Context

Communication Partner Inputs Outputs

Users

User requests and interactions.

Responses and hints (chatbot clues).

Web Application

Receives user inputs and data from backend services.

Updates the interface to display information to the user.

Backend Service

Processes user actions through the web application and data returned from external APIs.

Manages API calls and updates the web application view.

Chatbot

User queries (text input).

Hints and suggestions (text output).

Database

Stored game data.

Game state, user progress, stored results.

Wikidata

Receives queries about a topic or category.

Returns a page corresponding to the given query.

LLM (Large Language Model)

Receives relevant information about the question the user needs to answer.

Interacts or provides answers to the user in different ways, depending on the wildcard used.

3.1.1. Communication Partners:

  • Users:

    • End users interact with the system through the chatbot and other game features. They are provided hints during gameplay.

  • Web Application:

    • The web application acts as the user interface and manages the presentation of the game, including the display of questions, answers, and interactions with other system components.

  • Backend Service:

    • This service processes user actions, manages the game state, communicates with external services (such as Wikidata and the LLM), and provides necessary data to the web application.

  • Chatbot:

    • The chatbot serves as a conversational interface for user interactions. It receives inputs in the form of questions or commands and generates responses that may include hints or additional information.

  • Database:

    • The database stores all relevant game information, such as the game state, user progress, and historical results.

  • Wikidata:

    • An external data source accessed by the backend service to retrieve knowledge and information via SPARQL queries, helping to generate trivia questions and provide context.

  • LLM (Large Language Model):

    • A complex model that processes user queries and generates answers or hints, adapting based on the wildcards used in the game.

3.2. Technical Context

Communication Partner Explanation

Web Application

The user plays the game over the internet, connecting to the system via HTTP requests.

Backend Service

Manages game data, processes user actions, communicates with LLMs to provide hints, and generates trivia questions by calling external APIs.

Database

Stores user data, including player profiles, scores, and game progress.

Wikidata

The backend service retrieves data from Wikidata using SPARQL queries, providing general knowledge and information for the game.

LLM (Large Language Model)

Used to process user questions and provide relevant hints, ensuring dynamic and meaningful interactions in the game.

Azure Cloud

Used for deploying the application, ensuring system scalability, security, and availability.

Web Browsers

Allow users to access the game once deployed, supporting various browsers.

React, JavaScript, HTML, CSS

Technologies used for the frontend development of the game, providing an interactive and responsive user interface.

GitHub CI/CD

Tool used for continuous integration and delivery, enabling automatic deployment of code changes and version management. It also allows automation of tests and the deployment of project documentation.

REST API

A tool used to access various application data through HTTP requests. The responses return a JSON file containing the requested information.

Jest

Testing framework used for performing unit and integration tests in the code, ensuring its quality and functionality.

Gatling

Technology used to perform load and performance testing, ensuring that the application can handle multiple users simultaneously.

  • Web Application:

    • The game is played over the internet. Users connect to the system via HTTP requests, allowing access through web browsers.

  • Backend Service:

    • This service manages all game-related data. It processes user actions, generates trivia questions, and interacts with the Large Language Model (LLM) to provide hints. It also makes calls to external APIs to retrieve additional data for the game.

  • Database:

    • The database stores critical data such as user profiles, scores, and game progress, ensuring persistent storage and retrieval of this information.

  • Wikidata:

    • The backend service retrieves knowledge from Wikidata using SPARQL queries, which is used to create trivia questions and provide context for the game.

  • LLM (Large Language Model):

    • The LLM processes user questions and generates relevant hints or answers, allowing dynamic and intelligent interactions based on user inputs.

  • Azure Cloud:

    • Azure Cloud is used for deploying the application, ensuring that the system is scalable, secure, and highly available.

  • Web Browsers:

    • Web browsers serve as the platform for accessing the game, allowing users to interact with it from a variety of devices.

  • React, JavaScript, HTML, CSS:

    • These technologies are used to develop the game’s frontend. React builds the interactive user interface, while JavaScript, HTML, and CSS manage the layout, functionality, and styling of the game’s web pages.

4. Solution Strategy

4.1. Technology Decisions

For the implementation of WiChat, we have selected the following technologies based on their ease of development, scalability, and compatibility with the project requirements:

  • Version Control: Git – Distributed version control system that facilitates secure and collaborative source code management.

  • Repository Hosting: GitHub – Cloud-based platform for hosting and managing Git repositories, used for team collaboration, continuous integration, and automated deployment.

  • CI/CD Automation: GitHub Actions – Continuous Integration and Continuous Delivery (CI/CD) service used to automate testing, Docker image builds, and deployments to production environments.

  • Code Quality: SonarCloud – Continuous code quality analysis platform that detects bugs, vulnerabilities, code smells, and calculates test coverage to maintain high development standards.

  • Programming Language: JavaScript – Dynamic programming language used on both frontend and backend to build interactive web applications.

  • Frontend Library: React.js – JavaScript library focused on building efficient, modular, and interactive user interfaces on the frontend.

  • Styling Framework: CSS with Tailwind – Utility-first CSS framework for quickly building modern, responsive, and highly customizable interfaces.

  • Runtime Environment: Node.js – JavaScript runtime environment for server-side development, ideal for creating fast, scalable, and real-time backend services.

  • Web Framework: Express – Minimalist Node.js framework that simplifies the creation of RESTful APIs and the management of routes and middleware in the backend.

  • ODM Library: Mongoose – Object Data Modeling (ODM) library for MongoDB that provides a structured layer to define schemas and data models in Node.js.

  • Authentication: JWT (JSON Web Tokens) – Token-based secure authentication standard used to manage user sessions without the need for server-side state.

  • Language Model: Google Gemini (LLM) – Language model developed by Google to generate intelligent and personalized responses in chatbot interactions.

  • Knowledge Base: Wikidata – Open, structured knowledge base that provides semantic data used to dynamically enrich game questions.

  • Testing Tool: Puppeteer – Browser automation tool used to perform end-to-end testing of the application.

  • BDD Framework: Cucumber – Behavior-Driven Development (BDD) testing framework used with Puppeteer to describe and run natural language test scenarios.

  • Testing Framework: Jest – JavaScript testing framework used to perform unit and integration tests across various system services.

  • Load Testing: Gatling – Load testing tool that simulates multiple concurrent users to analyze the performance and scalability of backend services.

  • Containerization: Docker – Container platform that packages applications along with their dependencies, ensuring consistent deployments across environments.

  • Cloud Platform: Azure – Cloud services platform where the virtual machines hosting the system’s container deployments are located.

4.2. Top-Level System Decomposition

The system follows a frontend + dedicated backend architecture, where all business logic is managed by a Node.js backend instead of serverless functions.

  1. Presentation Layer (Frontend - React)

    • Implemented in React with TypeScript, providing an interactive experience.

    • Communicates with the backend via HTTP requests to the Node.js API.

  2. Business Logic Layer (Backend - Node.js & Express)

    • Manages question generation, answer validation, and data storage.

    • Connects to Wikidata to retrieve questions and answers.

    • Handles user authentication with JWT, generating and validating tokens.

4.3. Architectural Patterns

The system effectively implements the following architectural patterns:

  • Microservices Architecture:

    • The backend is divided into multiple microservices, each responsible for a specific business domain (user management, authentication, game logic, communication with the LLM).

    • Each service is independent, enabling scalability, easier maintenance, and separate deployment of components.

  • API Gateway Pattern:

    • The Gateway Service centralizes all frontend requests and routes them to the appropriate microservices.

    • It handles request routing, JWT token validation, and protection of internal services.

  • RESTful API Design:

    • The microservices expose RESTful APIs following design standards that ensure clear, structured, and resource-based communication.

  • Containerization Pattern:

    • The entire system is packaged into Docker containers, ensuring environment consistency across development, testing, and production.

  • Continuous Integration and Continuous Deployment (CI/CD):

    • Continuous integration is achieved via GitHub Actions, which automates unit and integration testing, code quality analysis (SonarCloud), and container deployments.

4.4. Design Patterns

  • Façade: Centralizes calls to database and Wikidata within the backend API.

  • Lazy Loading: Progressive data loading to optimize frontend performance.

  • Producer-Consumer: A scheduled auxiliary process generates questions and answers, storing them in the database for the game service to use.

4.5. Decisions for Achieving Quality Goals

To ensure system quality, the following strategic decisions have been made:

Quality Goal Decision Taken

Scalability

Use of database Atlas and Node.js backend, ensuring efficient request handling.

Availability

Deployment in a cloud-based environment with automatic scaling.

Security

Implementation of JWT-based authentication for secure access control without third-party dependencies.

Maintainability

Use of the Express framework for a structured and maintainable backend.

Usability

Intuitive web interface with React and automatic question generation to enhance the user experience.

Mitigation of LLM Errors

Use of specifically designed prompts to reduce incorrect responses and pre-filter generated hints.

Reducing Question Loading Time

Preloading questions so that while a user answers a question, the next one is already prepared, thus preventing delays.

4.6. Organizational Decisions

Third-Party Product Reason

Git

Easy-to-use distributed version control system.

GitHub

Web-based platform for hosting and managing Git repositories, including features like issue tracking, pull requests, and GitHub Actions.

Azure

Cloud service used for deploying the application with built-in support for continuous integration.

JSON Web Tokens (JWT)

Secure and stateless authentication mechanism used to manage user sessions.

Prometheus

Monitoring and alerting toolkit ideal for metrics collection.

Grafana

Analytics and monitoring platform allowing real-time visualization of metrics.

SonarQube

Static code analysis tool to ensure code quality and detect vulnerabilities.

CodeScene

Code analysis tool that identifies complexity patterns and technical debt.

Docker

Platform for creating, deploying, and running applications in containers, facilitating portability and scalability.

4.7. Motivation

The architectural decisions in this system are based on the need for an agile and efficient development approach within an academic environment of a couple of months. A Node.js backend with Express was chosen to ensure greater control over business logic while maintaining scalability and ease of integration with React. Additionally, the use of modern tools like Prometheus and Grafana was prioritized to guarantee real-time monitoring and metrics analysis, allowing proactive performance issue detection and resolution. The choice of cloud technologies like WikiData and Azure ensures that the system is scalable and accessible from anywhere.

5. Building Block View

5.1. Whitebox Overall System

5 building block view
Motivation

The previous diagram provides an overview of our system’s workflow. Users can register on our platform and participate in quizzes powered by Wikidata. Additionally, players can interact with our LLM-based chatbot to receive hints.

Contained Building Blocks
Building Block Description

Actor

Represents the end user who interacts with the WiChat application. They can register, play, answer questions, and request hints during the game.

WiChat

The core of the system. It manages game logic, user interaction, authentication, and communication with external services like Wikidata and Gemini.

Wikidata

An external structured data source used by WiChat to dynamically generate quiz questions. It provides up-to-date and relevant content.

Gemini

An external service powered by Google’s language model. It generates intelligent and contextual hints during the game to enhance user experience.

5.2. Whitebox WiChat Level 2

5.2 building block
Motivation

The extended diagram illustrates the complete flow of interactions within the WIChat system. Users interact with the Webapp, a React-based frontend, which sends requests to the backend through the Gateway Service. This gateway routes each request to the appropriate service depending on the operation required—such as user registration, gameplay, or requesting hints. Each service is responsible for a specific domain: UserService manages user data and authentication, GameService handles question generation and score tracking, and LLMService communicates with external language models like Gemini to provide personalized hints. Additionally, GameService retrieves game content from Wikidata, and all persistent data is stored in the database.

Contained Building Blocks
Actores Description

Actor

Represents the end user who interacts with the system through the web application. Users can register, log in, play, and receive hints.

Webapp

The frontend interface built with React. It sends requests to the backend services via the API Gateway and handles user interactions like gameplay and login.

GatewayService

The API gateway that receives all frontend requests and routes them to the appropriate microservice. It also validates JWT tokens and handles authentication flows.

UserService

Manages user-related operations such as registration, authentication, and user data retrieval.

GameService

Responsible for quiz logic, including question generation, answer validation, score tracking, and category management. It retrieves dynamic content from Wikidata and stores results in MongoDB.

LLMService

Handles communication with external language models (e.g., Gemini) to generate intelligent, context-aware hints for the user during the game.

MongoDB

The NoSQL database used for persisting data such as users, scores, game sessions, and questions.

GeminiAPI

External language model API (LLM) used to generate natural language hints during gameplay.

Wikidata

A structured open data source queried by the GameService to create real-time, relevant quiz questions.

6. Runtime View

6.1. Runtime Scenario 1 - Playing a Game

The following diagram shows the interaction between the user and the most relevant modules of the application.

06 runtime view EN

The interaction can be divided into the following steps:

  • Logging in: The user logs into the application. If they do not have an account, they will need to register.

  • Starting the game: Once logged in, the user can start a new game.

  • Answering the questions: For each question, four possible answers will be generated. Once per question, its information (question, image, and possible answers) will be presented to the user through the graphical interface, and the system will wait for their response. After the user submits an answer, the score will be increased—or not—according to the selected answer.

  • Ending the game: Once all questions have been answered, the GUI will display the final score.

  • Chatbot assistance: During the game, the user may interact with a chatbot powered by a language model (LLM) to get hints or general assistance.

Additional considerations:

  • Despite its simplicity, this diagram assumes the user already has an account.

  • The chatbot integration with the LLM may require an internet connection to process user requests.

7. Deployment View

7.1. Infrastructure Level 1

07 deployment
Motivation

This deployment view represents how the WiChat system is distributed across its infrastructure. It helps clarify where each component runs, how they communicate, and how third-party services are integrated. This understanding supports scalability planning, maintenance, and performance optimization.

Infrastructure Overview

The system is deployed using Docker containers, hosted on a Linux-based virtual machine in Microsoft Azure. Each backend service runs in its own container. The frontend is a React application executed in the client’s browser and communicates with the backend via REST APIs through a central gateway.

External Services
Component Description

Wikidata

An external data provider used to retrieve structured information and images that are used to dynamically generate quiz questions.

Gemini (LLM)

Google’s language model, used to generate contextual hints and responses for the chatbot integrated into the game.

Gateway Service

Serves as the single entry point for the frontend. It handles routing of HTTP requests to backend services.

User Service

Manages user-related operations such as registration, authentication, and user data retrieval.

Game Service

Responsible for creating quiz questions using data from Wikidata, validating answers, and managing scoring and categories.

LLM Service

Interfaces with the Gemini API to generate intelligent, context-aware hints for users during gameplay.

MongoDB Database

Stores all persistent data, including user profiles, questions, scores, and historical game data.
Client Side

Web Browser (React App): The user-facing application runs in the browser, built with React and Tailwind CSS. It communicates with the backend exclusively through the Gateway Service and provides the user interface for registration, gameplay, leaderboards, and chatbot interactions.

8. Cross-cutting Concepts

8.1. Domain Concepts

8.1.1. Introduction

This section covers fundamental principles that influence various aspects of the system, ensuring consistency and proper functionality. It includes domain models, design principles, technologies used, and key architectural decisions.

8.1.2. Motivation

The use of cross-cutting concepts ensures the system’s coherence, optimizing development and maintenance while enhancing security, scalability, and user experience.

8.1.3. Categories of Concepts

  • Domain Models

  • User Experience (UX)

  • Operational Concepts

  • Architecture and Design Patterns

  • Security and Data Protection

  • Development Strategies

Each of these is detailed below.

8.2. Domain Models

8.2.1. Domain Structure

  • User: The person who interacts with the app and answers questions while playing the game.

  • Question: A feature allowing users to engage in individual challenges with different formats.

  • Template: The base that makes up the questions and contains the query to search for it

  • Score: The score for each user based on the questions answered correctly.

Domain Entity Diagram

8.3. User Experience (UX)

  • Intuitive Design: A clear and accessible interface for easy navigation.

  • Accessibility Features: Visual aids such as icons and colors to improve understanding.

  • Attractive Design: A beautiful and visually appealing app design.

  • Consistent User Interface (UI): The layout, styles, and interaction patterns remain uniform across all screens and functionalities.

  • Fast Feedback: The system provides immediate visual or textual feedback after every user action (e.g., clicking a button, submitting an answer).

  • Minimal User Effort: Tasks should require the fewest possible steps to complete.

8.4. Operational Concepts

  • Ease of Use: User testing conducted to enhance usability.

  • Enhanced Accessibility: Adjustments made to improve the experience for all users.

  • Performance Optimization: Continuous efforts to optimize loading times, response rates, and system resource consumption.

  • Scalability Management: Operational processes that ensure the system can handle increased load without manual intervention.

  • Resource Efficiency: Strategies to optimize server and database resource usage, minimizing operational costs.

8.5. Security

  • Access Control: Restriction of certain sections to authenticated users.

  • Data Protection: Encrypted credentials to prevent unauthorized access.

  • Authentication and Authorization: Secure mechanisms for verifying user identity and managing permissions based on roles.

8.6. Architecture and Design Patterns

  • Microservices Architecture: The application is segmented into independent modules such as user management, question generation, and graphical interface.

  • Scalability: The modular structure enables system expansion without compromising performance.

8.7. Development Strategies

  • Automated Testing: Implementation of unit and integration tests to validate system functionality.

  • Continuous Deployment: Use of CI/CD pipelines to ensure active development and deployment processes.

  • API Gateway An API Gateway can be used to consolidate access to the different microservices, handling authentication, rate limiting, and logging. It simplifies communication by abstracting the underlying complexity of multiple services.

9. Architecture Decisions

9.1. Overview

This section documents the key architectural decisions made during the development of WIChat. Each decision has been carefully analyzed considering technical feasibility, project constraints, scalability, and maintainability. Providing the rationale behind these decisions ensures transparency and facilitates traceability for all stakeholders.

9.2. Key Architectural Decisions

A comprehensive and up-to-date list of all architectural decisions is available at the following link: https://github.com/Arquisoft/wichat_es1c/wiki

9.3. Motivation

The architectural decisions were guided by the need to create a system that is scalable, maintainable, and easy to deploy within the constraints of a university project. By adopting Node.js and Express for the backend, the project benefits from a robust and flexible framework capable of efficiently managing authentication, database interactions, and API operations.

9.4. Conclusion

The selected architectural approach supports the project’s objectives of rapid development, minimal operational overhead, and scalability. Future iterations of WIChat can build upon these foundations, refining the architecture based on real-world usage patterns and performance metrics.

10. Quality Requirements

10.1. Quality Tree

10 árbol

10.2. Quality Scenarios

Description Quality Attribute Scenario

The system must be available 24/7 with minimal downtime.

Availability

Users can access the system at any time without interruptions.

The architecture must support the addition of more servers without service disruption.

Scalability

During peak hours, the system distributes traffic across multiple servers without performance degradation.

The application must ensure the protection of user data, especially during registration and login.

Security

User credentials and personal data are encrypted and securely stored to prevent unauthorized access.

The response time to display a question and its options must be less than 2 seconds.

Availability / Performance

When a contestant requests a new question, the system presents it almost instantly.

Questions must be correctly generated from Wikidata without errors.

Mitigation of LLM Errors

The system extracts information from Wikidata accurately to generate consistent and error-free questions.

The chatbot must provide relevant and coherent hints based on the LLM API.

Mitigation of LLM Errors

When a user requests a hint, the chatbot generates it correctly using the LLM API.

The user interface must be intuitive, with clear instructions on how to participate and obtain hints.

Usability

A new user can navigate the application without prior instructions and easily understand how to interact with the game.

The application must allow easy updates and maintenance operations without major service disruptions.

Maintainability

Developers can deploy updates or fix bugs quickly without negatively affecting the user experience.

The appplication must be optimized to load questions quickly

Reducing question loading time

Questions should be preloaded when possible to optimize response times and ensure they are displayed instantly when needed.

11. Risks and Technical Debts

Risks and problems may occur during project development.

11.1. Risks

Name Description Priority

Time

The available time for the project is limited due to each dev in the team having other subjects and projects to work on.

Medium

Version Control (GitHub)

Github is a version control tool in which if we do a bad management we could lose some functionality when it comes to manage the conflicts occurred.

Low

Team Communication

Miscommunication or lack of coordination among team members could lead to delays or misunderstandings in the development process.

Low

Power Outage in Spain

The Power Outage in Spain delayed the project and hampered communication among group members, leaving final aspects of the work unfinished.

High

Internet Connection Failure

A failure in the internet connection could interrupt access to cloud services, repositories, or communication tools, delaying the development process.

Medium

Data Loss

There is a risk of losing data due to system errors, hardware failures, or accidental deletions, which could impact project progress.

High

Security Breaches

The system could be vulnerable to unauthorized access or attacks, compromising sensitive information and project integrity.

High

11.2. Technical Debts

Name Description Priority

React

React is a new technology for almost everyone in the team, so they should help each other to learn how to use it, as well as watch some tutorials to understand it better.

High

Documentation

The documentation of the project is incomplete or outdated, which could lead to misunderstandings or difficulties for new developers joining the team.

Medium

Testing Coverage

The project lacks sufficient automated tests, which increases the risk of introducing bugs when making changes or adding new features.

High

Code Refactoring

Some parts of the codebase are not optimized or follow inconsistent coding standards, which could make maintenance and scalability more difficult.

Medium

Dependency Management

The project relies on third-party libraries or services, and updates or deprecations could introduce compatibility issues.

Medium

12. Testing in the Project

12.1. Code Coverage

Code coverage is a metric used to measure what percentage of the source code is being executed by automated tests. In this project, unit tests have been implemented to ensure code quality and reliability.

Tool used Jest

Description

Jest is a testing framework for JavaScript that enables unit testing and code coverage measurement.

Coverage achieved

Currently, the project has achieved 80.2% coverage in critical areas of the system, including business logic and backend controllers.

12.2. End-to-End (E2E) Testing

End-to-end testing verifies the full functionality of the system, from the frontend to the backend, ensuring that the main application flows work correctly.

Tool used Cypress

Description

Cypress is an E2E testing framework that allows simulating user interactions in the browser and verifying system behavior.

Flows tested

- User registration. - Login. - Entering the game. - Navigation through the application.

12.3. Usability Testing

Usability testing focuses on evaluating the system’s user interface and the overall user experience when interacting with the application. The goal of these tests is to identify usability issues and ensure that the system is intuitive and easy to use.

12.3.1. Examples of Usability Tests

Usability tests were conducted with 5 participants from various age groups and different levels of technical expertise. Participants were asked to complete the following tasks:

  • Complete the account creation and login process.

  • Navigate the application and locate the frequently asked questions (FAQ) section.

  • Play a game using the chatbot.

  • Navigate through the main sections of the app (ranking and my account).

  • Access the previously played game from the personal ranking on the home screen and view the game’s statistics and submitted answers.

  • Log out of the application.

  • Results:

    • Onboarding Process: 100% of participants successfully completed the onboarding process without assistance. Most found the process clear and easy to follow, though some suggested adding an option to automatically log in after registration instead of being redirected to the login screen.

    • Frequently Asked Questions: 4 participants were able to find the FAQ section easily. The remaining participant had to search a bit more but eventually found the needed information.

    • Playing a Game: All participants were able to play a game without issues. However, some mentioned they would appreciate more information on how the chatbot works before starting. Additionally, they noted that opening the chatbot felt like a waste of time.

    • App Navigation: All users accessed the main sections of the app without issues.

    • Accessing the Played Game: 3 participants accessed the previously played game from the personal ranking on the home screen and viewed the game’s statistics and their submitted answers. The remaining 2 participants did not manage to access this section because they did not realize they had to click on the played game. Some suggested including a more prominent button or visual cue to guide users toward this option.

    • Logging Out: All participants were able to log out without issues.

  • Conclusion: Overall, participants found the application easy to use and navigate. However, some suggested improvements in the accessibility of certain controls and the clarity of instructions for accessing game statistics. Additionally, an option to automatically log in after registration was considered.

12.4. Load Testing

Load testing is used to evaluate the system’s performance under specific load conditions, ensuring it can handle multiple simultaneous users without degrading its functionality.

Tool used Gatling

Description

Gatling is a load testing tool that allows simulating multiple concurrent users and measuring the system’s performance.

Scenarios tested

Simulation of an execution throughout the application, including registration and login.

Results

The system has satisfactorily handled the established load.

  • Conclusion: Load tests have shown that the system is capable of handling a certain level of usage. However, it is recommended to continue optimizing the backend and perform periodic tests.

12.5. Test Results

Type of test Result

Unit tests

All unit tests have successfully passed, covering the main backend functions.

E2E tests

The main application flows have been successfully validated, ensuring a smooth user experience.

Usability tests

The main application has been tested by real people who have provided feedback on its performance.

Load tests

The system successfully the tests.

12.6. Conclusion

The use of coverage and end-to-end testing has enabled early detection and correction of errors during development, improving system quality and reducing the risk of production failures. It is recommended to continue expanding test coverage and perform periodic end-to-end (E2E) testing to ensure system stability. Thanks to Coverage testing, we have been able to review lines of code critical to development.

13. Glossary

Term Definition

Risks

Risks are something bad that could happen but has not yet happened.

Technical Debt

Debt acquired by consciously or unconsciously making the wrong design decisions.

LLM

A large language model is a type of machine learning model designed for natural language processing tasks such as language generation.

Skateholders

Person who affects, is affected or can contribute to the system and its architecture

Wikidata

Wikidata is a free and open knowledge base that can be read and edited by both humans and machines.

API

Application Programming Interface: A set of definitions and protocols that allow different applications to communicate with each other.

CI/CD

Continuous Integration/Continuous Deployment: A set of practices that automate the integration and delivery of code to improve development quality and speed.

Frontend

The part of an application that directly interacts with users, typically developed using technologies like HTML, CSS, and JavaScript.

Backend

The part of an application that handles server logic, databases, and data processing.

Cloud Computing

The use of remote servers hosted on the Internet to store, manage, and process data instead of local servers.

Microservices

An architectural style that structures an application as a collection of small, autonomous services that communicate with each other.

Scalability

The ability of a system to handle an increase in workload without compromising performance.

JSON

JavaScript Object Notation: A lightweight data interchange format that is easy for humans and machines to read and write.

REST

Representational State Transfer: An architectural style for designing web services that uses standard HTTP methods.

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.