1. Introduction and Goals
HappySw, a software development company, has been hired by RTVE in order to develop an experimental online version of the famous spanish program “Saber y Ganar”, a well-known question and answer contest.
Our main objective is to create a web application in which users have to sign up and answer a series of questions generated automatically from the data stored in Wikidata. After that, users will be awarded according to the number of correct answers.
We also expect to provide a practical software that fulfills customer expectations.
1.1. Requirements Overview
| Requirement | Description |
|---|---|
Web access |
The system will rely on at least one web frontend that will be deployed and access will be through web. |
Users registration |
Users must sign up first to be able to access their historial of the game: number of games, times, correct/incorrect answers, etc. |
Automatic generation of data |
Questions and answers have to be generated automatically from Wikidata. |
Questions must have a timer |
Questions must be answered on a determined time, otherwise the response will be count as a fail. |
Only one correct answer |
System must originate only one correct answer and the rest of them will be wrong so as not to confuse the player. |
Data access through an API |
System must allow access to the information about users and the generated answers through an API. |
1.2. Quality Goals
| Priority | Quality goal | Motivation |
|---|---|---|
High |
Usability |
The application interface has to be satisfying and easy to handle to users even if their web skills are zero. |
High |
Maintainability |
Our software should be designed in a way that it won´t be difficult to modify, extend and adjust to changes that could suddenly happen. |
Medium |
Availability |
Users may consider a basic that the system let them watch their personal data and results whenever they want. |
1.3. Stakeholders
| Role/Name | Expectations |
|---|---|
Teachers |
Providing guidance to the development team in order to build the required functional software. |
Development team |
The group of people in charge of developing the application which goals are to satisfy the stakeholders, learn new technologies, maintain a good relationship between us and be proud of the effort put into the project. |
Other students |
They can be interested in this project to learn how we work as a team and to have other points of view. |
Users |
Every one that will be using the application and who should find it practical, enjoyable and easy to use. |
RTVE |
The main client, it´s the company that hired us and provided the requirements needed. |
Businesses |
Companies involved in software development that might be looking for future engineers. |
1.4. Group members
| Name | Contact |
|---|---|
Álex Fernández Salé |
|
María López García-Consuegra |
|
Mauro Varea Fernández |
|
Lucas Castro Antuña |
2. Architecture Constraints
| Technical Constraint | Reason |
|---|---|
Web app |
The application we are developing is a web game called WIQ consisting of automatically generated questions and answers. Users, once logged in, must answer within a certain time to win prizes. Additionally, users will also have access to the history of their games. |
Documentation |
Diagrams and ASCIIDoc will be used along with the Arc42 template to keep the documentation updated throughout the development of the web app. |
Question generator with Wikidata |
Questions will be automatically generated along with the correct and three incorrect answers. This questions will be generated with Wikidata. |
Deployment |
The web app must have a frontend to interact with the game through a web interface, which will be deployed in a virtual machine. To deploy locally for testing before releasing, we will use Docker and npm. |
| Organizational Constraint | Reason |
|---|---|
Github |
Github will be used to keep the web app in a repository with Git version control. Projects will also be used to track who and when someome takes up a task and completes it. Issues will be opened for every task involving the web app. |
Class meetings |
We will use the time during classes to discuss new tasks that need to be done, as well as to address any common problems we might face in order to solve them as soon as possible. Other forms of communication, like a Whatsapp group, can be used to communicate between developers. |
3. System Scope and Context
In WIQ, users can use the WebApp to learn various knowledge through questions created from Wikidata contents. The user interacts directly with the WebApp, which extracts information from WikiData to formulate the questions with their answers and stores them in our database. We use various technologies such as JavaScript, GitHub and MongoDB in the process of creating and maintaining this project.
3.1. Business Context
| Communications | Ins | Outs |
|---|---|---|
User |
Interactions with the application |
Responses to that interactions. |
WIQ |
WikiData information |
Various information received from the APIs and the database. |
Wikidata |
Requests by the WIQ application |
Responses to that requests with the information stored in Wikidata. |
3.2. Technical Context
| Technology | Description |
|---|---|
JavaScript |
Language used for most of the application development. |
Wikidata |
Information base used to formulate WIQ questions. |
WIQ |
Web application. |
MongoDB |
Database used for WIQ data. |
GitHub |
Code collaboration platform. |
4. Solution Strategy
Summary and explanation of the fundamental decisions and solution strategies that we are going to follow while we develop the web app WIQ.
4.1. Technology decisions
-
Javascript as the programming language. It was chosen as the best option among the others we considered (Java, Spring Boot, etc) as it is well-suited for using APIs easily and is a simple language.
-
React.js as the Javascript library chosen to program the user interface of the app due to its ease of use and popularity nowadays.
-
Sparql with Wikidata to use in the question generator, as it is a requirement of the app.
-
Docker for deploying de app locally and testing it.
4.2. Top-level decomposition of the system decisions
The system will be separated into different microservices, one for each characteristic of the app. It consists of modules or packages with classes dedicated to only one responsibility each. We decided to do it this way so that each developer can program their own feature in their branch, reducing potential conflicts when merging code.
4.3. How to achieve key quality goals decisions
We want the web app to be quick and easy to use, as well as to keep all the users' data secure in the system. To make this possible, Docker will help by providing a way to test every aspect of the app before making the release. Moreover, multiple tests will be done to ensure everything works as intended.
4.4. Relevant organizational decisions
-
Github will be used to keep all of our code modifications saved and to have Git version control.
-
Issues will be used to assign tasks to the members.
-
Projects will be used to track the progress of the tasks.
-
-
A Whatsapp group will be used to communicate instantly with each other about important matters.
5. Building Block View
The Building Block view shows the decomposition of the WIQ system into different building blocks that will represent different aspects of the webapp. It will help by giving a clear image of the overall system and also the inside of it.
5.1. Whitebox Overall System
- Motivation
-
The user interacts with the webapp interface to be able to play the game. In the diagram it is clear to see that the webbApp interacts with an external box which is Wikidata, as it is a requirement of the game to generate the questions. In subsequent levels, the webApp will be decomposed into more detail.
5.1.1. WebApp
The WebApp box consists of the entire game with all the different responsibilities the game might have all together. The interface of the WebApp serves as the frontend of a web application, that will be detailed in other diagrams.
5.1.2. Wikidata
The purpose of the Wikidata box is to get the necessary information to generate all the questions for all the games. The web app will interact with Wikidata by SPARQL querys which will be stored in the database.
5.2. Level 2
5.2.1. Interfaces
It consists of the interfaces with which the user will interact to play the game and use all of the different services it provides. There will be different interfaces for the different parts of the webapp, all of them will be connected with eachother. These interfaces will be atractive to the user and easy to use, as well as fast-charging not to make the users wait much. These interfaces are the ones that calls for something to be done, so they interact with the gateway.
5.2.2. Gateway
The gateway is the place where every request is redirected to the service where it belongs to as that information is not visible for the user.
5.2.3. Services
The different services are the ones that internally take care of all the data in the server. They also deal with the requests sent by the gateway and generate a response to it, a good one or the error related to it. To generate the response, the services need data from the database or Wikidata, so they interact with them and sends the data as the response to show the user, for example.
5.2.4. MongoDb
MongoDb is the service we will use to store our data. We will keep it in a cluster in which there are different collections to separate the data. Templates of the entities we save are seen in the project and there are some for the users and their record and others for the questions.
5.3. Level 3
5.3.1. Users
Auth service
This is one service inside the users part of the webapp. It is in charge of authenticating the users when they register for the first time in the game. All the data gets collected and saved in the collection users in MongoDb for when they login later. It uses the same database that the record service uses.
Users service
This is one service inside the users part of the webapp. This one is the one users use everytime when they log in. It retrieves all their data from the database and shows them in the webApp as the users will have an option to view all their past data. It gets the data from the same collection as the auth service and the record.
5.3.2. Question Generator
The Question Generator is the service that interacts with the Wikidata external service through SPARQL querys. It is dedicated to generate the questions and the answers and send them to the database to store there to later show in the game.
5.3.3. Record
The record service is the one that answers the requests related to save or get the games and statistics of the player. It interacts with the user collection in the MongoDb database and stores there the data. It also sends the data for the user to see.
6. Runtime View
6.1. Question Scenario
In the diagram we can see one user interacting with the app by getting and answering a question of the game.
In this scenario, the question will first be collected from the database. To do so, the question view will call getQuestion, which will propagate to the question service propagate to question service where, thanks to the question repository, a random question will be fetched. Afterwards, this question will be deleted from the database to avoid repeating questions. Once the question has been retrieved, it is displayed in the view. When the user selects one of the 4 answers, the selected answer is checked, the user is notified of the answer. the selected answer is checked, the user is notified of this check (whether it is correct or incorrect), and the process of saving the question begins. To do this, the /saveQuestion endpoint will be called and, once redirected to the historial service, it will save the question in a temporary array so that, when the user wants to save the complete game, the questions will be stored in a temporary array. the complete game is to be saved, all the questions of that game will be there.
6.2. Register Scenario
The diagram shows a sequence of consecutive actions that a user takes in order to access to the main interface of the application.
The user first insert his/her data into the corresponding fields, after that, clicking on the register button will perform a series of actions inside the system that the user won´t be seeing. First, the gateway service will recognize the action of adding the user and it will redirect the request to the auth service, which is the one in charge of validating the fields previously specified by the user. Finally, the connection with the database will be made and, if everything is correct, the user information will be saved.
6.3. Login Scenario
This diagram explains the sequence that every user follows in order to sign into the application.
This flowchart is very similar to the previous one because the actions are basically the same: insert the user data in the fields. However, the system reacts in a different way than before, that´s because the user has already signed up previously and the database has registered that information on the system. This time, the action sent by the auth service to the database is to search if there´s any user whose data corresponds to those obtained previously. If the user has not signed up yet the application will notify him that an error on the authentication has ocurred. When the user is logged, then 10 questions will be generated with wikidata and saved to the database.
6.4. Save record Scenario
In this diagram we can see the sequence for saving a game. When the game is over, the user is redirected to the Game Final screen, where he/she will click on the "Save record" button to save that game in the record. First, the gateway service will recognize the action of saving a game. It will start by obtaining the user by username by calling the /getUserByUsername endpoint of authservice which, by a findOne() query will retrieve the user with that username. Once the user has been obtained, gateway service will call history service to store the queries and the user in the same batch, thanks to the history repository.
6.5. Get record Scenario
This diagram shows the process by which a user, previously logged in, accesses the records of his games. First, the user will click on the navBar button to access his game record. This will make a call to the /getGameRecord endpoint, which the gateway service will catch. This controller will call user service to obtain the user for whom the complete history is to be obtained. Once the user is obtained, gateway service will call history service to, through the history repository, obtain the complete history of the user.
6.6. Get all questions Scenario
This diagram shows the process to get all the questions from the database. Once logged in, the user will click the get DB data button. This will make a call to the /getAllQuestions endpoint which, in turn, will get all the questions from the question service. Once the questions are obtained, the gateway service will create a temporary questions.json file with all the questions and pass it to the view, which will create a link to download it.
6.7. Get all users Scenario
This diagram shows the process to get all the users from the database. Once logged in, the user will click the get DB data button. This will make a call to the /getAllUsers endpoint which, in turn, will get all the users from the user service. Once the users are obtained, the gateway service will create a temporary users.json file with all the questions and pass it to the view, which will create a link to download it.
7. Deployment View
The deployment view describes the deployment architecture of the web application. It illustrates how the software elements are deployed onto the hardware infrastructure. This view provides insights into the physical deployment structure, including servers, databases and network configurations.
7.1. Infrastructure Level 1
| Element | Description |
|---|---|
Device |
The device used by end-users to access the web application, such as desktop computers, laptops, tablets or smartphones. |
Azure server |
The virtual machine, hosted on the Microsoft Azure platform, responsible for hosting and running the web application. |
Docker |
The containerization platform utilized to encapsulate and deploy microservices, providing lightweight, portable environments for running specific components of the web application stack. |
7.2. Infrastructure Level 2
| Element | Description |
|---|---|
User service |
Utilized by logged-in users, retrieves their data from the MongoDB database and displays it within the web application. |
Auth service |
Ensure user authentication during their initial registration in the game. Collect and securely store all their information in the MongoDB database to facilitate seamless login experiences in subsequent sessions. |
Gateway service |
Acts as a central entry point for client requests, routing them to appropriate backend microservices. |
Question generator |
Generates the questions and the answers, then transmits them to the interface for display to the user. Utilizes SPARQL to interact with the Wikidata external service. |
Record |
Manages and stores records of user played games, stats and other relevant data in the database MongoDb. |
MongoDB |
The database management system, serves as the backend storage for the application’s functionality. It stores user data, generated questions and other game-related information. |
8. Cross-cutting Concepts
8.1. Ethics
Ensuring users are clearly informed about what data is collected, how it will be used and with whom it is shared by obtaining their explicit consent for its processing.
8.2. Performance
Optimizing performance is crucial for ensuring a seamless user experience. This involves implementing efficient algorithms and database structures to minimize response times and maximize scalability. By prioritizing performance considerations, the application can deliver timely and responsive interactions, enhancing user satisfaction. However, maintaining decent timings will be challenging
8.3. User experience
This is a key element in the design of every application because it directly impacts on user satisfaction and retention. Crafting intuitive interfaces that facilitate effortless interaction with the system is sure something to take into account.
9. Architecture Decisions
9.1. Decisions
| Decision | Reason |
|---|---|
Javascript |
We chose to stick with Javascript for the development of this web app because we already had knowledge of this language from other subjects. We found it to be an accessible language capable of fulfilling all the app’s requirements, including using APIs such as the one from Wikidata. |
React.js |
We decided to use React.js because it is one of the most popular Javascript libraries used nowadays. Although none of us were familiar with it, we thought it would make programming the front-end part of the app better and easier for us. |
Mongodb |
For the database aspect of the app, we opted for Mongodb as we believe it is a well-suited option for storing the data necessary for the design and development of the app. |
SPARQL |
To generate the questions and answers for the game, we will use SPARQL in Wikidata as it is a great source of information to provide different types of questions to the users, making the game versatile and non-repetitive. |
Users login |
When a user logs into the application, 10 questions will be automatically generated and saved in the database. The decision was made based on the performance demonstrated compared to the other options. |
9.2. Package division
| Package | Description |
|---|---|
GatewayService |
This is a crucial part of the project because it connects different services and provides a unified interface to interact with them. It gives an abstraction layer so that clients can communicate with the underlying services without needing to know the implementation details of each. It also provides a documentation interface for developers to understand how to interact with services through defined routes. |
QuestionsGenerator |
It is responsible for generating questions from Wikidata. It handles loading question templates, generating questions and providing random questions based on selected categories. |
Record |
The record package manages and stores game records. It contains the model of each game played, which handles saving and retrieving game-related data. When a user plays the game, their questions are temporarily stored in memory until the game session is completed and saved in the database. |
Users |
It is divided into two packages both of them having different functionalities: - AuthService: Handles user authentication and authorization. - UserService: Manages user-related operations like password hashing, and password and username validation. It also contains the model of the information that the application stores for each user. |
Webapp |
It is responsible for creating the web application´s user interface and involves various functionalities such as rendering views, handling user interactions and communicating with backend services. It uses React as the base framework, and html and css to manage the visual appearance of the application. |
LoadTests |
Handles load tests to test the functionality and performance of the application. |
10. Quality Requirements
The main quality objectives of the project will be:
-
Usability: The system will be intuitive, through a simple and clear interface.
-
Functionality: The system will offer a set of features and tools to fulfill user needs.
-
Performance: The system will provide fast and effective responses to the user.
-
Maintainability: The system will be easy to maintain, upgrade or extend, without putting the whole project at risk.
-
Security: El sistema será seguro para las contraseñas, ya que están hasheadas, y tendrá seguridad contra inyección en URL.
10.1. Quality Tree
10.2. Quality Scenarios
We will categorize the quality scenarios into three main types: usage, change, and failure scenarios.
10.2.1. Usage scenarios
| Source | Stimulus | Attribute | Artifact/Environment | Reply | Response measure |
|---|---|---|---|---|---|
Players |
A player wants to start a game |
Performance |
Game Interface |
The system creates the game |
Game creation time less than 0.5s |
Players |
A player wants to answer a question |
Performance |
Game Interface |
The system updates the question interface |
Question update time less than 0.5s |
Players |
A player wants to login with username and password |
Security |
User Interface |
The system stores these credentials |
These credentials will be encrypted to maintain their security. |
Players |
A player wants to access his personal game history |
Performance |
The system will show the personal game history |
These games will be showned in less than 1s |
Players |
10.2.2. Change scenarios
| Source | Stimulus | Attribute | Artifact/Environment | Reply | Response measure |
|---|---|---|---|---|---|
Developers |
The game must have more modes to play |
Maintainability |
Game Interface |
A new game mode must be implemented |
The implementation of these new mode should be independent of the other game modes |
Developers |
We want to migrate the database to another database system |
Maintainability |
Database |
The system do the migration |
Encrypted data will be migrated in encrypted form |
10.2.3. Failure scenarios
| Source | Stimulus | Attribute | Artifact/Environment | Reply | Response measure |
|---|---|---|---|---|---|
Game error |
An error occurs during the creation of a game |
Failure |
Game Interface |
The system doesn’t create the game |
The system will alert the user of the error in the creation |
Question error |
A user wants to play a category mode y no hay preguntas de esa categoría |
Failure |
Game Interface |
The system doesn’t create the question |
The system will alert the user of the error |
Record error |
An error occurs durante el acceso al historial de un usuario |
Failure |
Record Interface |
The system wont show the record |
The system will alert the user with a internall server error |
11. Risks and Technical Debts
We must take into account all risks and problems, as they are very useful to prevent and be able to manage them correctly.
| Type | Name | Description | Priority |
|---|---|---|---|
Risk |
Time |
The time for this project is limited, since we must follow certain delivery guidelines and, in addition, the other subjects force us to distribute the available time in the best possible way |
Medium |
Technical Debt |
React |
React is a new technology for all the members of the group. Although we agree that it is the best option to carry out the project, we must inform ourselves about it, take courses and learn independently the potentials of this technology |
High |
Risk |
Github |
GitHub is a very powerful tool when it comes to working in a coordinated and parallel way, but without a good organization and communication in the conflicts generated, functionalities can be lost |
Low |
Risk |
Autonomy |
Typically, projects undertaken during the course are heavily guided, with frequent reviews, partial deliveries and documentation to steer the team throughout the project. Working entirely autonomously may pose challenges in terms of organization. |
Medium |
12. Tests
Information about the different tests we have done.
12.1. Unit tests
We have done unit testing in all the different components of the webapp and services, all of these trying to test every aspect of the component by mocking database accesses to be able to get the most coverage percentage possible. All the tests pass successfully and give us a really good test coverage on the lines of the component they test. Here are the overall results of the components of the webapp:
There is a test suite for each service or app has. Here are the results of those tests:
Question service.
Record service
Gateway service
Users Service
Auth Service
12.2. E2E tests
In addition to the unit tests we have done some E2E tests too. These tests are able to make sure all our components work well while used together. We have done this tests in the cases of a user creating an account, loging in, playing the game and whatching the record. Here are the results of those tests, all of them pass successfully.
12.3. Load tests
Gatling was used to make load tests to test our gateway and see how it performed with a lot of requests. We made load tests to the login and to the game. All the information about these tests are in the folder loadtests of the project. Here are some important data of the tests to give an overall view of how they went.
These tests consist of two users starting to do the test each second for 60 seconds, in total 120 users.
Login Simulation.
Answer questions Simulation.
13. Glossary
Definition on some of the most important terms of this documentation.
| Term | Definition |
|---|---|
API (Application Programming Interface) |
A set of rules and protocols that allows different software applications to communicate and interact with each other. |
Arc42 |
A widely-used template for documenting software architectures, emphasizing a pragmatic, lightweight approach to capturing and communicating architectural decisions and design rationale. It provides a structured format for describing system components, interfaces, and their relationships, aiding in the understanding and maintenance of software systems. |
ASCIIDoc |
A lightweight markup language used for writing documentation, particularly favored for its simplicity and readability. It allows for the creation of structured documents using plain text, which can then be easily converted into various formats such as HTML, PDF, or EPUB. |
Deploy |
The process of releasing and installing a software application or system onto a target environment, such as a server or cloud platform, making it available for use by end-users. This typically involves transferring code, configurations, and other necessary resources to the production environment and ensuring that the application runs smoothly and as intended. |
Docker |
A platform for developing, shipping, and running applications using containerization technology. It allows developers to package their applications and all dependencies into lightweight, portable containers that can run consistently across different environments, streamlining the deployment process and enhancing scalability and efficiency. |
Frontend |
The part of a software application or system that users interact with directly. It typically includes the user interface components, such as web pages, graphical elements, and other visual elements, as well as the logic that controls user interactions. The frontend is responsible for presenting data and functionality to users in an intuitive and accessible manner. |
Microservices |
A software architectural style where an application is composed of loosely coupled, independently deployable services that are organized around specific business capabilities. Each microservice is responsible for a single function or feature and communicates with other services through well-defined APIs. |
Wikidata |
A collaborative, open database that stores structured data to support Wikimedia and other knowledge-related projects. |
WIQ |
Online version (web app) of the famous spanish program "Saber y Ganar", a question and answer contest. |
Quality attribute |
Measurable property of a system, which indicates how well the system meets the needs of stakeholders. |