wichat_es2a

Efficiency

The game should run quickly and smoothly, so as not to bore the user with unnecessary waiting.

Usability

The application must be easy to learn and use, because no one will stop to read an instruction manual.

Maintenance

The application must be designed in such a way that parts can be modified in the future without the need to redo the application.

Testability.

Different use cases should be tested to ensure correct operation.

Security

The application should be secure enough so that no one can access a user’s personal information without permission.

Development Team

To improve their hard skills using different technologies, mainly focused on the web. Improve their soft skills such as teamwork skills, communication and time management.

Teachers

They are in charge of guiding the students and supervising their work, as well as helping them to solve any problems that may arise.

Users

They will be in charge of using the application.

GIT & GitHub

The use of GIT will be mandatory for version control, and GitHub will be the platform we use to store the code. This system will allow parallel work by using branches for developing new features or fixing bugs. Additionally, we will use Pull Requests for code review before final integration. GitHub Actions may be used to automate testing deployment.

Docker

Docker will be used to containerize the application in both development and production environments for web deployment, ensuring consistent environment configurations and simplifying application maintenance across different platforms.

MongoDB

MongoDB will be used as the primary database to store user data, questions, and hints. Its flexible schema will allow efficient handling of dynamic content and scalability for future improvements.

React

The frontend will be developed using React to create a dynamic and responsive user interface. This framework will enable a component-based architecture, improving maintainability and reusability.

Node.js

Execution environment using JavaScript for server-side operations, rather than client-side. It provides an event-driven, non-blocking I/O model, making it lightweight and efficient.

Express

Web framework for Node.js designed to simplify the implementation of web applications. It offers a minimal and flexible structure for handling routes, middleware, and API endpoints.

JavaScript

JavaScript will be the main programming language for both the frontend (React) and backend (Node.js & Express), ensuring a unified development environment and reducing context switching between technologies.

Wikidata

Wikidata will be the primary source for generating images for the questions and hints.

LLMS (Long Language Model)

The system will use an external language model (LLM) to generate interactive hints about the images. However, due to the inherent limitations of LLMs (such as generating incorrect responses or hallucinations), it will be necessary to implement mechanisms to validate and mitigate these issues to ensure the accuracy of the generated hints.

Team

The project team consists of 6 people, which means that coordination and cooperation between team members is essential.

Time

The team must adhere to the established deadlines for project delivery, ensuring that progress is presented according to the anticipated dates and the decisions documented in the meeting minutes.

Meetings

Weekly meetings will be held during the practical classes, where the tasks completed by each team member during the previous week will be reviewed, and new tasks will be discussed. If there is a need to address questions outside these meetings, team members can ask through the WhatsApp group, or hold meetings via Discord, making sure that the decisions made during those sessions are clearly documented on GitHub.

Issues

The GitHub Issues tool will be used for task management. Each team member will be responsible for completing the tasks specified within the given time frame.

Records

After each meeting, whether during the scheduled practice hours or any extraordinary meetings, meeting minutes will be written to document the decisions made.

Software Design

The code must be modular, maintainable, and understandable. "Clean code" principles will be applied to ensure the project is easy to update and expand.

Documentation

The Arc42 template will be used to create the project documentation. This documentation must be clear, structured, and easy to follow, with a practical approach so that any team member or external person can understand the architecture and key components of the system.

Adaptability

The application must be designed to work across multiple devices and screen sizes, ensuring a consistent experience on both desktop and mobile platforms. Responsive design techniques and best practices will be implemented to optimize usability across different resolutions.

Usability

The system must provide an intuitive and accessible user interface, ensuring a smooth experience for all users.

Users (Contestants)

Registration data, game responses, hint requests

Game questions, AI-generated hints, game history

System Administrator

Platform management commands

System status reports, user activity logs

Language Model (LLM)

Image and question data

Interactive hints

Wikidata

Data queries

Images and question-related data

Users (Contestants)

HTTP (Web Browser)

Game interactions, hint requests, and responses

System Administrator

HTTP (Admin Panel)

Platform management commands and logs

Language Model (LLM)

API (REST/GraphQL)

Image/question data and hint generation

Wikidata

API (SPARQL)

Data queries and responses

Game responses, hint requests

HTTP

Users (Contestants)

Platform management commands

HTTP

System Administrator

Image/question data, hint generation

API

Language Model (LLM)

Data queries and responses

API

Wikidata

Usability

To ensure the usability of the application, an intuitive and simple interface will be designed so that the user has no doubts about what action to take at any moment. In addition, a sufficiently legible font with an appropriate size and weight will be used. Finally, the application will be made responsive to facilitate its use on different devices.

Maintainability

