Wiq 7 Documentation

About arc42

arc42, the template for documentation of software and system architecture.

Template Version 8.2 EN. (based upon AsciiDoc version), January 2023

Created, maintained and © by Dr. Peter Hruschka, Dr. Gernot Starke and contributors. See https://arc42.org.

Note	This version of the template contains some help and explanations. It is used for familiarization with arc42 and the understanding of the concepts. For documentation of your own system you use better the plain version.

1. Introduction and Goals

Saber y Ganar is the Software Architecture project developed by Ángel Luis Álvarez Iglesias (uo17919), under the supervision of Jorge Álvarez Fidalgo.

This project consists of an application that features a question-and-answer game, designed to be both engaging and educational. Additionally, the application offers a statistics tracking system, allowing registered users to view their own performance metrics and compare them with those of other players.

The application is built using the MERN stack, which includes MongoDB for the database, Express.js for the server-side framework, React for the front-end development, and Node.js for the runtime environment.

1.1. Requirements Overview

Requirement Code	Description
RE1	The system will have at least a web front-end which will be available and accessible through the web.
RE2	Users will be able to register to the system and obtain the historical data from their participation: number of games, questions passed and failed, times, …
RE3	Questions will be automatically generated from data available in Wikidata.
RE4	Questions have to be answered before some specific time.
RE5	Each question will have one right answer and several incorrect ones or distractors. Both the right answer and the distractors should be automatically generated.
RE6	The system will give access to the information about the users through an API.
RE7	The system will give access to information about the generated questions through an API.
RE8	Allow different game modes like the ones that appear in the quiz show page (Each wise man with his subject, Travel with us, The hot question, Discovering cities, …).

Requirement Code

Description

RE1

The system will have at least a web front-end which will be available and accessible through the web.

RE2

Users will be able to register to the system and obtain the historical data from their participation: number of games, questions passed and failed, times, …

RE3

Questions will be automatically generated from data available in Wikidata.

RE4

Questions have to be answered before some specific time.

RE5

Each question will have one right answer and several incorrect ones or distractors. Both the right answer and the distractors should be automatically generated.

RE6

The system will give access to the information about the users through an API.

RE7

The system will give access to information about the generated questions through an API.

RE8

Allow different game modes like the ones that appear in the quiz show page (Each wise man with his subject, Travel with us, The hot question, Discovering cities, …).

1.2. Quality Goals

Quality Objective	Implementation	Priority
Usability	To ensure the application is user-friendly, we will maintain a consistent design and emphasize predictability, making it easy to learn and providing a seamless user experience.	5
Testability	We will perform thorough tests to ensure the proper functioning of all services within the application.	4
Performance	We will strive to optimize resource usage within the application to ensure its performance remains fast and efficient.	4
Reliability	We will focus on building a robust application by implementing error-handling mechanisms and redundancy measures to ensure consistent performance and minimize downtime.	3
Security	The goal is to meet essential security standards to prevent unauthorized access to accounts and protect user information from exposure. However, this is not a primary objective of the project.	1

Quality Objective

Implementation

Priority

Usability

To ensure the application is user-friendly, we will maintain a consistent design and emphasize predictability, making it easy to learn and providing a seamless user experience.

Testability

We will perform thorough tests to ensure the proper functioning of all services within the application.

Performance

We will strive to optimize resource usage within the application to ensure its performance remains fast and efficient.

Reliability

We will focus on building a robust application by implementing error-handling mechanisms and redundancy measures to ensure consistent performance and minimize downtime.

Security

The goal is to meet essential security standards to prevent unauthorized access to accounts and protect user information from exposure. However, this is not a primary objective of the project.

1.3. Stakeholders

Role	Description	Expectations
Client	Our client is RTVE, represented by the course instructors, who have requested the development of an application based on the "Saber y Ganar" TV show.	An application that fulfills all the requirements outlined in the section above.
Development team	The student uo17919.	Develop a comprehensive application as described in the lab practice guide. It must meet all specified requirements and clearly demonstrate the effort invested in the project.
Users	The target audience for the application (the players) who will test or use the final product.	A fun and well-functioning game that features a variety of questions to offer a challenging experience.
Github users	The users who will access the project repository on Github.	A well-documented project that is easy to understand and navigate, featuring high-quality code and a clear architecture.

