1. Introduction and Goals

RTVE has hired the company HappySw, composed of students from the Oviedo School of Software Engineering, to develop a new game-show like web application. This application will be called KiWiq, where users will be able to register and log in to play. The application will consist of answering questions of different types generated with Wikidata. Questions answered correctly will count towards statistics that are displayed in a ranking.

1.1. Requirements Overview

  • The system shall provide non-registered users with the option to sign up.

  • The system shall provide unidentified users with the option to log in.

  • The system shall only be used by registered users.

  • The system shall have a game mode with a 9 rounds.

  • In each round, the system shall fetch and display a question.

  • In each round, the system shall display four answers, with only one being correct.

  • The system shall offer registered users access to the number of games they have played.

  • The system shall offer registered users access the number of questions they have answered correctly.

  • The system shall offer registered users access the number of questions they have answered incorrectly.

  • The system shall offer registered users access the ranking of the game.

  • The system shall set a time limit for registered users to respond to each question.

See the complete functional requirements in the Annex of the documentation.

1.2. Quality Goals

Goal Description

Functional suitability

The system shall fulfill its intended purpose effectively and efficiently, allowing users to register, log in, play the quiz, and access their user statistics.

Reliability

The system should be reliable in generating questions from Wikidata, ensuring that questions are accurate and diverse. The system shall handle user registrations, logins, and game data storage without errors.

Availability

The system shall be available 99% of the time a user tries to access it.

Maintainability

The system shall be designed and implemented in a way that facilitates easy maintenance and updates.

Performance efficiency

The system shall deliver optimal performance, ensuring responsive interactions for users. The automatic generation of questions from Wikidata and the real-time gameplay shall be efficient. The system shall handle 1000 concurrent users.

Security

The system shall prioritize user data security. It shall implement robust authentication mechanisms for user registration and login. The API access points for user information and generated questions shall be secured with proper authorization.

Usability

The system shall provide a user-friendly interface, making it easy for users to register, log in, and play the game. The system learning time for a user should be less than 4 hours.

Compatibility

The system shall be compatible with various web browsers and devices, ensuring a seamless experience for users regardless of their choice of platform. It has to be well-optimized for different screen sizes and functionalities.

1.3. Stakeholders

Role/Name Expectations

RTVE

To have a new application for a quiz game.

HappySw

Develop a good application that fulfills the requirements expected by the client.

Registered user

To play with an entertaining and easy-to-use application. An application with which the user learn about different topics.

Wikidata

Being able to offer service allowing people to use the data through the API.

2. Architecture Constraints

The application must be developed according to some constraints that were defined by the client. These constraints are meant to be the cornerstones of our project as they are mandatory and provide a baseline to work on. The following tables will define the constraints.

Technical constraints

Constraint

Description

Web accesible front-end

The application must be possible to access through a web browser

Use of WikiData

The system must make use of WikiData to gather information

Automatic questions

The questions prompted by the game must be generated automatically

Organizational constraints

Constraint

Description

Weekly meetings

Each class week, the team must meet and discuss the development

Use of GitHub

GitHub must be used to communicate and keep track of the development process

Deliverables

The project will be reviewed by the professors on three occasions

Conventional constraints

Constraint

Description

Documentation in Arc42

The documentation must follow the Arc42 template

Wireframes

wireframe Root
Figure 1. Root Wireframe
wireframe About
Figure 2. About Wireframe
wireframe SignUp
Figure 3. Sign up Wireframe
wireframe SignIn
Figure 4. Sign in Wireframe
wireframe Dashboard GameModes
Figure 5. Dashboard game modes Wireframe
wireframe Dashboard customGameMode
Figure 6. Dashboard custom game mode Wireframe
wireframe Dashboard UserPanel
Figure 7. Dashboard user panel Wireframe
wireframe Dashboard ResumeGame
Figure 8. Dashboard resume game Wireframe
wireframe Rules
Figure 9. Rules Wireframe
wireframe Game
Figure 10. Game Wireframe
wireframe Statistics
Figure 11. Statistics Wireframe
wireframe Menu
Figure 12. Menu Wireframe
wireframe Results
Figure 13. Results Wireframe

3. System Scope and Context

3.1. Business Context

C4 Level 1 Business context diagram
Figure 14. Overall view of the business context

The player interacts with the Kiwiq system, which will communicate with the WikiData API through REST HTTP calls using SPARQL for the queries. It will ask the API for information that will later be used for generating the questions that will be shown to the player. This information will come in the form of text or images.

3.2. Technical Context

C4 Level 2 Container context diagram
Figure 15. Overall view of the technical context