In order to facilitate the maintainability and expansion of the application, we will try to follow the good practices for software development acquired in other previous subjects of the degree. An example of this will be some of the SOLID principles previously studied, such as the Single responsibility principle or the Open/closed principle.

Task distribution

GitHub Issues

It will be used to assign each of the tasks into which the project is divided to a member of the team. These tasks will be distributed equally among the different members of the team, trying to adjust to the knowledge and tastes of each one.

Changes approval

Pull requests

Once each task is finished, a pull request will be made so that at least one component of the team other than the developer of the task will review it before merging it to the main branch of the project.

Project timeline

GitHub Projects

This will be used to track the development of the project and be able to see which parts are completed and which are not, as well as which parts are currently being worked on.

Communication

Weekly meetings

Meetings will be held on a weekly basis to see what is the status of the project, what has been done and what remains to be done.

Documentation

AsciiDoc

We have chosen Asciidoc as the primary documentation tool. This decision is largely due to the ease and intuitiveness of deploying documentation using the tools provided by the Asciidoc ecosystem.

User

Represents the participants of the game (they can answer questions and request hints).

Browser

Interface where the user interacts with the game. It is responsible for sending answers and hint requests.

WIChat

Manages the game logic. It communicates with Wikidata to retrieve data and provides additional information to the LLM when necessary.

Wikidata

Database that provides the data to generate the questions.

LLM (Large Language Model)

Processes users' questions about the images and returns hints to the Browser to help the participants.

User interface (User ↔ Browser)

The user interacts with the Browser. The Browser is used to send answers and requests hints.

HTTP/REST Inteface (Browser ↔ WIChat)

The browser communicates with de WIChat system using HTTP or REST requests to send answer and retrieve game information

Hints Requests (Browser ↔ LLM)

The browser requests hints from the Large Language Model (LLM) to assist the participants.

Query for Additional Information (LLM ↔ WIChat)

The LLM queries WIChat when additional information is needed to provide hints.

REST Inteface (WIChat ↔ Wikidata)

WIChat interacts with Wikidata via REST requests to retrieve data for generating questions.

Response in HTML/JSON (WIChat ↔ Browser)

WIChat sends the processed information to the browser in HTML or JSON format to be presented to the user.

Sending Hints (LLM ↔ Browser)

The LLM sends hints to the browser to be displayed to the user.

User

Represents the participants of the game. They can answer questions of the main game or the math mini-game, request hints, join groups and interacts with other users.

Browser

Interface (frontend) where the user interacts with the game. It sends request to the backend via the Gateway.

GatewayService

Acts as a central single entry point for frontend requests. It routes them to the appropriate backend service.

WikidataService

Handles the core game logic. It retrieves questions and answers from the external Wikidata repository and process them for the game

Wikidata (external)

External semantic knowledge base. The WikidataService queries this to obtain data for generating questions.

LLM (Large Language Model)

Provides hints based on user requests. It may contact the WikidataService to obtaing context or clarigy game-related data before responding

MathGame

A backend service that generate math-based questions and evaluates answer, providing an additional mini-game experience.

AuthService

Handles user authentication, including login and token generation.

UserService

Manages user data, including profile information, friend requests and private messages.

GroupService

Handles group-related functionalities, such as creating groups, adding users to groups, and managing group messages.

APIService

Provides a REST API for external integrations and serves as a bridge between the GatewayService and other services.

User interface (User ↔ Browser)

The user interacts with the Browser to answer questions(for the main game or math mini-game), request hints, manage their profile and join or create groups.

Frontend (Browser ↔ WebAppService)

The Browser sends all requests (game logic, hints, user info, etc.) to the WebAppService using HTTP/REST.

Frontend to Backend Gateway (WebAppService ↔ GatewayService)

The Gateway routes these request of WebApp to the appropriate backend services.

Game Logic (GatewayService ↔ WikidataService)

Routes game-related request (e.g., get question, submit answer) from the frontend to the WikidataService.

Wikidata Query Interface (WikidataService ↔ Wikidata)

The WikidataService comunicates with the public Wikidata knowledge base to retrieve data for generating questions.

Hints Requests (Gateway ↔ LLMService)

Routes hint request to the LLMService, which enrich response by querying WikidataService

Math Game (GatewayService ↔ MathGame)

Routes math-game specific request (new question, validate answer) to the MathGame service.

Authentication (GatewayService ↔ AuthService)

Handles login and authentication logic via secure requests through the Gateway.

User Management (GatewayService ↔ UserService)

Routes requests for user profiles, friendships, and messages to the UserService.

Group Management (GatewayService ↔ GroupService)

Routes group-related operations (create group, join, chat) to the GroupService.

External API Interface (APIService ↔ External Systems)