Role

Description

Expectations

Client

Our client is RTVE, represented by the course instructors, who have requested the development of an application based on the "Saber y Ganar" TV show.

An application that fulfills all the requirements outlined in the section above.

Development team

The student uo17919.

Develop a comprehensive application as described in the lab practice guide. It must meet all specified requirements and clearly demonstrate the effort invested in the project.

Users

The target audience for the application (the players) who will test or use the final product.

A fun and well-functioning game that features a variety of questions to offer a challenging experience.

Github users

The users who will access the project repository on Github.

A well-documented project that is easy to understand and navigate, featuring high-quality code and a clear architecture.

2. Architecture Constraints

2.1. Technical Architecture Constraints

Technical architecture constraints	Description
Web application	As indicated in RE1, access to the application shall be through the web, so a web application must be developed rather than a desktop application.
Wikidata	As indicated in RE3, the questions shall be automatically generated from Wikidata data.
Github	The project shall be hosted in a GitHub repository created by the ArquiSoft organization for the Software Architecture course at the School of Software Engineering at the University of Oviedo.
Github actions	The project shall use GitHub Actions to automate the testing and deployment processes.
Docker	The project shall use Docker to containerize the application.

Technical architecture constraints

Description

Web application

As indicated in RE1, access to the application shall be through the web, so a web application must be developed rather than a desktop application.

Wikidata

As indicated in RE3, the questions shall be automatically generated from Wikidata data.

Github

The project shall be hosted in a GitHub repository created by the ArquiSoft organization for the Software Architecture course at the School of Software Engineering at the University of Oviedo.

Github actions

The project shall use GitHub Actions to automate the testing and deployment processes.

Docker

The project shall use Docker to containerize the application.

2.2. Organizational and Political Constraints

Organizational and political constraints	Description
Development time	The team shall develop the application in accordance with the established deadlines, even if this means using alternative development technologies or altering the original architectural decisions.
Compliance with privacy regulations	The application shall adhere to updated data privacy regulations to ensure the confidentiality of the contestants.

Organizational and political constraints

Description

Development time

The team shall develop the application in accordance with the established deadlines, even if this means using alternative development technologies or altering the original architectural decisions.

Compliance with privacy regulations

The application shall adhere to updated data privacy regulations to ensure the confidentiality of the contestants.

2.3. Conventions

Conventions	Description
Documentation	The development team shall use arc42 to document the application architecture, design decisions, and implementation details, ensuring ease of future updates and maintenance.

Conventions

Description

Documentation

The development team shall use arc42 to document the application architecture, design decisions, and implementation details, ensuring ease of future updates and maintenance.

3. System Scope and Context

3.1. Business Context