The Kiwiq system will be deployed together in the same server and contains different modules:

  • Kiwiq Proxy: When interacting with the server, an nginx proxy will be tasked with redirecting the queries to the petitions to the Kiwiq client will also be deployed on a nginx web server.

  • Kiwiq Client: This client will be served to the client and communicates with the API through HTTPS REST calls and exchanges information through JSON objects. The client will be developed in React and Javascript and is deployed via a nginx server.

  • Kiwiq REST API: The Kiwiq REST API will be run as a .jar file on the server and connect to a database running on a PostgreSQL docker container. The connection layer between the SpringBoot API and the database will be JPA.

  • Kiwiq database: In the database the questions and answers generated by the Question Generator module will be stored, written in Java and using JPA as a connection layer. The DBMS is PostgreSQL.

  • Question generator: The Question Generator will also use the WikiData REST API to retrieve information to generate questions. It will generate the questions by connecting to the Wikidata REST API through HTTPs calls and passing a SPARQL query to retrieve the data that will later be used in the question generation. It is written in Java and uses JPA

4. Solution Strategy

What follows is a summary of our solution’s main decisions, and the approach we decided to use to create the system.

4.1. Technologies breakdown

Regarding the technologies, we decided to use the following ones:

  • React for the frontend, using the Chakra UI component library. Although the preferred way to use React is currently through a framework, we preferred this approach due to this being many of us first time using it, as well as a lack of experience using any framework in any of us.

    • As a consecuence of this, pure JavaScript is being used due to React 18 not supporting Typescript 5.

  • PostgreSQL as DBMS to store the information. We nearly immediately discarded using MongoDB due to many of us not having experience with it, and those who did, preferred relational databases. Many modern DBMS also include either JSON or JSONB data types, so using a DBMS whose main appeal is JSON and not many of us have experience with did not sit well with us.

  • Java SpringBoot 3 for the backend/API, it being a language we are all comfortable with. The server will easily support multithreading if needed due to SpringBoot being an abstraction over servlets, something we would be able only to simulate if we used Node.js as it uses a single-threaded event loop.

  • Java for the Question Generator process, due to the ease for connecting with the DB via JPA and our familiarity.

4.2. Organizational breakdown

Currently, we have been meeting twice a week, but that may change in the future. Most, if not all of us, were present for these meetings, and relevant decisions were also discussed on the side and between members, as well discussions related to opinions on some matter. Some of these meetings took place in person while others took place on a Discord Server.

We also have a Whatsapp community for the team, and a Notion wiki.

4.3. Important quality-related decisions

Quality attribute pursued Solution chosen

Privacy

All stored password will be hashed, both client-side and server-side, to avoid password disclosure. The client-side password is also intended to prevent password discoverage in case it is a repeated one.

Robustness

Currently, all validations will take place server-side to avoid not being properly taken care of due to JavaScript desactivation, such as when using the NoScript plug-in or sending a request via cURL.

Availability

Since Wikidata has a 1-minute limit related to the API, the backend will start querying it upon start and fill the database with questions to increase speed and thus improve user experience. This makes it so we are not dependent on the Wikidata API to be up for our system to work

4.4. Workflow

4.4.1. Team Workflow:

We have divided ourselves in teams related to our own areas of expertise, but those divisions are indicative, and frontend teams may review or comment PRs if they wish, or vice versa. The frontend team may also ask input from the backend team if they wish, and the backend team may do the same.

Separation of the group into teams though, tends to reflect on the final structure of the project, as stated in Conway’s law. To prevent this, we employed the use of API definition tools such as Swagger to make the integration of frontend and backend not dependent on having members of both teams present. Conway’s law still affected in other aspects, though.

Meetings are also organized each week so as to keep the team updated, decide what should be worked on next and discuss any problems that may arise from implementation.

4.4.2. Coding workflow:

Pair programming was implemented in the backend team, which helped immensely to shorten the existing knowledge gaps and achieve a consistent coding style. This also reduced the number of PRs that needed to be validated, since having 2 people write the code increases its reliability.

4.4.3. Git workflow:

Trunk Based Development was used as source-control branching model, using develop as our trunk branch, and merging into master for tested releases.

For commit messages we used the specification on https://www.conventionalcommits.org/en/v1.0.0/ so as to keep them consistent.

For branch naming we used a variation of Conventional Commits commit naming, naming branches with its purpose first (docs,feat,fix…​).

Pull Requests were the main method of contributing to the project, these needing to be validated by at least 2 other teammates before merging to ensure code quality.

4.5. Code Style/Structure

Regarding the code style, we must make two important distinctions: the frontend and backend. In the latter, we will mainly use Object-Oriented Programming because our language of choice is Java, which strongly favours it. Regarding the former, it will be more of a case-by-case approach, as for instance, OOP-oriented React is deprecated in favor of a functional approach, but sometimes we may need OOP’s strengths.

