Template

1. Introduction and Goals

1.1. Requirements Overview

The WIQ web application allows users to play a game similar to the one of Saber y Ganar quiz show. This game consists on answering a number of questions with different types and subjects obtaining a prize for each question well answered. Game´s questions are automatically generated from data available in Wikidata (https://www.wikidata.org/).

The system will have at least a web front-end which will be available and accessible through the web.
Users will be able to register with the system and obtain the historical data from their participation: number of games, questions passed and failed, times, etc.
Questions will be automatically generated from data available in Wikidata.
Questions have to be answered before some specific time.
Each question will have one right answer and several incorrect ones or "decoy answers". Both the right answer and the decoy ones should be automatically generated.
The system will give access to the information about the users through an API.
The system will give access to information about the generated questions through an API.

1.2. Quality Goals

Table 1. Quality goals ordered by priority (from most to least important)
Quality Goal	Description
Learnability	Any user must be able to use the app with ease. The interface must remind the user to the one in Saber y Ganar quiz show.
Satisfaction	Users will not get repeated questions in at least a hundred questions.
Modularity	The application will be divided in modules so that a change on one component has minimal impact on other components.
Testability	The application should be able to go through different test and complete them successfully.
Time behaviour	Users will not have to wait more than 500ms to get a new question.

1.3. Stakeholders

Role/Name	Contact	Expectations
Professors	ASW module professors	Get a great project which can be evaluated and shown in their github.
Developers	wiq_es6c team	Carrying out a full real project using all the knowledge obtained in the degree.
Responsible company	HappySw	Development of an experimental version of the Saber y Ganar quiz show.
Client	RTVE	Getting a Web App to promote its famous Saber y Ganar quiz show by letting their viewers enjoy a similar experience.
Main beneficiaries	Public users	Having a great time playing an interesting and easy to use quiz game.
Side beneficiaries	Wikidata	Obtain free promotion of their application and its ease to use in multiple projects.

Role/Name

Contact

Expectations

Professors

ASW module professors

Get a great project which can be evaluated and shown in their github.

Developers

wiq_es6c team

Carrying out a full real project using all the knowledge obtained in the degree.

Responsible company

HappySw

Development of an experimental version of the Saber y Ganar quiz show.

Client

RTVE

Getting a Web App to promote its famous Saber y Ganar quiz show by letting their viewers enjoy a similar experience.

Main beneficiaries

Public users

Having a great time playing an interesting and easy to use quiz game.

Side beneficiaries

Wikidata

Obtain free promotion of their application and its ease to use in multiple projects.

2. Architecture Constraints

2.1. Technical constraints

Constraint	Explanation
OS/Browser Independence	The project must be available to the maximum amount of users feasible. That includes support for mainstream OSs (Windows, Linux, MacOS) and browsers. (Chrome, Safari, Firefox, Edge)
Usage of REACT	The REACT JS framework will be used to develop the front-end of the project.
Docker	The application will operate within a Docker environment.
Version Control	In order for the project to be graded adequately, it must use GitHub as its version control system. The contributions of each team member and agreements reached must be easily traceable.
Wikidata	To generate questions, WikiData would be used as a knowledge base. Wikidata is a free and open knowledge base that can be read and edited by both humans and machines. Wikidata acts as central storage for the structured data of its sister Wikimedia projects, including Wikipedia, Wikivoyage, Wiktionary, Wikisource and others.
Continuous integration and delivery	The development must progress through frequent integration of small changes into the main branch. New features must be automatically deployed with ease. (In our case, using Docker)

Constraint

Explanation

OS/Browser Independence

The project must be available to the maximum amount of users feasible. That includes support for mainstream OSs (Windows, Linux, MacOS) and browsers. (Chrome, Safari, Firefox, Edge)

Usage of REACT

The REACT JS framework will be used to develop the front-end of the project.

Docker

The application will operate within a Docker environment.

Version Control

In order for the project to be graded adequately, it must use GitHub as its version control system. The contributions of each team member and agreements reached must be easily traceable.

Wikidata

To generate questions, WikiData would be used as a knowledge base. Wikidata is a free and open knowledge base that can be read and edited by both humans and machines. Wikidata acts as central storage for the structured data of its sister Wikimedia projects, including Wikipedia, Wikivoyage, Wiktionary, Wikisource and others.

Continuous integration and delivery

The development must progress through frequent integration of small changes into the main branch. New features must be automatically deployed with ease. (In our case, using Docker)

2.2. Organizational constraints

Constraint	Explanation
Time	The team has to complete the project during the semester.
Team size	The development teams must be composed of 5-7 members. In our case, the final team is composed of 6 members.
Budget	No budget is provided for the development, so any costs that may arise have to be covered by the development team.
Deliverables	Along the development process, the team must prepare deliverables set for certain dates, consisting of documentation and/or application prototypes.
Team meetings	In order to plan the development of the project, as well as to assign tasks and make design decisions, the team will participate in several meetings. These meetings can be done in and out of the classroom, as needed. A record must be created for every meeting, summarizing the progress made.
Project testing	The development team must test acceptable coverage of the project using different methods (unit testing, integration testing, acceptance testing… etc.)
Knowledge	There are many aspects of the development of this project that are foreign to some of us (usage of REACT, deployments, microsystems architecture… etc.) so some research is required to keep up.

Constraint

Explanation

Time

The team has to complete the project during the semester.

Team size

The development teams must be composed of 5-7 members. In our case, the final team is composed of 6 members.

Budget

No budget is provided for the development, so any costs that may arise have to be covered by the development team.

Deliverables

Along the development process, the team must prepare deliverables set for certain dates, consisting of documentation and/or application prototypes.

Team meetings

In order to plan the development of the project, as well as to assign tasks and make design decisions, the team will participate in several meetings. These meetings can be done in and out of the classroom, as needed. A record must be created for every meeting, summarizing the progress made.

Project testing

The development team must test acceptable coverage of the project using different methods (unit testing, integration testing, acceptance testing… etc.)

Knowledge

There are many aspects of the development of this project that are foreign to some of us (usage of REACT, deployments, microsystems architecture… etc.) so some research is required to keep up.

2.3. Conventions

Constraint	Explanation
Use of English	The totality of the project must be written in English, as to facilitate its understanding internationally.
Programming Language conventions	We ought to follow the conventions specific to the programming languages we’re employing.
Documentation format	The documentation must adhere to the Arc42 method, ensuring it is clear, simple, and effective.
Clean code	In order to ease the understanding and maintenance of the project, all code written must be organized, descriptive and easy to read.
Accesibility	The application should be user-friendly, allowing all individuals to navigate effortlessly, irrespective of any disabilities, ensuring inclusivity for all users.
Microservices	The application will be divided into microservices to facilitate its development.

Constraint

Explanation

Use of English

The totality of the project must be written in English, as to facilitate its understanding internationally.

Programming Language conventions

We ought to follow the conventions specific to the programming languages we’re employing.

Documentation format

The documentation must adhere to the Arc42 method, ensuring it is clear, simple, and effective.

Clean code

In order to ease the understanding and maintenance of the project, all code written must be organized, descriptive and easy to read.

Accesibility

The application should be user-friendly, allowing all individuals to navigate effortlessly, irrespective of any disabilities, ensuring inclusivity for all users.

Microservices

The application will be divided into microservices to facilitate its development.

3. System Scope and Context

3.1. Business Context

Entity	Input	Output
User	App usage and experience.	The user will introduce and send its credentials every time it creates a new account or logs into an existing one.
WebApp	User data and input, as well as external API calls received.	Handled API calls or calls to their respective microservice in order to be processed and answered.
Wikidata	Calls to Wikidata’s REST API asking for certain data, which will be used to construct the questions.	Said data. Its format may vary, according to the necessities of the questions generator.

Entity

Input

Output

User

App usage and experience.

The user will introduce and send its credentials every time it creates a new account or logs into an existing one.

WebApp

User data and input, as well as external API calls received.

Handled API calls or calls to their respective microservice in order to be processed and answered.

Wikidata

Calls to Wikidata’s REST API asking for certain data, which will be used to construct the questions.

Said data. Its format may vary, according to the necessities of the questions generator.

3.2. Technical Context

4. Solution Strategy

4.1. Technology Decisions

In order to develop the application and adhere to the constraints, we selected the following technologies:

ReactJS: JavaScript library that streamlines the development of graphical interfaces for web applications.
GitHub: Platform offering remote repository services for project development, task management, and version control.
MongoDB: A non-relational, document oriented database selected to oversee storage of diverse application contents, with each microservice possessing its dedicated database.
NodeJS: Facilitates efficient management of asynchronous events, notably beneficial for scalable network applications and database administration.
Docker: Employed for seamless deployment of the application environment.

4.2. Top-level Decomposition

4.2.1. Diagramming tools

We will use PlantUML and UMLet for creating the documentation’s diagrams.

4.3. Approaches to Achieve Top Quality Goals

Quality Goal	Scenario	Solution Approach
Scalability	The application’s design must accommodate changes effortlessly throughout its lifecycle.	Employing a microservices approach to minimize code repetition and enhance understanding of application distribution, ensuring future scalability.
Usability	Seamless execution of all application functions is crucial for user satisfaction.	Optimizing usability through the utilization of React.
Maintainability	Application architecture must facilitate seamless addition or modification of functionalities with minimal code changes.	Implementing design patterns and adhering to code conventions to ensure clean and maintainable code. Additionally, prioritizing testing during development for long-term maintainability.

Quality Goal

Scenario

Solution Approach

Scalability

The application’s design must accommodate changes effortlessly throughout its lifecycle.

Employing a microservices approach to minimize code repetition and enhance understanding of application distribution, ensuring future scalability.

Usability

Seamless execution of all application functions is crucial for user satisfaction.

Optimizing usability through the utilization of React.

Maintainability

Application architecture must facilitate seamless addition or modification of functionalities with minimal code changes.

Implementing design patterns and adhering to code conventions to ensure clean and maintainable code. Additionally, prioritizing testing during development for long-term maintainability.

4.4. Organizational Decisions

We’ve established the following organizational guidelines:

Language: Adhering to international standards, the project, encompassing code and documentation, will be developed in English as the primary language.
Issues: All deliberations will be documented as issues on GitHub.
GitHub Projects: Employing this tool, we’ll plan the application’s development process, utilizing GitHub’s integrated features for efficient project management in accordance with AGILE methodology.

5. Building block view

5.1. Level 1: Overall System’s whitebox

5.1.1. Motivation

This level shows how the application will work internally in generaly. The client, WebApp, access to the different services provided by the microservices which make up the program.

5.1.2. Contained Building Blocks

Name	Description
User	Client of the application which will interact with it.
WIQ App	System developed to be used by the users. The games will be based on the information obtained from WikiData.
WikiData	Service external to the application from which the application questions will be obtained. Wikidata is a collaboratively edited multilingual knowledge graph hosted by the Wikimedia Foundation.

Name

Description

User

Client of the application which will interact with it.

WIQ App

System developed to be used by the users. The games will be based on the information obtained from WikiData.

WikiData

Service external to the application from which the application questions will be obtained. Wikidata is a collaboratively edited multilingual knowledge graph hosted by the Wikimedia Foundation.

5.2. Level 2

5.2.1. Motivation

WiQ application is the general structure of a system in which users will have the possibility to play a video game implementation of the popular RTVE programme, "Saber y Ganar".

5.2.2. Contained Building Blocks

Name	Description
Web App	Layer in which the user will interact directly and which will connect with the different services.
Gateway Service	Microservice that redirects the requests from the WebApp to its corresponding microservices
Questions Service	Microservice to generate the questions used by the application from WikiData
Game Service	Microservice that implements the quiz game
Question Historic Service	Microservice that stores the generated questions for later consultation
User Statistics Service	Microservice that stores the statistics of the games played by the user.
UserAuth Service	Authentication microservices that allows the user to register and log in.

Name

Description

Web App

Layer in which the user will interact directly and which will connect with the different services.

Gateway Service

Microservice that redirects the requests from the WebApp to its corresponding microservices

Questions Service

Microservice to generate the questions used by the application from WikiData

Game Service

Microservice that implements the quiz game

Question Historic Service

Microservice that stores the generated questions for later consultation

User Statistics Service

Microservice that stores the statistics of the games played by the user.

UserAuth Service

Authentication microservices that allows the user to register and log in.

5.3. Level 3

5.3.1. Motivation

To display the inner architecture of the different microservices, as well as how do their components interact with themselves and with other components from other microsystems. All microservices follow the MVC architectural pattern, to the exception of those who have no UI to handle.

5.3.2. Contained Building Blocks

Name	Description
User Service	It retrieves the data from new users and registers them in the database.
Auth Service	It retrieves the data from returning users and checks if they are in the database.
Game Controller	Handles all the game’s logic; where the user input’s processing takes place. It can request questions to the Questions Microservice, and also gather user statistics, to later be sent to the User Statistics Controller.
Questions Historic Controller	Receives the generated questions, and sends them to the database. Besides, it also handles recovering them from the database and sending them where they are needed. (e.g: as response from an API call, or to the UI)
User Statistics Controller	Receives various information about the player’s performance in the match. There, some processing may occur before storing it in the database. Also handles retrieving the information and sending it where it’s needed (e.g: as response from an API call, or to the UI).
Questions Generator	Contains the required templates and proceedings to construct questions. In order to do so, it delegates the Wikidata querying to the Wikidata extractor. It gets the data through the database so when the data is returned, the question is formulated through templates.
Wikidata Extractor	Handles extraction and formatting of Wikidata’s output. It’s queries must cover all necessary information in order to construct the question(s), including not only the correct response, but also believable and coherent “decoy answers”. It stores the data retrieved on the database.

Name

Description

User Service

It retrieves the data from new users and registers them in the database.

Auth Service

It retrieves the data from returning users and checks if they are in the database.

Game Controller

Handles all the game’s logic; where the user input’s processing takes place. It can request questions to the Questions Microservice, and also gather user statistics, to later be sent to the User Statistics Controller.

Questions Historic Controller

Receives the generated questions, and sends them to the database. Besides, it also handles recovering them from the database and sending them where they are needed. (e.g: as response from an API call, or to the UI)

User Statistics Controller

Receives various information about the player’s performance in the match. There, some processing may occur before storing it in the database. Also handles retrieving the information and sending it where it’s needed (e.g: as response from an API call, or to the UI).

Questions Generator

Contains the required templates and proceedings to construct questions. In order to do so, it delegates the Wikidata querying to the Wikidata extractor. It gets the data through the database so when the data is returned, the question is formulated through templates.

Wikidata Extractor

Handles extraction and formatting of Wikidata’s output. It’s queries must cover all necessary information in order to construct the question(s), including not only the correct response, but also believable and coherent “decoy answers”. It stores the data retrieved on the database.

6. Runtime View

6.1. User plays a match. Only one question batch is needed.

In circumstances in which few questions are needed for the game, it may be possible to extract all of them in a batch without affecting performance and response times. Besides, extracting them this way opens up the possibility of using multiple threads to gather the data, greatly increasing performance. However, if the querying times are too high, this strategy may cause great delays while loading the game. A possible alternative is explained below:

6.2. User plays a match. An example of dynamic question generation.

In cases where a lot of questions are needed, or wikidata querying has a great impact on performance, this alternative may prove to be convenient. By distributing the data fetching along the entire match, bottlenecks on performance will be reduced. Depending on the system load, or even on client device’s specifications, batch sizes may vary adapting to maintain responsiveness.

6.3. User consults its game statistics.

6.4. User consults questions used in games.

7. Deployment View

7.1. Infrastructure Level 1

In addition to what is shown in the diagram, we will also use Graphana and Prometheus during the production stage as code monitoring systems.

Motivation: Despite our initial goal being to run the application with Docker in an Azure VM, as we were running out of Azure Credits, we decided to switch to an Oracle VM. However, during the production stage, each contributor will deploy the project locally. Final product will be deployed in http://wiq.sytes.net/ (if that does not work, try http://158.179.212.42:3000/).
Quality and/or Performance Features: Previously, we had an Azure VM with 2 GiB RAM and 1vCPU. When we decided to change to the Oracle VM, we also improve our resources, as it was free. Finally, our Oracle VM has 24 GiB RAM and 4vCPU. Each microservice has its own container. There are also two databases, one for the Question Generator and Wikidata Extractor services, and another one for the rest of the containers which may need it.

8. Cross-cutting Concepts

8.1. Domain model

9. Architecture Decisions

Architecture decisions	Advantages	Disagvantanges
Use of JavaScript	It is a language we have all used.	It is a complex language that can cause us problems while other simpler languages could make our work easier.
Use of React	It is the most used JavaScript framework and there is a lot of documentation about it.	All of us in the team will have to learn how to use it because we have never worked with it.
Use of MongoDB	Being a non-relational database, it is easier to use. In addition, it is used by large telecommunications companies.	Non-relational databases are the ones with which we have the least experience.

Architecture decisions

Advantages

Disagvantanges

Use of JavaScript

It is a language we have all used.

It is a complex language that can cause us problems while other simpler languages could make our work easier.

Use of React

It is the most used JavaScript framework and there is a lot of documentation about it.

All of us in the team will have to learn how to use it because we have never worked with it.

Use of MongoDB

Being a non-relational database, it is easier to use. In addition, it is used by large telecommunications companies.

Non-relational databases are the ones with which we have the least experience.

10. Quality Requirements

To describe the quality requirements that the game will have, we will use quality scenarios. Quality scenarios describe the action to be performed by the user or the system (stimulus) in order to generate a response to the interaction.

10.1. Quality Tree

10.2. Quality Scenarios

Quality scenarios, also known as use cases, are detailed descriptions of situations in which a user interacts with a system and describe the expected outcomes along with the conditions of the environment in which the interaction occurs.

Quality goal	Motivation	Usage Scenarios	Priority
Usability	The ease of interaction with the user should be enhanced through intuitive and simple interfaces to improve the user experience.	Users will be able to understand how the game works thanks to the clarity of its rules and ease of navigation.	High
Diversity	The questions provided by the application will be of various topics.	The user must correctly answer questions on different topics. This will improve the user experience and maintain the interest of the participants.	High
Fiability	The game must be played without errors.	The answer determined as correct for each question by the system shall be the one that is actually correct.	Medium
Interactivity	The user must answer a series of questions in which the user must select the correct answer in each case.	For each of the questions, the user must select the correct answer from those provided by the system.	Medium
Privacy	In order to be able to play, the user must log in to the application.	Only the user who created/owns the account will have access to it (unless he/she gives someone else his/her credentials).	Low

Quality goal

Motivation

Usage Scenarios

Priority

Usability

The ease of interaction with the user should be enhanced through intuitive and simple interfaces to improve the user experience.

Users will be able to understand how the game works thanks to the clarity of its rules and ease of navigation.

High

Diversity

The questions provided by the application will be of various topics.

The user must correctly answer questions on different topics. This will improve the user experience and maintain the interest of the participants.

High

Fiability

The game must be played without errors.

The answer determined as correct for each question by the system shall be the one that is actually correct.

Medium

Interactivity

The user must answer a series of questions in which the user must select the correct answer in each case.

For each of the questions, the user must select the correct answer from those provided by the system.

Medium

Privacy

In order to be able to play, the user must log in to the application.

Only the user who created/owns the account will have access to it (unless he/she gives someone else his/her credentials).

Low

11. Risks and Technical Debts

Risk	Consequence
Knowledge of REACT	It is a framework that no team member has used before. Therefore, we have all had to learn how to use it.
Internal group conflicts	Lack of free time for team members makes group work difficult.

Risk

Consequence

Knowledge of REACT

It is a framework that no team member has used before. Therefore, we have all had to learn how to use it.

Internal group conflicts

Lack of free time for team members makes group work difficult.

12. Testing

12.1. Unit tests

Unit testing is fundamental to ensure application working as intended. Our goal is to have a minimun of 80% of code coverage. Jest is used as the testing framework due to its simplicity and speed.

12.2. Acceptance tests

As for acceptance tests, we currently have five scenarios:

Registering a new user
- Given An unregistered user
- When I fill the data in the form and press submit
- Then A confirmation message should be shown on the screen
Login with an existing user
- Given A registered user
- When I fill the data in the form and press submit
- Then Menu screen is displayed
Playing classic game with default settings
- Given A logged user
- When I play with configured settings(2 questions 2 answers)
- Then 2 questions with 2 answers are asked
Playing calculator game with default settings
- Given A logged user
- When I press play button
- Then questions with 4 answers are displayed till time finishes
Checking history
- Given A logged user
- When I go to History section
- Then games with questions and answers are shown

12.3. Load Tests

For load tests, we have been using Gatling with Firefox proxy to simulate a real user experience.

Scenario	t <800ms	t ∈ [800ms - 1200ms)	t >= 1200ms	Failed
2 new users per second(peak: 59 users)	100%	0%	0%	0%
Peak 1000 users	67%	1%	26%	5%
Peak 1500 users	64%	0%	16%	20%
Peak 2000 users	66%	0%	11%	23%
Peak 3000 users	49%	8%	12%	31%

13. Monitoring

We have been using Grafana and Prometheus for monitiring the entire application.

Grafana dashboard currently shows the following metrics related to requests:

Number of requests
Number of failed requests
Amount of time to process a request

Figure 1. Requests Monitoring

14. Glossary

Term	Definition
MongoDB	NoSQL database system that, instead of storing data in tables as a relational database does, stores data in JSON-like documents with a flexible schema.
REACT	Open source JavaScript library developed by Facebook to build interactive and responsive user interfaces (UI). It is one of the most popular tools for modern web application development.
Usability	Ease with which users can interact with a product, system or application to achieve their objectives effectively, efficiently and satisfactorily.
Dynamic question generation	There may be circumstances where pre-generating the questions isn’t feasible. So instead, questions can be generated while the user is playing the game and answering questions.
Decoy answer	For questions that offer multiple options to select the correct answer from, it will be necessary to generate believable incorrect answers, that match the topic and theme of the question. For example, when asking about the longest river in Egypt, along with the correct answer (The Nile) some other river names of the country could be chosen for alternatives.
Question template	General structure of a question, which can or cannot transcend topics. For example, valid templates for questions could be: "What’s the tallest mountain in <country>?" "What is <concept>?" "Who invented <x>?"

Term

Definition

MongoDB

NoSQL database system that, instead of storing data in tables as a relational database does, stores data in JSON-like documents with a flexible schema.

REACT

Open source JavaScript library developed by Facebook to build interactive and responsive user interfaces (UI). It is one of the most popular tools for modern web application development.

Usability

Ease with which users can interact with a product, system or application to achieve their objectives effectively, efficiently and satisfactorily.

Dynamic question generation

There may be circumstances where pre-generating the questions isn’t feasible. So instead, questions can be generated while the user is playing the game and answering questions.

Decoy answer

For questions that offer multiple options to select the correct answer from, it will be necessary to generate believable incorrect answers, that match the topic and theme of the question. For example, when asking about the longest river in Egypt, along with the correct answer (The Nile) some other river names of the country could be chosen for alternatives.

Question template

General structure of a question, which can or cannot transcend topics. For example, valid templates for questions could be: "What’s the tallest mountain in <country>?" "What is <concept>?" "Who invented <x>?"