1. Introduction and Goals
WIQ is a project developed for the subject "Software Architecture" of the Computer Engineering degree of the School of Computer Engineering of the University of Oviedo. This project is based on the wiq project, made available to the students by the teachers of the subject. WIQ! has been commissioned to the company HappySw by RTVE, with the aim of recreating its famous quiz show Saber y ganar in a web version accessible to everyone. This project will be carried out by the development team, which is formed by:
WIQ! is a software by means of which users can emulate being the participants of the quiz show Saber y ganar, which has numerous functionalities:
-
Play several of the game modes seen on the show.
-
Register to be able to keep track of their statistics in the game
-
Have friends, join groups and see the statistics of the other users.
-
Adjust the themes of the questions, the answer time, the number of questions… *
1.1. Requirements Overview
-
The system will have at least one web frontend that will be deployed and accessed via the web.
-
Users will be able to register in the system and consult the history of their participation in the system: number of games, number of correct/failed questions, times, etc.
-
Questions will be automatically generated from Wikidata data.
-
Questions must be answered within a given time limit.
-
Each question will have one correct answer and several incorrect or distracting answers. Both correct and incorrect answers will be generated automatically.
-
The system shall allow access to user information through an API.
-
The system shall allow access to the information of the generated questions through an API.
1.2. Quality Goals
| Priority | Quality Goal | Motivation |
|---|---|---|
1 |
Usability |
The application should be intuitive for users, making it easy for them to interact with the application regardless of their skills. |
2 |
Mantainability |
The application must have a well-defined and structured design, so that it is easy to make modifications and/or extensions. |
3 |
Availability |
The application must ensure high availability, with mechanisms in place to prevent system failures and ensure continuous access to its services. |
1.3. Stakeholders
| Role/Name | Contact | Expectations |
|---|---|---|
Students (HappySw) |
Martín Cancio Barrera, Iyán Fernández Riol and Rodrigo García Iglesias |
The students are the developers of the application. They are in charge of the complete development, which will improve their programming and teamwork skills. |
Users |
Anyone who uses the application |
Users are the ones who will ultimately use the application, so it must be intuitive and easy to understand. |
Teachers |
José Emilio Labra Gayo, Pablo González González, Jorge Álvarez Fidalgo and Cristian Augusto Alonso. |
They are the supervisors of the project, and will help the students toensure that the project comes to fruition. |
RTVE |
RTVE |
They are the main stakeholders in the application, as they are the ones who commissioned it, so that their viewers can use it. |
2. Architecture Constraints
| Architecture constraint | Description |
|---|---|
Development Technology |
The application must be developed using web technologies compatible with RTVE’s requirements and standards. |
Implementation Platform |
The application must be implemented on a web hosting platform that meets RTVE’s performance, security and scalability requirements. |
Code Maintainability |
Software development practices that promote clean and well-documented code should be followed to facilitate future upgrades and maintenance. |
Development Time |
The application must be developed within a specific time frame, which may influence architectural decisions and technology selection. |
Wikidata Integration |
The system architecture must incorporate the use of Wikidata as data source to generate questions, ensuring seamless integration and consistency with external knowledge bases. |
3. System Scope and Context
3.1. Business Context
Entity |
Description |
User |
It’s the one that interacts directly with the app. |
WIQ! |
The web application. |
Wikidata |
Source from which data is drawn to formulate questions |
3.2. Technical Context
Entity |
Description |
User |
Represents the user interacting with the system. In this case, the user is interacting with the "WIQ!" application through the device and the web browser. |
Device |
The device used by the user to access the application. This node contains the web browser component that allows the user to interact with the application. |
Cloud |
Represents the cloud infrastructure, in this case, Azure. This node contains the "WIQ!" component that hosts the application and allows its access through HTTP/HTTPS protocols. |
WIQ! |
The main application that the user interacts with. It is hosted on the Azure cloud and accesses a MongoDB database to store and retrieve data, as well as interacts with Wikidata through REST. |
Wikidata |
Source from which data is drawn to formulate questions. The application will request data via "Wikidata Query Service", which allows to retrieve data using SparQL. |
MongoDB |
The database management system used by the "WIQ!" application to store and retrieve data. In this case, it is used to store data related to the application. |
4. Solution Strategy
We developed an application in which users can register to play, where in each game they will have to answer several questions, from different categories, where it will be saved A ranking with the maximum score of the user and can be compared with other users, it will also have a section that indicates their correct guess and in which category they get the most questions right.
-
JavaScript: JavaScript is a very flexible programming language widely used in software development. It incorporates many features that makes this development easy and effective, such as asynchronous functions, libraries, etc. This is the language that will be used to create front-end and back-end on our application.
-
Node.js: Node.js is a JavaScript runtime built on Chrome’s V8 JavaScript engine. It’s used to create server-side applications, and it’s the runtime that will be used to create the back-end of our application.
-
MongoDB: MongoDB is an open-source NoSQL database that uses a document-based data model for information storage and retrieval.
-
React JS: It’s a framework created by Facebook that’s widely used to create user interface components. Chosen for the large volume of documentation and the fact that it is the framework used during the previous courses.
-
Chakra UI: It’s a simple, modular and accessible component library that gives us the ability to create a responsive and accessible design.
-
WikiData: It’s a free knowledge base modified by humans as well as machines, and it’s where we’ll get our questions from.
-
Microsoft Azure: A cloud computing platform that provides infrastructure, platform, and software-as-a-service services to host, manage, and scale online applications and services.
-
GitHub: It’s a platform that provides hosting for software development and version control using Git. It’s where we’ll host our code and collaborate with the team.
-
Github Actions: It’s a CI/CD tool that automates the process of building, testing, and deploying code. It’s where we’ll automate the process of testing and deploying our application in Azure Cloud.
-
Asciidoc: It’s a text document format for writing notes, documentation, articles, books, ebooks, slideshows, web pages. We’ll use it to document our project.
4.1. Design
The designed website is composed of a frontend in React, a backend in Node.js and is documented using Asciidoc. Each user will have their own account where their information will be saved. Design-related decisions are detailed in point 9.
4.2. Testability
Tests will be carried out for each individual part of the application, thus ensuring the correct operation of the different modules both individually and together.
4.3. Interface
The graphical interface will be chosen among all the members of the team, each one contributing a sketch or idea, which will be shared and it will be decided which best fits the expected performance and which elements of these sketches are most suitable. This will take into account the usability and needs of different types of users.
5. Building Block View
5.1. Whitebox Overall System
The code is broken down in a structured way by levels, in which the internal dependencies of each element are taught. The system is divided into Whitebox and Blackbox.
Actors |
Description |
User |
It’s the one that interacts directly with the app. |
5.2. Blackbox Overall System
Name |
Description |
WIQ |
The application which users will interact with. |
Wikidata API |
The API that will provide data to the application, in order to generate the questions. |
5.3. Level 1
The system is divided into nine components, each of which is responsible for a specific task. These components are.
Component |
Description |
Webapp |
The main component of the application, which will be responsible for the user interface and game logic. |
Gateway service |
The component that will be responsible for the communication between the web application and the other microservices. |
Auth service |
The component that will be responsible for the authentication of the users. |
User service |
The component that will be responsible for the user data. |
Question service |
The component that will be responsible for generating the questions. |
Stats service |
The component that will be responsible for the statistics of the game. |
Prometheus service |
The component that will be responsible for monitoring the application. |
Grafana service |
The component that will be responsible for visualizing the monitoring data. |
MongoDB |
The database that will store the user data. |
5.4. Level 2
In this level, the components are divided into smaller components, which are responsible for specific tasks. We’ll take a closer look to some of the most important components, which are question service, and webapp.
5.4.1. Question Service
Building block |
Description |
Question service |
The component that will be responsible for receiving requests from gateway service and responding with the questions. |
Generator chooser |
The component that will be responsible for generating generic generators, which will be used to generate the questions. |
Generic generator |
The component that will be responsible for generating the questions about one specific topic. |
5.4.2. Webapp
Building block |
Description |
App |
Main component of the application, which will be responsible for routing. |
Home |
The component that will be responsible for the home page. |
Login |
The component that will be responsible for the login page. |
Register |
The component that will be responsible for the register page. |
Clasico |
The component that will be responsible for the classic game mode. |
Batería de sabios |
The component that will be responsible for the wise battery game mode. |
Calculadora |
The component that will be responsible for the human calculator game mode. |
Stats |
The component that will be responsible for the statistics page. |
Profile |
The component that will be responsible for the profile page. |
Settings |
The component that will be responsible for the settings page. |
Sobre |
The component that will be responsible for the about page. |
6. Runtime View
6.1. User logs in
User logs in by entering his username and password. The system checks the credentials and if they are correct, the user is redirected to the main page. Otherwise, an error message is shown.
6.2. User registers
User registers by entering his username, password, email and other optional information. The system checks if the username is unique and if the email is valid. If everything is correct, the user is redirected to the main page. Otherwise, an error message is shown.
6.3. User plays a game
User selects a game to play. The system loads the game and the user can start playing. The user can pause the game, save it and resume it later. When the game is over, the user can see his score and the game is saved in the user’s history.
It should be noted that this does not require access to wikidata data, as the system has a data caching system that allows wikidata data to be stored in the system’s database, so it is not necessary to access wikidata every time a game is played.
6.4. User looks his stats
User can see his stats by pressing stats button. It shows things such as games played, average score, total score, total correct questions, total incorrect questions, correct answer ratio or average time per question.
6.5. User looks his game history
User can see his game history by pressing history button. It shows a list of games played, with answered questions.
6.6. User looks at ranking
User can see the ranking of the users. This ranking can be filtered by average points, total points, correct answer ratio or average time.
6.7. User checks his friends
User can see his friends. He can also get into their profile to see their stats.
6.8. User looks for users to be friends
User can see a list of non-friends users. He can send a friend request to them.
6.9. User looks for available groups to join
User can see a list of available groups to join. He can send a request to join them.
7. Deplyment View
7.1. Infrastructure Level 1
- Motivation
-
The infrastructure consists on a set of containers that will be deployed in a cloud provider. This containers will be responsible for the different parts of the application. The infrastructure will be monitored by Prometheus and Grafana. The data will be stored in a MongoDB database. The application will use Wikidata to obtain the data for the questions.
7.2. Infrastructure Level 2
7.2.1. Webapp
This container is responsible for the user interface.
7.2.2. Question Generator
Question generator is the part of the application that generates the questions for the users.
7.2.3. User Service
User Service is the part of the application that handles users information.
7.2.4. Auth Service
Auth Service is the part of the application that handles the authentication of the users. It’s very important as it’s the first thing a potential user will encounter when they visit our page.
7.2.5. Stats Service
Stats Service is the part of the application that handles the statistics of the users.
7.2.6. Gateway service
Gateway service is the part of the application that handles the communication between the different parts of the application.
7.2.7. MongoDB
MongoDB is the database that will store the data of the users, the questions, the answers, and the statistics of the application.
7.2.8. Prometheus
Prometheus is the monitoring tool that will be used to monitor the application.
7.2.9. Grafana
Grafana is the visualization tool that will be used to visualize the monitoring of the application.
7.2.10. Wikidata
WikiData is the API that you we will use to obtain the data for the questions. Wikidata is a free and collaborative database that can be read and edited by both humans and machines. It provides a common source of certain types of data that can be used by Wikimedia projects.
8. Cross-cutting Concepts
8.1. Domain Concepts
This is the actual domain of the application, which is the area of knowledge or activity that the application is designed to support. In this case, the domain is quiz games, which are games that test the player’s knowledge on a specific topic.
8.2. Architecture and Design Patterns
The project follows a microservices architecture, which is a design pattern that structures an application as a collection of loosely coupled services. This makes the application more scalable, flexible, and easier to maintain.
8.3. User Experience (UX)
8.3.1. User Interface
A user interface is the space where a human and a computer or device communicate and exchange information
The user interface is the part of the application that directly interacts with the client, in our case, the player. It should function correctly and be user-friendly.
8.3.2. Ergonomics
Ergonomics is the science of designing and arranging workplaces, products, and systems to fit and adapt to the people who use them. Ergonomics aims to improve comfort, efficiency, and safety by considering human physical and psychological needs and limitations.
8.3.3. Internationalization
The application should be able to support multiple languages and regions, so that it can be used by people from different countries and cultures. As of today it has been translated into Spanish and English.
8.4. Development Concepts
8.4.1. Build, Test, Deploy
The project follows a CI/CD pipeline that automates the build, test, and deployment processes. This ensures that the application is always up-to-date and working correctly.
8.4.2. Configurability
The project has a configuration file that allows the developer to generate new types of questions just by modifying the file. This makes the application more flexible to topic addition.
8.5. Security and safety
8.5.1. Security
The app REST API verifies the user’s identity and permissions before allowing access to the resources. It also prevents sensitive data from being exposed to unauthorized users. This ensures that the application is secure and protects the user’s data.
8.5.2. Safety
The application has a backup system that automatically saves the user’s progress in case of a failure. This ensures that the user’s data is always safe and can be recovered in case of a problem.
8.6. Operation concepts
8.6.1. Disaster-Recovery
App containers have restart policies that automatically restart the container in case of a failure. This ensures that the application is always available and running despite any failures.
8.6.2. Monitoring
The application has a monitoring system that tracks the performance and availability of the application. This allows the developer to identify and fix any issues before they affect the user’s experience.
9. Architecture Decisions
10. Quality Requirements
In our project, we have some quality goals or expectations that we want to be met. These are:
-
Performance: ability of the software system to respond well to user interactions and perform tasks efficiently.
-
Usability: intuitiveness of the software interface, making it easy for users to interact with the system.
-
Maintainability: how easily the software system can be modified, updated, and extended without significant effort or risk.
10.1. Quality Tree
-
Quality
-
Performance
-
Usability
-
Maintainability
-
-
Relationships
-
Quality → Performance
-
Quality → Usability
-
Quality → Maintainability
-
10.2. Quality Scenarios
10.2.1. Usage Scenarios
| Aspect | Source | Stimulus | Artefact | Environment | Response | Response Measurement |
|---|---|---|---|---|---|---|
Performance |
User |
While playing, a user selects a response to a question. |
User Interface |
Normal gameplay conditions. |
The system updates its interface very fast and the user knows if they responded correctly, so they can keep playing. |
Interface update time is less than 0.5 seconds. |
Usability |
User |
A new user starts playing the game. |
User Interface |
Initial game setup. |
The user interface displays available options and provides clear instructions on how to play, including a 'Help' button. |
User can navigate through the interface without guidance. |
Performance |
User |
A user finishes playing a game and wants to start a new one. |
System and User Interface |
Post-game completion. |
The system ends the current game, displays the user’s score, resets all game elements, and offers the option to start a new game. |
Score is saved accurately, and game restarts without errors. |
Performance |
User |
A user finishes playing a game and wants to see his stats. |
System, User Interface, Stats Service |
Stats retrieving. |
The user presses the Stats button, and his stats are shown in the screen, giving him the option to switch between gamemodes. |
Stats are shown correctly, including last game. |
10.2.2. Change Scenarios
| Aspect | Source | Stimulus | Artefact | Environment | Response | Response Measurement |
|---|---|---|---|---|---|---|
Maintainability |
Developers |
We want to add the option of logging in with an e-mail instead of an username |
Login system is well structured so it is easy to modify it or add new ways of logging in |
Normal conditions |
The development team implements the new login method easily, ensuring that neither the current data or the new credentials will be compromised |
Successful integration of the new login method without compromising data |
Maintainability |
Developers |
Developers want to add a new game mode |
The game’s code is well-structured and documented |
Development phase |
Due to code being well-structured and documented, it is easy to add new functionality to our system without risking our already implemented functionality |
Successful addition of new game mode |
Maintainability |
Developers |
An error is identified in the game that needs to be corrected. |
The game’s code is well-structured and documented |
Error identification and resolution phase |
Due to code being well-structured and documented, developers can easily locate the error and correct it |
Successful identification and correction of the error |
11. Risks and Technical Debts
| Priority | Description of Risk/Technical Debt | Suggested Measures |
|---|---|---|
High |
Potential application malfunctions |
Implement unit tests for key components and critical functions, along with extensive testing with real users |
Medium |
Slow performance of database queries |
Optimize database queries, avoid unnecessary queries |
Medium |
Potential unavailability of Wikidata |
Design the UI to handle missing or incomplete data from Wikidata. |
Low |
Unoptimized styles |
Optimize styles to improve application performance and loading times |
Low |
Insufficient documentation |
Provide comprehensive documentation of architecture, code structure, development processes, and deployment to facilitate team maintenance and collaboration |
Low |
Vulnerabilities in user authentication |
Implement additional security measures, such as password encryption |
12. Testing
This section details the results of the various types of tests that have been carried out with the application.
12.1. Unit Testing
We used Jest to perform unit testing on the application. We have written tests for all the components of the application, mocking the database and external services. All the tests passed successfully. The results of the tests are shown below:
12.1.1. Auth service
12.1.2. User service
12.1.3. Gateway service
12.1.4. Stats service
12.1.5. Webapp
12.2. e2e Testing
We used puppeteer to perform end-to-end testing on the application. We have written tests for login, register, create group, and for the three gamemodes.
12.3. Code coverage
We used sonarCloud to check the code coverage of the application. The results are shown below:
12.4. Usability and accessibility Testing
We used some tools to measure usability levels of the application, along with some testing with real users (friends and family).
12.4.1. Automatic tools:
First, we will show the automatic tools results:
PageSpeed Insights:
This tool is used to measure different aspects of a certain page, such as performance, accessibility, best practices and optimisation. We used this tool on all of our pages, and the results were kind of similar. Below, the results for the Classic and Stats page are shown:
As we can see, our pages perform very nicely on every evaluable aspect, except in Best practices, and that’s because the tool is giving us a warning because we don’t use HTTPS in our application, which can lead to security issues.
Juicy Studio:
This tool is used to measure the contrast between background and foreground colors of a web page. We used this tool on both of out color combinations: dark mode and light mode. The results are shown below:
As we can see, both of our themes use correct and high-contrasted color combinations.
12.4.2. Testing with real users:
We did some testing with 18 people, all of them being friends and family of us, the develpoment team. We let them try the application, play games, view their stats, create groups, etc., and when they were finished we asked them a few questions. We wanted to get from each individual his UI rating, functionality rating and some recommendation of things we could change / add if we continued developing the app.
The results of this test are shown below:
As we can see, we have attempted to conduct tests with people of various ages, and approximately the same number of men and women, in order to obtain different perspectives and a broader and more diverse range of users. We consider the results to be very positive, judging by the average of the scores obtained.
However, looking at the recommendations made by our testers, we think it would be a good idea to work on upgrading the group system, adding administrators, invitations, and private groups, and adding friend requests. We should also consider improving our UI, maybe studying design tendencies and trying to applicate them to our project.
12.5. Load Testing
We used Gatling to perform load testing on the application. It consisted of simulating 1000 users accessing the application at the same time, each of one performing 83 requests. The results of the test are shown below:
Using this script we inject 2 users per second during 60 seconds in total, and each user performs 83 requests. The test was successful, and the results are shown below:
As we can see in Gatling’s report, the application was able to handle a load of 9990 requests. In particular, 97% of the requests were successful in less than 800 milliseconds and 3% were unsuccessful.
This shows that the application is able to handle a large number of requests in a short period of time, with a high success rate. We can also be sure that the application is able to handle a large number of users accessing it at the same time in production.
12.6. Code coverage
We used SonarCloud to check the code coverage of the application. It shows test coverage, code duplication, and code smells, among other things. The results are shown below:
13. Glossary
| Term | Definition |
|---|---|
WIQ |
Application or game based on the TV show "Saber y Ganar". |
Login |
Process of authenticating a user’s identity to access the application. |
Wikidata |
Online collaborative database storing structured data and linking information across different projects and languages. |
User |
Person who interacts with a system, service, or application to perform tasks. |
Admin |
Person with special rights or authority to manageaspects of an application. |
Query |
Request for information from a database. |
Database |
Organized collection of structured information. |
Documentation |
Written information regarding a system’s design, functionality, or usage. |
Distractors |
Incorrect or irrelevant options or elements included in a question. |
NodeJS |
Runtime environment that allows the execution of JavaScript code outside of a web browser. |
ReactJS |
JavaScript library for building user interfaces, particularly single-page applications. |
JavaScript |
High-level programming language primarily used for creating interactive web pages and applications. |
MongoDB |
Popular NoSQL database program, known for its flexibility and scalability. |
CSS |
Cascading Style Sheets, used for styling and formatting web pages written in HTML. |
HTML |
Hypertext Markup Language, the standard markup language for creating web pages and web applications. |