4.5.1. Backend

API

In the backend, the structure will be that of a typical Maven project, using different packages for different modules of the project:

  • The auth package is used for authentication related endpoints and configuration.

  • The game package is used for game related endpoints and logic

  • The questions package is used for question related endpoints and logic

  • The statistics package is used for statistics related endpoints and logic

  • The commons package is used for common logic that may be used among different packages, such as utils classes or user logic.

In each of this packages, the following structure is followed:

  • The dtos package stores Data Transfer Objects, used for sending or receiving data

  • The mappers package stores classes used for mapping from models to DTOs or vice versa.

In our Spring Boot project the following structure is found in each of our modules, following a Domain Driven Design approach:

  • A Controller handles the requests done to our API.

  • A Service handles the retrieval of the Models from the database using Repositories.

  • A Model is retrieved and handles its domain logic.

  • A Repository is used for retrieving Models from the database.

A crucial part of the design is that the models are the ones handling the logic, as described in Jimmy Bogard’s talk: https://www.youtube.com/watch?v=UYmTUw5LXwQ

In regard to testing, a Test First approach was employed when possible, and the logic of the Models and the Services was tested, as well as the responses given by the Controllers in different situations.

Question Generator

In the question generator, the structure is simple, using three packages to structurize the code:

  • The model package is used to store the classes that model the questions and answers.

  • The repositories package, where classes related to storing the questions and answers in the DB can be found.

  • The templates package, where all the classes where the questions are created by using calls to wikidata can be found.

4.5.2. Frontend

  • In the frontend, the structure will be quite different:

    • The src/components will contain single components which we may reuse.

    • The src/pages will contain the endpoints and will follow a simple structure. For instance, given a /statistics/personal and a /statistics/general endpoints, both will be independent React components that will return the page and be placed under the src/pages/statistics folder.

5. Building Block View

5.1. Whitebox Overall System (C4 Level 1)

Overview Diagram

Business context diagram
Figure 16. Overall view of the business context
Motivation

This will be the general sketch of the elements interacting inside the application, including the external elements that will include the application.

Contained Building Blocks

  • Player: This is the user that will be playing with our application. They will need to be authenticated to be able to play.

  • Kiwiq Application: This is the main application that will reproduce how the game will work. This part will be more detailed in the following parts.

  • WikiData API: This is an external API, which will provide us with the information to produce the questions.

Important Interfaces

The user will interact with the system via the web client, which will allow them to play games. The system will then interact with the WikiData API via the question generator module by doing HTTPs requests with SPARQL queries in them.

5.2. Container Diagram (C4 Level 2)

Container diagram
Figure 17. Overall view of the container context
Motivation

An inner view on the Kiwiq Application and its components inside. How the Kiwiq application will be structured inside and its main components.

Contained Building Blocks

  • Kiwiq Proxy: When interacting with the server, an nginx proxy will be tasked with redirecting the queries to the petitions to the Kiwiq client will also be deployed on a nginx web server.

  • Kiwiq Client: This is the connection between the user and the application. It will allow the users to play the WIQ game. This part will be developed in React with Typescript for its clear component structure, simplified code quality and separation of concerns.

  • Kiwiq REST API: This is the part responsible for managing the users that log into the application, managing also the logic of the game and sending the request to the Wikidata API for the question generation. This part is going to be developed in SpringBoot due to its foundations on the Java programming language, which is the language that the developers find the easiest to develop in.

  • Question Generator Module: This component is in charge of everything related with the questions. It retrieves the information from WikiData QS and stores it in the WIQ Database, which later is queried for questions and answers from the REST API.

  • Kiwiq Database: This is where the most important data is going to be stored. Such as, users questions and other game info that will be specified in the future. The database we chose to use is PostgreSQL, since it is compatible with Docker and it’s an object-relational kind of database, which is easier for the developers to use. Another alternative would’ve been to use MySQL.

Important Interfaces

We are connecting the front end with the back end via a REST API, using HTTPs requests. Also, the Question Generator Module communicates with WikiData QS this way. The Question Generator Module connects to the WIQ DataBase through JPA, where it stores the questions that will later be used by the REST API.

5.3. Component Diagram (C4 Level 3)

Component diagram
Figure 18. Overall view of the component context
Motivation

An inner view on the Kiwiq API and its components inside. How the Kiwiq API will be structured inside and its main components.

Contained Components

  • Authentication module: Tasked with handling of the login and register of the users as well as restricting the user access.

  • Game module: Tasked with handling the games allowing for creating new games, starting rounds, sending answers and updating statistics.

  • Question module: Tasked with handling the questions, allowing to get any question from the system, as well as retrieving them from the database.

  • Statistics module: Tasked with handling the statistics, allowing to check the top 10 users in the system, as well as saving the statistics.