Allows external clients to consume parts of the system’s functionality securely.

User agent

The client that accesses the system through the web application.

Virtual Machine

The server hosting the system.

Docker

Containerization platform used for deploying and managing the system.

Wikidata API

External service that provides dynamic content for the application.

Large Language Model (LLM)

AI-powered component that analyzes application context to assist users with relevant hints.

Functionality

The user starts a new game

The system will provide a question, set a time limit and initialize the scoring system.

High

Usability

A new user opens the game for the first time

The system will be easy to understand at first sight, and prepared to answer any questions the user might have about its use. It will also be able for people with various disabilities to use it.

High

Performance

A user answers a question

The system will provide instant feedback (right or wrong) and move to the next question without any delay.

High

Security

A user logs in

All data is safely stored and encrypted, with no vulnerabilities.

High

Testing

A user plays the game

No bugs will be encountered during the game.

High

Compatibility

A user opens the game in a web browser

The game will work properly independently of the browser used.

High

Content

A user starts a game

Different categories and difficulty levels will be available.

Medium

Scalability

A large number of users play the game

The system will be able to handle the load without any performance issues.

Medium

Maintainability

A developer needs to update the system

The code will be well-documented and easy to understand.

Medium

Extensibility

A developer wants to add a new feature

The system architecture will allow for easy extension.

Medium

Localization & Internationalization

A user changes the language

The system will switch to the selected language.

Low

Lack of experience with the base project and its technologies

9

Since none of the team members have prior experience with the technologies used in this project, there will be a steep learning curve. This will require extensive research and testing, which could slow down progress. However, leveraging documentation and online resources will help mitigate this risk.

First time working as a large team on a software project

8

The team has experience in GitHub but has not collaborated in such a large group before. This could lead to difficulties in task distribution, communication, and version control conflicts. Establishing clear workflows and communication channels will be essential to mitigate these issues.

Integration of a Large Language Model (LLM) chat system

7

Adding an AI-driven chat system for user hints introduces complexities such as model selection, API integration, and performance optimization. Ensuring precision in the chat responses will require careful planning.

Managing dependencies and service configurations

6

The project relies on multiple external services and dependencies, which may introduce compatibility issues. Keeping dependencies up-to-date and using containerization tools can help manage these risks.

Unequal distribution of workload

5

If tasks are not evenly distributed among team members, it may lead to burnout or bottlenecks. Regular meetings and tracking progress using project management tools will be necessary to balance workload effectively.

Microservices deployment limitations

8

Despite the project’s adoption of a microservices architecture, the current deployment setup lacks proper load balancing and auto-scaling capabilities. This creates a significant bottleneck when handling increased user traffic, particularly during peak usage times. Performance degradation becomes noticeable even with moderate user loads, making the application unsuitable for production environments without these enhancements. Implementation of container orchestration with Kubernetes or advanced Docker Swarm configurations would be necessary to fully leverage the microservices architecture’s scalability benefits.

Code reuse issues and structural patterns duplication

7

Significant code duplication exists across microservices in the form of identical utility functions (validateRequiredFields, MongoDB connection setup) implemented independently in each service. This undermines the modularity benefits of the microservices architecture and creates maintenance challenges when common functionality needs to be updated. Additionally, error handling patterns are inconsistent across services, with varying approaches to validation and error responses. Similar test setup code is also duplicated across test files, with each service reimplementing MongoDB memory server configuration. A systematic refactoring effort to extract common utilities into shared libraries, standardize error handling patterns, and create reusable test fixtures would significantly reduce maintenance complexity and improve code quality.

Wikidata API performance limitations

6

The Wikidata service experiences performance issues, particularly with slow response times when fetching questions. This affects the game experience as users may experience delays while waiting for questions to load. Performance optimizations, caching mechanisms, and potentially preloading questions are required to improve user experience.

LLM service scalability constraints

8

The current LLM service implementation can only handle approximately 3 simultaneous connections and has token limitations due to using a personal-use API key. This severely restricts the scalability of the application in a production environment with multiple users. A production-ready API key with higher rate limits or implementing a queuing system would be necessary to scale the application.

Limited internationalization

5

The question system currently only supports English or Spanish, limiting the accessibility for the people which can speak neither languages.

Lack of robust error handling

6

Many API endpoints have basic error handling that returns generic error messages rather than providing specific information to help diagnose issues. This makes troubleshooting more difficult, especially in production environments. More comprehensive error handling with appropriate logging would improve system reliability and maintenance.

Environment variable management

4

The project relies on numerous environment variables for configuration with inconsistent handling across services. This creates potential for configuration errors and complicates deployment. A standardized approach to environment variable management and validation would improve system reliability.