Name	Description
Player	The user who plays the game.
Wiq	The application is used by players and interacts with Wikidata to automatically generate questions.
Wikidata	Collaborative database of free knowledge that stores structured data (https://www.wikidata.org/).

Name

Description

Player

The user who plays the game.

Wiq

The application is used by players and interacts with Wikidata to automatically generate questions.

Wikidata

Collaborative database of free knowledge that stores structured data (https://www.wikidata.org/).

3.2. Technical Context

Name	Description
User	The user who plays the game.
WebApp	The application is used by players and interacts with Wikidata to automatically generate questions.
Frontend	The user interface of the application.
Gateway	The entry point of the application.
User service	Manages user registration.
Authentication service	Manages user authentication.
Statistic service	Manages game statistics.
Question service	Handles the generation and formulation of game questions.
MongoDB	Database used to store the data of the application.
Wikidata	Collaborative database of free knowledge that stores structured data (https://www.wikidata.org/).

Name

Description

User

The user who plays the game.

WebApp

The application is used by players and interacts with Wikidata to automatically generate questions.

Frontend

The user interface of the application.

Gateway

The entry point of the application.

User service

Manages user registration.

Authentication service

Manages user authentication.

Statistic service

Manages game statistics.

Question service

Handles the generation and formulation of game questions.

MongoDB

Database used to store the data of the application.

Wikidata

Collaborative database of free knowledge that stores structured data (https://www.wikidata.org/).

4. Solution Strategy

4.1. Technology decisions

Technology	Description
Git	Software version control system
GitHub	Cloud-based service that hosts the aforementioned version control system, Git.
Node.js	Runtime environment for JavaScript that enables the development of scalable server-side applications.
Express	Framework for building web applications in Node.js.
React	JavaScript library that allows us to create interactive user interfaces easily. It is based on components.
Docker	Tool that simplifies the creation, deployment, and execution of applications using containers. Containers allow you to package an application with all its required components, such as libraries and other dependencies, and deploy it as a single package.
Puppeteer	Test automation tool for web browsers developed by Google. It allows control of the browser through an API.

Technology

Description

Git

Software version control system

GitHub

Cloud-based service that hosts the aforementioned version control system, Git.

Node.js

Runtime environment for JavaScript that enables the development of scalable server-side applications.

Express

Framework for building web applications in Node.js.

React

JavaScript library that allows us to create interactive user interfaces easily. It is based on components.

Docker

Tool that simplifies the creation, deployment, and execution of applications using containers. Containers allow you to package an application with all its required components, such as libraries and other dependencies, and deploy it as a single package.

Puppeteer

Test automation tool for web browsers developed by Google. It allows control of the browser through an API.

4.2. Decisions about the top-level decomposition of the system

A microservices architecture has been chosen, with distinct modules assigned to each functionality. This approach allows for better scalability, maintainability, and flexibility.

4.3. Decisions on how to achieve quality goals

Quality Goal	Implementation
Usability	The team will focus on designing a clear and accessible interface for all users. To achieve this, we will adhere to web usability standards and perform usability tests.
Testability	Unit tests and end-to-end (E2E) integration tests will be created to ensure the software is reliable, robust, and free of errors.
Performance	We will focus on optimizing the application’s performance to ensure fast response times and efficient resource usage. This includes implementing performance best practices and monitoring the system to address any potential bottlenecks.
Reliability	Our goal is to ensure that the application operates consistently and without interruptions. This involves implementing robust error-handling mechanisms, conducting regular system tests, and designing the system to recover gracefully from failures.
Security	We will implement all necessary measures to secure our application.

Quality Goal

Implementation

Usability

The team will focus on designing a clear and accessible interface for all users. To achieve this, we will adhere to web usability standards and perform usability tests.

Testability

Unit tests and end-to-end (E2E) integration tests will be created to ensure the software is reliable, robust, and free of errors.

Performance

We will focus on optimizing the application’s performance to ensure fast response times and efficient resource usage. This includes implementing performance best practices and monitoring the system to address any potential bottlenecks.

Reliability

Our goal is to ensure that the application operates consistently and without interruptions. This involves implementing robust error-handling mechanisms, conducting regular system tests, and designing the system to recover gracefully from failures.

Security

We will implement all necessary measures to secure our application.

4.4. Relevant organizational decisions

The team will follow an agile development methodology to ensure flexibility and adaptability throughout the project.

5. Building Block View

5.1. Whitebox of the Overall System

Motivation: WIQ is a web application where users can register and start playing. The game consists of answering a series of questions of various types and topics, with a reward for each correct answer. An important aspect of the system is that the questions will be automatically generated from Wikidata data (https://www.wikidata.org/).
Contained Building Blocks

Name	Responsibility
User	The user interacts with the application.
WIQ	The application is used by the user and communicates with Wikidata to generate questions automatically.
Wikidata	Collaborative database of free knowledge that stores structured data.

Name

Responsibility

User

The user interacts with the application.

WIQ

The application is used by the user and communicates with Wikidata to generate questions automatically.

Wikidata

Collaborative database of free knowledge that stores structured data.

5.2. Level 1

Motivation: The main components of WIQ are shown here.
Contained Building Blocks

Name	Responsibility
User	The user interacts with the application.
Frontend Web	Component responsible for the system’s user interface. It provides access to the system’s functionalities through a web browser.
Backend	It contains the business logic and data management of the system. It exposes endpoints to interact with clients through an API.
MongoDB	NoSQL database management system that uses a flexible data model based on JSON documents with dynamic schemas.
Wikidata	Collaborative database of free knowledge that stores structured data.

Name

Responsibility

User

The user interacts with the application.

Frontend Web

Component responsible for the system’s user interface. It provides access to the system’s functionalities through a web browser.

Backend

It contains the business logic and data management of the system. It exposes endpoints to interact with clients through an API.

MongoDB

NoSQL database management system that uses a flexible data model based on JSON documents with dynamic schemas.

Wikidata

Collaborative database of free knowledge that stores structured data.

5.3. Level 2

Motivation: A detailed breakdown of the WIQ microservices is presented.
Contained Building Blocks

Name	Responsibility
User	The user who plays the game.
WebApp	The application is used by players and interacts with Wikidata to automatically generate questions.
Frontend	The user interface of the application.
Gateway	The entry point of the application.
User service	Manages user registration.
Authentication service	Manages user authentication.
Statistic service	Manages game statistics.
Question service	Handles the generation and formulation of game questions.
MongoDB	Database used to store the data of the application.
Wikidata	Collaborative database of free knowledge that stores structured data (https://www.wikidata.org/).

Name

Responsibility

User

The user who plays the game.

WebApp

The application is used by players and interacts with Wikidata to automatically generate questions.

Frontend

The user interface of the application.

Gateway

The entry point of the application.

User service

Manages user registration.

Authentication service

Manages user authentication.

Statistic service

Manages game statistics.

Question service

Handles the generation and formulation of game questions.

MongoDB

Database used to store the data of the application.

Wikidata

Collaborative database of free knowledge that stores structured data (https://www.wikidata.org/).

6. Runtime View

6.1. User Registration

User registration in the application is managed through the user microservice (userservice). The user enters a username and password, and if the user is created successfully, a confirmation message is displayed. Otherwise, an error message is shown.

6.2. Login

The application’s login is managed through the authentication microservice (authservice). The user enters their credentials, and if the information is correct, a view of the application with the available options is displayed.

6.3. Play

The quiz game is managed through the authentication microservice (questionservice). The user starts a new game, and a new question with its corresponding answers is displayed.

6.4. Statistics

The application’s statistics module is handled by the statistics microservice (statsservice). Upon user request, the game statistics are presented in a view.

7. Deployment View

Element	Description
User	The actor who interacts with the application, representing the players.
Azure	The cloud platform where the application is deployed.
Ubuntu	The virtual machine on Azure running the Ubuntu operating system.
Docker	Technology used to containerize and deploy the microservices and the database.
WebApp	The main component of the web application, including the frontend and backend services.
Frontend	The user interface of the application, which the users directly interact with.
Gateway	The service that acts as an intermediary between the frontend and other backend services.
User Service	The service that handles user registration and management.
Authentication Service	The service responsible for user authentication.
Statistic Service	The service responsible for generating and managing user statistics.
Question Service	The service responsible for generating and managing the game questions.
MongoDB	The database where the application data is stored.
Wikidata	An external component that is queried to obtain additional data for the game questions.

Element

Description

User

The actor who interacts with the application, representing the players.

Azure

The cloud platform where the application is deployed.

Ubuntu

The virtual machine on Azure running the Ubuntu operating system.

Docker

Technology used to containerize and deploy the microservices and the database.

WebApp

The main component of the web application, including the frontend and backend services.

Frontend

The user interface of the application, which the users directly interact with.

Gateway

The service that acts as an intermediary between the frontend and other backend services.

User Service

The service that handles user registration and management.

Authentication Service

The service responsible for user authentication.

Statistic Service

The service responsible for generating and managing user statistics.

Question Service

The service responsible for generating and managing the game questions.

MongoDB

The database where the application data is stored.

Wikidata

An external component that is queried to obtain additional data for the game questions.

8. Cross-cutting Concepts

This section describes overall, principal regulations and solution ideas that are relevant in multiple parts (= cross-cutting) of the system.

8.1. Domain concepts

- Domain model: The domain model, including the key classes and their most important attributes, is illustrated in the following diagram.

8.2. User Experience Concepts (UX)

- Usability tests: Usability tests will be conducted to ensure a pleasant user experience.

8.3. Safety and Security Concepts

- Password Hashing: During the registration process, user passwords will be hashed using a secure algorithm on the frontend before being sent and stored in the database. Later, during the login process, passwords are retrieved hashed from the database and decrypted on the frontend.

8.4. Architecture and Design Patterns

- Microservices: The system will be designed as a set of microservices, each responsible for a specific domain or functionality.

8.5. "Under-the-hood"

- Persistency: The system will use a nosql database (Mongo DB) to store data.

- Transaction handling: (todo)

- Session handling: The system will use JWT tokens for session handling.

- Exception and error handling: A server-side validation layer will be develop to catch and handle exceptions and errors effectively.

8.6. Development Concepts

- CI/CD: The system will be developed using GitHub Actions for continuous integration and continuous deployment (CI/CD).

8.7. Operational Concepts

- Administration: The system will provide an administration interface to manage users, roles, and other system settings.

- Scalability: The system will be deployed on an Azure virtual machine, which allows for easy scaling.

- Monitoring: The system will be monitored using Prometheus and Grafana. Prometheus is an open-source monitoring and alerting toolkit. Grafana is a visualization tool that allows you to create dashboards and graphs.

9. Architecture Decisions

This section describes the architecture decisions that were made during the development of the project.

9.1. Technology Decisions:

- Decision 1 - Use of Microservices: The system is designed as a set of microservices, each responsible for a specific domain or functionality. This architecture allows for better scalability, maintainability, and flexibility.

- Decision 2 - Use of node.js for Backend Services: The backend services of the system are built using node.js, a JavaScript runtime. Node.js was chosen for its performance, scalability, and ease of use.

- Decision 3 - Use of a NoSQL Database: A NoSQL database was chosen for the system due to its flexibility and scalability. The system uses MongoDB as its primary database.

- Decision 4 - Use of a React Frontend: The frontend of the system is built using React, a JavaScript library for building user interfaces. React was chosen for its performance, flexibility, and ease of use.

- Decision 5 - Use of Docker Containers: The system is deployed using Docker containers. This architecture allows for better portability, scalability, and isolation of services.

- Decision 6 - Use of a RESTful API: The system exposes a RESTful API for communication between the frontend and the microservices. This architecture allows for better decoupling between the frontend and backend components.

10. Quality Requirements

As described in section 1: Introduction and Goals, the quality requirements that were identified for the project are:

- Usability: the application should be user-friendly and intuitive, allowing users to easily navigate and interact with its features.

- Testability: The application should undergo thorough testing, ensuring a clear separation between its logic and presentation layers.

- Performance: The application should be able to handle a reasonable number of users and requests without compromising its performance.

- Reliability: The application should be reliable, ensuring that it is available and responsive to users at all times.

- Security: The application should be secure, protecting users' data and preventing unauthorized access to its features.

10.1. Quality Tree

10.2. Quality Scenarios

10.2.1. Usage Scenarios

Usage Scenario	System Reaction
A new user registers in the application.	The system should add the user data to the database and show a confirmation message.
The user logs into the application.	The system should verify the user’s credentials and grant access to the application.
The user starts a new game.	The system should start a new game and display the first question.
An authenticated user accesses the statistics section of the website.	The system should display the user’s statistics.

Usage Scenario

System Reaction

A new user registers in the application.

The system should add the user data to the database and show a confirmation message.

The user logs into the application.

The system should verify the user’s credentials and grant access to the application.

The user starts a new game.

The system should start a new game and display the first question.

An authenticated user accesses the statistics section of the website.

The system should display the user’s statistics.

10.2.2. Change Scenarios

Change Scenario	System Reaction
A new game mode is added to the application.	The system should update the game modes list and display the new mode to the users.
A new user role is created.	The system should update the user roles list and grant the new role to the users.
2FA authentication is implemented.	The system should add the 2FA authentication feature and require users to enable it.

Change Scenario

System Reaction

A new game mode is added to the application.

The system should update the game modes list and display the new mode to the users.

A new user role is created.

The system should update the user roles list and grant the new role to the users.

2FA authentication is implemented.

The system should add the 2FA authentication feature and require users to enable it.

11. Risks and Technical Debts

Below is a table presenting the risks and potential technical debts considered by the development team.

Risk	Description	Preventive Measure
Inexperience with the technologies used	Due to potential inexperience with the technologies used in the project, technical debts may arise.	To minimize the impact, it is recommended to research and test the technologies to achieve a basic level of proficiency with them.
Dependency on wikidata	The project relies on the Wikidata API to retrieve data. If the API is unavailable, the project may not function as expected.	To mitigate this risk, it is recommended to implement a fallback mechanism that uses a local database to store data.
Code loss	The project may suffer from code loss due to a lack of proper version control.	To prevent this, Git will be used as the version control system for managing the code and storing it in a remote repository.
Loss of code quality	The project may suffer from a loss of code quality due to the lack of experience with the technologies used.	To prevent this, it is recommended to use code quality tools and to follow best practices.
Planning issues	The project may suffer from planning issues due to a lack of experience with project management.	To prevent this, It is recommended to divide the project into activities and tasks, estimate their duration, and allow for potential deviations.

Risk

Description

Preventive Measure

Inexperience with the technologies used

Due to potential inexperience with the technologies used in the project, technical debts may arise.

To minimize the impact, it is recommended to research and test the technologies to achieve a basic level of proficiency with them.

Dependency on wikidata

The project relies on the Wikidata API to retrieve data. If the API is unavailable, the project may not function as expected.

To mitigate this risk, it is recommended to implement a fallback mechanism that uses a local database to store data.

Code loss

The project may suffer from code loss due to a lack of proper version control.

To prevent this, Git will be used as the version control system for managing the code and storing it in a remote repository.

Loss of code quality

The project may suffer from a loss of code quality due to the lack of experience with the technologies used.

To prevent this, it is recommended to use code quality tools and to follow best practices.

Planning issues

The project may suffer from planning issues due to a lack of experience with project management.

To prevent this, It is recommended to divide the project into activities and tasks, estimate their duration, and allow for potential deviations.

12. Glossary

Term	Definition
API	Application Programming Interface, which is a set of rules and protocols that allows different software applications to communicate with each other.
Backend	Internal part of the application’s architecture, which is responsible for processing requests and generating responses.
CI/CD	Continuous Integration and Continuous Deployment, which is a set of practices that automate the integration of code changes and the deployment of applications.
Container	Standardized unit of software that packages up code and all its dependencies so that the application runs quickly and reliably from one computing environment to another.
Database	Collection of information that is organized so that it can be easily accessed, managed, and updated.
Frontend	External part of the application’s architecture, which is visible to the user and interacts with the backend.
JSON	Data format that is easy to read and write for humans and easy to parse and generate for machines.
Microservice	Architectural style that structures an application as a collection of small services, each running in its own process and communicating with lightweight mechanisms.
Performance	Ability of a software system to provide a certain level of service in terms of throughput, response time, and resource utilization.
Reliability	Ability of a system to perform and maintain its functions in routine circumstances, as well as hostile or unexpected circumstances.
Scalability	Ability of a software system to handle a growing amount of work or its potential to accommodate growth.
Security	Ability of a software system to protect data and functionality from unauthorized access and malicious attacks.
Testability	Ability of a software system to be tested.
Usability	Degree to which a software can be used by specified consumers to achieve quantified objectives with effectiveness, efficiency, and satisfaction in a quantified context of use.

Term

Definition

API

Application Programming Interface, which is a set of rules and protocols that allows different software applications to communicate with each other.

Backend

Internal part of the application’s architecture, which is responsible for processing requests and generating responses.

CI/CD

Continuous Integration and Continuous Deployment, which is a set of practices that automate the integration of code changes and the deployment of applications.

Container

Standardized unit of software that packages up code and all its dependencies so that the application runs quickly and reliably from one computing environment to another.

Database

Collection of information that is organized so that it can be easily accessed, managed, and updated.

Frontend

External part of the application’s architecture, which is visible to the user and interacts with the backend.

JSON

Data format that is easy to read and write for humans and easy to parse and generate for machines.

Microservice

Architectural style that structures an application as a collection of small services, each running in its own process and communicating with lightweight mechanisms.

Performance

Ability of a software system to provide a certain level of service in terms of throughput, response time, and resource utilization.

Reliability

Ability of a system to perform and maintain its functions in routine circumstances, as well as hostile or unexpected circumstances.

Scalability

Ability of a software system to handle a growing amount of work or its potential to accommodate growth.

Security

Ability of a software system to protect data and functionality from unauthorized access and malicious attacks.

Testability

Ability of a software system to be tested.

Usability

Degree to which a software can be used by specified consumers to achieve quantified objectives with effectiveness, efficiency, and satisfaction in a quantified context of use.