All the previously mentioned modules also use a common module named commons, that contains logic common to all of them, like the user handling or some util classes.

6. Runtime View

Here we can see what the main workflow of main parts of the project.

6.1. Sign Up

Sign up diagram

6.2. Login

Login diagram

6.3. General Game’s life cycle

  • This diagram shows how should the application behave for an expected normal case scenario.

Game’s sequence diagram

6.4. Question Generation

Question generation diagram

7. Deployment View

Deployment diagram

7.1. Infrastructure Level 1

Motivation

The above diagram shows the initial version of the architecture and the division between its components. We will be using a simple client-server architecture, and the server will be querying Wikidata for the questions. By separating the architecture in this way we enforce a clear separation between the client/frontend and the server/backend, which benefits the system as a whole because so long the common API is implemented, the implementations themselves shall remain interchangeable.

Quality and/or Performance Features

As stated before, we consider the main advantage of this architecture the interchangeability of the components. There remain details to be scratched out though, but this is still an initial version.

Mapping of Building Blocks to Infrastructure

  • The webapp/frontend/client is contained within the webapp subfolder.

  • The API/backend is contained within the quiz-api subfolder.

    • The database will be generated on deployment.

    • Wikidata is an external component, so although it is an important part of the deployment architecture, it is something we do not have access to changing.

    • The grafana config is found within the monitoring/grafana subdirectory

    • The prometheus config is found within the monitoring/prometheus subdirectory

  • The question generator is a separate component that will be deployed on the server only at the beginning of the system. It is contained within the questiongenerator subfolder.

  • The configuration for the proxy container is found within the proxy_conf subfolder.

7.2. Infrastructure Level 2

7.2.1. Frontend/Client

This component is self-contained and does not require much explanation.

7.2.2. API/Backend

API Deployment diagram
Server

Our main idea is that the server will be a self-contained .jar file with all the dependencies required within. It will communicate with the database to retrieve the questions.

Database

The database will contain the data used by the system. Therefore, it will contain user data, as well as the data related to the questions and their answers.

Question Generator

The question generator will be run only at the beginning of the application. It will connect with Wikidata using SPARQL to generate questions and answers and store them in the database. This question generation will generate all the questions used by the application at once. It could be run again to generate new questions if they are added.

8. Cross-cutting Concepts

Domain Model

This is the diagram that includes the domain model of the backend.

Concept Domain Model

Class

Explanation

Question

The model of the questions, has a type to specify if it is text or image. Stores both right and wrong answers

User

The people using the application, they have statistics and take part in a ranking to compete

Answer

Models each possible answer, created to reuse answers that are common to different questions, as well as distractors

Game

It is created when the user starts a game and includes the rounds that the user has to answer

Statistics

Stores information about the amount of correct and wrong answers that each user has answered

Enum

Explanation

QuestionCategory

Category for the question

QuestionType

Type of the question (if it shows a text or an image etc)

AnswerCategory

Category of the answer (used also for getting distractors)

GameMode

Game mode for the game
Question Generator

The Question Generator is an important part of our application, it is already briefly described in Section 6, but more insight is given here.

The Question Generator module is written in Java and connects via HTTP with Wikidata query service. It follows a template design pattern where each Java class is responsible for generating the questions and answers. The query is ran against Wikidata and it returns a text in JSON format that is processed into the question and answers, which are later stored in the DB.

Architecture and design patterns

We decided to use a React based frontend with BootSpring for the backend, which will follow the model view controller pattern to make the code clear.

User Experience

As this is a game, the focus must be in user experience so players can have an enjoyable experience, for achieving this, the response time should be as low as possible and the interfaces should be intuitive and beautiful.

Safety and Security concepts:

Authentication is done in SpringBoot3. Passwords must be hashed both in client and in API to ensure as much security as possible.

Robustness:

It is desired to make the application as independant as possible from Wikidata. This way, if it is down our application can still manage to be available for our users. In order to archieve this, we will implement two modules regarding questions, one for retrieving it from Wikidata and storing it in our own DB and another for getting questions from it.

Development concepts:

Our code will be deployed within an Azure’s Virtual Machine using continuous integration.

Under-the-hood:

Regarding Data persistence, our project has a PostgreSQL DB, which stores information about users, statistics, games, answers and questions.

9. Architecture Decisions

During the application development process, decisions had to be made as issues emerged. The most interesting design decisions are reflected in this architectural records:

9.1. Main webapp technology

Date Recorded: 01/02/2024

Scope: frontend, webapp

Description: Offers a powerful combination of performance, flexibility, and developer experience, making it a popular choice for building modern web applications. One of the members of the group has already worked with it in the past. It allows us to build a good user interface for the application.

Decision taken: The frontend team has agreed to use React or a React framework, as all members agree they are not up to the task of maintaining a personalised stylesheet.

9.2. React technology to be used

Date Recorded: 01/02/2024

Scope: frontend, webapp

Description: The frontend team has been discussing whether to use React or a React framework like Next.js as it is the currently recommended option.

Decision taken: The frontend team has agreed to use a pure React-based approach due to most members not having any kind of prior experience with React and those that do have it are do not feel confident enough in their skills.

9.3. Main backend technology

Date Recorded: 01/02/2024

Scope: backend, API

Description: The backend team wants to deprecate the given Node.js microservices system in favour of a monolithic Springboot-based approach. This is mainly due to only one member having prior experience in Node.js development. No members support keeping the current approach, and when asked if SpringBoot would allow a possible microservices constraint, a member of the backend team has stated that a proper-developed SpringBoot application should be easy to divide between different microservices.

Decision taken: The backend team has agreed to use SpringBoot and JPA for the backend.

9.4. Replacing MongoDB with a relational DBMS

Date Recorded: 01/02/2024

Scope: database

Description: A member of the backend has proposed the replacement of MongoDB as DBMS, with PostgreSQL replacing it. A member of the frontend team has supported it, remarking modern DBMS have built-in JSON support if needed. Other members of the backend team have stated their agreement, as many of them do not have prior experience with MongoDB and prefer relational databases.

Decision taken: The team has agreed to drop MongoDB and to use PostgreSQL.

9.5. Libraries for React

Date Recorded: 09/02/2024

Scope: frontend, webapp

Description: To enhance the efficiency and effectiveness of our development process, we’ve taken proactive steps to incorporate specific libraries into our project. These carefully chosen libraries, meticulously outlined in detail within issue #16.

Decision taken: The team has agreed to use Chakra UI as the main library for the frontend.

9.6. HTTP/2 and HTTPS

Date Recorded: 23/02/2024

Scope: security

Description: To improve security we have decided to make HTTP/2 and HTTPS one of the main requirements in our project as can be seen in issue #51.

Decision taken: The team has agreed to use HTTP/2 and HTTPS.

9.7. Architecture of the question generator process

Date Recorded: 03/03/2024

Scope: backend, question generator

Description: The question generator must be a part of our application, but different to the webapp or the API, it doesnt need to be running on a loop. It just needs to be run once everytime we want to load or update questions. Implementing it in the API module would result on more coupling but not duplicating code for the model. On the other hand, implementing it in a new module would make the application cleaner and easier to change.

Decision taken: The team has decided to implement the question generator as a separate module of our application.

9.8. Connect to the database with the question generator

Date Recorded: 10/03/2024

Scope: backend, question generator, database

Description: The backend team has been discussing whether to use JPA or JDBC to connect to the database with the question generator. When researching JPA it was found that although it is easier to use since the models already exist in our API, the models cannot be used from a different package, which makes us duplicate code as we do not have time to research another way of implementing it. On the other hand, JDBC would be more complex to use and does not have the same level of flexibility as JPA.

Decision taken: The team has agreed to use JPA to connect to the database with the question generator. Although this will generate duplication of code in the models, it should be manageable due to the small size of the project. This will be recorded as technical debt and new approach should be looked into if the project grows in size.

9.9. Workflow of the game logic

Date Recorded: 19/03/2024

Scope: backend, game logic

Description: The game logic must be implemented in the backend, since implementing it in the frontend would make it very dependent on performance and prone to allowing cheating and exploits. The questions will be served to the frontend each round but then validated in the backend, to prevent cheating. Points will also be automatically calculated in the backend.

Decision taken: The team has agreed to implement the game logic in the backend to make it more robust and prevent cheating.

10. Quality Requirements

10.1. Quality Tree

This quality tree is a high-level overview of the quality goals and requirements. The Quality tree uses "quality" as a root while the rest of the quality categories will be displayed as branches.

Quality Tree

10.2. Quality Scenarios

To obtain a measurable system response to stimulus corresponding to the various quality branches outlined in the mindmap, we will use quality scenarios. Scenarios make quality requirements concrete and allow to more easily measure or decide whether they are fulfilled.

10.2.1. Usage Scenarios

Quality attribute Scenario Priority

Functional suitability

Users shall be able to register, log in, play the quiz, and access historical data without encountering errors or glitches.

High, Medium

Reliability

The system shall reliably generate accurate and diverse questions from Wikidata. User registrations, logins, and game data storage shall be handled without errors.

High, Medium

Availability

The system shall be available 99% of the time when a user attempts to access it.

High, High

Performance efficiency

The system shall deliver optimal performance, ensuring responsive interactions for users. It shall efficiently generate questions from Wikidata and handle real-time gameplay with up to 1000 concurrent users.

High, High

Usability

The system shall provide a user-friendly interface, allowing users to register, log in, and play the game with a learning time of less than 15 minutes. Other functionalities that are not that obvious, such us rules or about pages, are allowed for 2 hours.

High, Medium

Security

User data shall be securely handled. Robust authentication mechanisms shall be in place for user registration and login. API access points for user information and generated questions shall be secured with proper authorization.

Medium, High

Compatibility

The system shall be compatible with various web browsers and devices, providing a seamless experience for users regardless of their choice of platform. It shall be well-optimized for different screen sizes and functionalities.

High, Medium

10.2.2. Change Scenarios

Quality attribute Scenario Priority

Modifiability

The system shall be designed and implemented in a way that allows for easy maintenance and updates.

High, Medium

Maintainability

The code of the system shall be well-documented, and modular, allowing for efficient troubleshooting and modifications.

High, Medium

Testability

The unit tests shall have at least 80% coverage.

High, Medium

Monitoring

The system shall have monitoring in place to track the performance and availability of the system.

High, Medium

10.2.3. Implementation

Security

The system is secured using Spring Security. The user data is stored in a database and the passwords are hashed using BCrypt. The API access points are secured with proper authorization. HTTPS is used to encrypt the data in transit.

The system is also protected against SQL injection via using JPA repositories and prepared statements.

The system is also designed in such a way that prevents cheating, by limiting the options available for the user and doing all validation in the backend, such as checking if the answer is correct, preventing request forgery.

Testability

Many different tests were done to this project as they were considered as a critical requirement for the development.

  • Unit tests: The strongest constraint, as an 80% code coverage is mandatory to ensure code works properly.

  • Load tests: They show how the system will behave under expected workloads.

  • Stress tests: This way we can the behaviour of the system under unexpected loads, such as DDoS attacks. Although we are not protected against them yet, we could do it by using CloudFare as discussed issue #266.

  • Acceptance (e2e) tests: The idea behind them is to ensure the correct functionality of the whole system so real user interactions will work as expected.

  • Usability tests: They aim for the idea of knowing how easy the product is to learn and to use.

More information about testing can be seen in Section 12.

Monitoring

The system is monitored using Spring Boot Actuator and Prometheus. The monitoring data is visualized using Grafana.

The actuator is deployed in https://kiwiq.run.place:8443/actuator/prometheus.

actuator
Figure 19. Spring Boot Actuator

The Prometheus server is deployed in http://20.199.84.5:9090.

prometheus
Figure 20. Prometheus

The Grafana is deployed in http://20.199.84.5:9091. The Grafana dashboard is available at the following link with user asw@uniovi.es and password aswgrafana.

The dashboard used is: https://grafana.com/grafana/dashboards/6756-spring-boot-statistics/ Make sure to put kiwiq.run.place:8443 as the Instance and WIQ API as the application.

grafana
Figure 21. Graphana Spring Boot dashboard
Maintainability

In our CodeScene analysis we find that our knowledge distribution is well-balanced as well as a nice code health, excepting one hotspot on a test that is not relevant.

codescene general
Figure 22. CodeScene general view

11. Risks and Technical Debts

Risk Explanation Mitigation proposed

Little knowledge of the technologies to be used

For most of the members of the team, is the first time working with technologies as React or Wikidata

Explore technologies documentation to familiarize ourselves with the technology, and seek examples of use.

Lack of time

We may face time constraints in fulfilling all the requirements for each deliverable and meeting every deadline.

Try to maintain a steady and sustainable development pace. Prioritize building functional components initially, then iterate and enhance from there.

Coordination and responsability problems

It is probably the first time involvement in developing a project from scratch, including decisions on architecture, design, and implementation, introduces various challenges. Misunderstandings regarding tasks and version control management errors can result in individuals inadvertently disrupting the work of others. Additionally, the necessity to make numerous decisions and reach agreements increases the likelihood of errors, potentially consuming significant time and effort.

To ensure effective collaboration and organization, adhere to the teachers' instructions concerning GitHub, including utilizing features such as issues and pull requests, and maintain a disciplined approach to your work. Furthermore, leverage the collective knowledge and suggestions of every team member, integrating them with your existing expertise.

Hardcoded url in prometheus.yml

We do not have the expertise in prometheus to know how to properly set up the URL, so we decided to harcode it.

Investigate the way to use a variable in the file and use it.

Hardcoded ip in graphana dashboard.yml

As in the previous case, we do not have the expertise in graphana to know how to properly set up the IP, so we decided to harcode it.

Investigate the way to use a variable in the file and use it.

Non optimal code (loadAnswers)

When designing the application we did not take into account that two users may have the same question given to them at the same time. To solve a problem that would arise with that, we decided to just load the distractors of a question once and use the same distractors for all following games, this means that a question always has the same distractors which can get boring.

Rewrite the code (which means altering the workflow) so the distractors are load per game and user, so everytime a questions is asked, the distractors are different.

Use of "supress warnings"

We use Lombok to annotate our classes and make the code lighter, this means that getters and setters are generated by the annotations and not explicitly written in our code, due to this, SonarCloud thinks that our private attributes are not used (the getters and setters are public and used by outside classes, but SonarCloud does not detect that).

Sadly, at this moment we do not think this can be avoided, so the mitigation is just to wait for a SonarCloud update that does detect this.

Questions tied to ID

Questions are tied to the game entities by means of relational tables via id, which makes it difficult to update if they change.

Creating a unique identifier for each question that can stay throughout versions, so we do not need the BD autogenerated ID to access them.

JWT handling could be improved

Handling the session has been difficult and we came up with a solution that works, but can be improved.

We should investigate how to improve session handling, as an example using React context

Usage of React

React has proven to be a pain to work with, so we could change it for better options in case we shall continue the developing of the application.

Changing to Vue.js should be considered.

Queries are hardcoded

To write the questions faster and prevent losing time with possible bugs we hardcoded the queries to Wikidata, which makes the code less readable and maintainable.

The queries can be written in an external file and then read in the code, possibly using a properties file.

QG code can be refactored for lighter classes

As with all the projects in Software developing, as you code you find yourself repeating lines, this has happened in the Question templates, which makes it a bit tedious to change those files.

More abstract classes should be included between the QuestionTemplate.java class and each implementation of it.

Use of relational DB for questions

We started using a relational DB as we were more comfortable with it, but it caused its own troubles, as repeating many lines in the DB.

Using a NoSQL DB as Neo4j for storing the questions could be better as it would be lighter and we would keep the relations that exist in Wikidata between questions.

e2e ran in local

We had many troubles trying to set up the e2e in the actions, as they include setting up the db and filling it before this tests are started.

We should investigate about this and learn how to set up the tests.

In terms of technical debt, it’s likely to be significant due to our lack of familiarity with the majority of the technologies involved for most of the team. Both Wikidata and React present considerable challenges, and we anticipate accumulating substantial technical debt in both areas. At present, our only strategy for mitigation is to search for potential solutions online.

12. Testing

12.1. Performance efficiency

The tests were done with a 2 core and 4 GB of memory system. However, real used VM has 2GB and 1 vCPU in order to keep costs low. If required, a more powerful machine could be easily used instead of the current one. The difference between machines is not such significant as real VM only loads API and the docker image for the DB, while the testing machine must also take care of loading the front of the website.

This system’s efficiency has been measured with Gatling. For the script that we used, a user already created, logged in and played a full game. After that, the user clicked to look the statistics.

The scripts were run a total of 4 times. For load testing, one with 1 user, other with 100 users and another one with 1000 users. Finally one with 10000 for stress testing. Regarding load testing, the results of these scripts show that response times are reasonable up until 1000 users, although roughly 25% of the requests fail. Here are the results.

1 user:

Gatling 1 user
Figure 23. Gatling results with 1 user

100 users:

Gatling 100 users
Figure 24. Gatling results with 100 user

1000 users:

Gatling 1000 users
Figure 25. Gatling results with 1000 user

10000 users:

Having 10000 users playing a game at the same time make a lot of failures. However, the server does not get down so after all those users leave, the system could still run normally.

Gatling 10000 users
Figure 26. Gatling results with 10000 user

12.2. Functional Suitability

To ensure the users are able to do what they are supposed to do and nothing else, both unit and acceptance testing were done.

Acceptance testing tries to see if the user is able to use the application properly without crashing. However, as security is one of the most important requirements, unit testing from a 'back-end' point of view, so that as few unexpected inputs or bugs may happen in any part of the application (front-end included).

On top of it, strong e2e testing was built to reensure the integrity of the software, as negative and positive test cases were introduced. Via e2e, we can also know what the user is capable of by means of normal application usage and how the system reacts to it.

Unit testing was done via Jupyter for API while Jest and React Testing Library for React components in front-end views. Gherkin was used for acceptance testing and user story building. Finally, e2e tests were done in JS using Cucumber and Puppeteer.

12.3. Usability tests

Although they were not as much as desired, 4 usability tests were done as a way to know how easy our product is. The people tested all use internet daily, although they do not share the same level of expertise.

Most people had no problem to complete the basic task (registering and playing a full game). However, one wanted to log in before signing up (probably that was just a dumb mistake). Regarding some more complex task, such us seeing the rules, some of the users had problems as they had not noticed the button for deploying the lateral menu.

Overall, usability tests were good enough, although we would like to have some more people with a wider range of age

13. Glossary

Term Definition

Distractor

Incorrect answer shown to the user alongside the correct one in each question

KiWiq

The name of our project

Question Generator (QG)

A module of the application responsible for querying Wikidata, creating the questions and storing them in our DB

14. Annex

14.1. Functional Requirements

14.1.1. Users Sign up.

  • FR-USU 1. The system shall allow an unregistered user to register in the application.

  • FR-USU 2. The system shall request the necessary data to register the new user.

    • FR-USU 2.1. The system shall request the following mandatory data to register the new user:

      • FR-USU 2.1.1. Username.

      • FR-USU 2.1.2. Email address.

      • FR-USU 2.1.3. Password.

  • FR-USU 3. The system shall not allow the user to be registered when any value entered by the new user is invalid.

  • FR-USU 4. When all the values entered by the new user are valid, the system shall check if the user is already registered in the persistence system.

    • FR-USU 4.1. When a user with the same data is already found in the persistence system, the user shall not be able to create a new account since it already exists.

    • FR-USU 4.2. When no user matching the data is found in the persistence system.

      • FR-USU 4.2.1. The new user shall be registered in the system.

14.1.2. Users Log in.

  • FR-ULI 1. The system must allow an unidentified user to log in.

    • FR-ULI 1.1. The system shall request the email address as the user identifier.

      • FR-ULI 1.1.1. The system must check that its format is valid.

      • FR-ULI 1.1.2. It is a mandatory field.

    • FR-ULI 1.2. The system shall request the user’s password.

      • FR-ULI 1.2.1. It is a mandatory field.

    • FR-ULI 1.3. The system shall automatically validate the entered data to verify when it corresponds to a registered user account.

      • FR-ULI 1.3.1. When the user is not stored in the persistence system, an error message shall be displayed.

      • FR-ULI 1.3.2. When the user exists in the persistence system, but the passwords do not match, a message shall be displayed to the user notifying them of the error.

      • FR-ULI 1.3.3. When the user is stored in the persistence system and the passwords match, the user shall be logged in.

  • FR-ULI 2. The system must allow users who are logged in to log out.

14.1.3. Data management by the user.

  • FR-DMU 1. The system shall allow all registered users to access their historical data from their participation.

    • FR-DMU 1.1. Registered users shall be able to access the number of games they have played.

    • FR-DMU 1.2. Registered users shall be able to access the number of questions they have answered correctly.

    • FR-DMU 1.3. Registered users shall be able to access the number of questions they have answered incorrectly.

    • FR-DMU 1.5. Registered users shall be able to access the ranking of the game.

14.1.4. Play to WIQ.

  • FR-PWIQ 1. The system shall only allow registered users to play the WIQ game.

  • FR-PWIQ 2. The game consists of nine rounds.

    • FR-PWIQ 2.1. In each round, the system shall automatically generate a question to the registered user.

    • FR-PWIQ 2.2. In each round, the system shall provide the registered user with four automatically generated possible answers.

    • FR-PWIQ 2.3. In each round, there shall always be only one correct answer.

    • FR-PWIQ 2.4. The system shall automatically end the game after completing the ninth round.

  • FR-PWIQ 3. The registered user must respond to the question before the specified time expires.

    • FR-PWIQ 3.1. When the specified time has not ended, and the registered user has provided an answer:

      • FR-PWIQ 3.1.1. The system shall check if the answer is correct.

        • FR-PWIQ 3.1.1.1. When the answer is correct:

          • FR-PWIQ 3.1.1.1.1. The registered user shall be notified.

          • FR-PWIQ 3.1.1.1.2. When the registered user is in the ninth round, the system shall end the game.

          • FR-PWIQ 3.1.1.1.3. When the registered user is not in the ninth round, the system shall move to the next round.

        • FR-PWIQ 3.1.1.2. When the answer is incorrect:

          • FR-PWIQ 3.1.1.2.1. When the registered user is in the ninth round, the system shall end the game.

          • FR-PWIQ 3.1.1.2.2. When the registered user is not in the ninth round, the system shall move to the next round.

    • FR-PWIQ 3.2. When the specified time has ended:

      • FR-PWIQ 3.2.1. When the registered user is in the ninth round, the system shall end the game.

      • FR-PWIQ 3.2.2. When the registered user is not in the ninth round, the system shall move to the next round.

  • FR-PWIQ 4. The system shall allow the user to create custom games.

    • FR-PWIQ 4.1. The user may select.

      • FR-PWIQ 4.1.1 The number of rounds.

      • FR-PWIQ 4.1.2 The time per round.

      • FR-PWIQ 4.1.3 The categories of the questions.