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.
1. Introduction and Goals
WIQ is a web application developed by HappySw that allows users to play an online quiz game.
The questions are automatically generated from Wikidata data and can be grouped by topic. In the main game mode, players can answer the questions in a set amount of time and can later check their record and the number of correct and incorrect answers.
1.1. Requirements Overview
The main functional requirements to be met are:
-
Users must be able to register
-
Users must be able to consult their participation history
-
Each question must have one correct answer and several incorrect answers.
-
Questions must have a time limit to answer them
-
Access to the user’s data must be allowed through an API.
-
Access to the information of the generated questions must be allowed through an API.
1.2. Quality Goals
The quality goals in order of priority are as follows:
| Quality goal | Description |
|---|---|
Performance efficiency |
Question generation must be efficient |
Availability |
Users must always be able to play, regardless of the number of users or problems with third-party services used |
Usability |
The application must be easy to understand and use |
Maintainability |
The application must be testable and easily modifiable |
Security |
The login password of users must be encrypted. Other sensitive information must be kept secure |
1.3. Stakeholders
| Role/Name | Contact | Expectations |
|---|---|---|
Teachers |
They interact with the development team and review the project to detect and correct errors |
The application must meet all functional requirements and must follow the quality goals |
RTVE (client) |
Company commissioning the development of the application |
The company hopes that the application will be easy to use for all users and that it will be a good version of its "Saber y Ganar" programme |
Development Team |
They are the creators of the project |
They must develop an application that meets all the requirements and is attractive in order to attract as many users as possible |
Users |
End-users who will interact with the application |
They expect it to be user-friendly, attractive and similar to the programme it imitates ("Saber y Ganar") |
2. Architecture Constraints
2.1. Technical constraints
| Constraint | Description |
|---|---|
Wikidata |
The generation of the questions should be done automatically with the data from Wikidata |
Web access |
The application must be accessible via the web |
Git and GitHub |
Version control and project tracking will be done using Git. GitHub is used to remotely store the repositories |
2.2. Organizational constraints
| Constraint | Description |
|---|---|
Team |
The development team is composed of 4 people |
Repository control |
The repository has a "main" and a "develop" branch and numerous "feature" branches where new functionalities are developed |
Meetings |
At least one weekly team meeting is held to maintain proper organisation |
2.3. Conventions
| Convention | Description |
|---|---|
Arc42 |
The arc42 template is used in the documentation |
AsciiDoc |
The documentation is done using AsciiDoc as markup language |
3. System Scope and Context
3.1. Contents
3.1.1. Scope and context
This project aims to develop a quiz game. The main constraints are developing the game as a web app and using Wikidata to obtain the questions and answers.
3.2. Business Context
3.2.1. Contents
-
Users: They interact directly with the application through the user interface provided by the frontend using React, HTML, CSS, and JavaScript.
-
Wikidata API: The application communicates with the Wikidata service to obtain questions and answers related to different topics. Requests are made using the HTTP protocol, and response data is received in JSON format.
3.2.2. Motivation
Regarding the information exchanged with the application, it will require having a registered account to play, and it will also exchange information with a MongoDB database and Wikidata itself to obtain the questions.
3.2.3. Form
Quiz Game |
Comunication Partners |
Inputs |
Outputs |
Users |
User Interface |
User answers |
Game questions |
Wikidata API |
API Service |
Question requests |
JSON Responses |
3.2.4. Context diagram
3.3. Technical Context
3.3.1. Contents
-
HTTP Channel: The application uses the HTTP protocol to communicate with the Wikidata API service.
-
MongoDB Data Channel: Interactions with the MongoDB database allow for storing and retrieving questions and answers.
3.3.2. Deployment diagram
4. Solution Strategy
4.1. Contents
This page contains a short summary and explanation of the fundamental decisions and solution strategies, that shape system architecture.
4.1.1. Technology Decisions
Below, all the technologies to be used in the development of the application are listed:
-
JavaScript / React: A JavaScript library designed to facilitate the development of web applications.
-
Material UI: Set of user interface components for web applications.
-
JavaScript / NodeJS: An asynchronous runtime environment based on JavaScript.
-
MongoDB: A document-oriented NoSQL database system.
-
Docker: Used for deploying applications locally.
-
Azure: Used for deploying applications on a server.
4.1.2. Top-Level Decisions
In this section, a summarized list of all decisions regarding the architecture of the application is included.
Architectural Pattern |
In this project, the pattern based on the Microservices model is used. |
Frontend (Client) |
React: Building the user interface |
Backend (Server) |
NodeJS: Building the server on the backend |
Mongoose: Interaction with the database |
|
Database |
MongoDB: NoSQL database storing data in BSON format |
Deployment |
Azure cloud services |
4.1.3. Quality Goals
Next, several quality goals are established, along with the decisions made to achieve them.
| Quality Goal | Decisions |
|---|---|
Usability |
Creation of a responsive interface adaptable to all types of screens. |
Accessibility |
Compliance with accessibility standards to ensure a usable application. |
Maintainability |
A structured project that facilitates the maintainability of the application. |
Testing |
Assurance of a fully functional and error-free application. |
4.1.4. Relevant Organizational
Regarding the organization of the team, we have decided to use agile methodologies for better and faster group work. In this project, we will follow the best practices of the SCRUM framework.
Practices to be followed:
-
Division of the project into tasks.
-
Equitable assignment of tasks.
-
Frequent meetings on the progress of the application.
-
Construction of "Alpha" versions before the final release.
Additionally, "Issues" and the GitHub-provided Kanban (ToDo - In Progress - Done) are used for communication.
4.1.5. Motivation
This section addresses the fundamental decisions for the project’s architecture.
Deployment |
Use of Azure for application deployment |
Security |
User access control |
Monitoring |
Prometheus and Grafana for monitoring |
5. Building Block View
5.1. Level 1: Whitebox of the Overall System
5.1.1. Motivation
WIQ application is the general structure of a system in which users will have the possibility to play a game like Saber y Ganar and compare their results with their friends.
5.1.2. Contained building blocks
| Name | Description |
|---|---|
User |
Client of the application which will interact with it. |
WIQ |
System developed to be used by the users. |
WIKIDATA |
Aplication to generate the questions and answers. |
5.2. Level 2
5.2.1. Motivation
Shows how the application will work internally. The user, through the user interface, will use microservices to access the different modules with the help of the database.
5.2.2. Contained building blocks
| Name | Description |
|---|---|
User Interface |
The user will interact with the UI. |
Microservices |
It is the backend of the UI, formed by different modules. |
DataBase |
MongoDB is the chosen NoSQL database management system. It stores all the information necessary for the proper functioning of the application. |
5.3. Level 3
5.3.1. Motivation
Detailed structure of the system. Focused on the components of the User Interface and Data Access.
5.3.2. Contained Building Blocks
| Name | Description |
|---|---|
User interface |
Game screen where the user can play the game. |
Gateway service |
Allows the user interface to communicate with each microservice. |
Game Service |
Contains all user participations with the number of games played, correct/incorrect answers, and times. |
Users Service |
Allows the client to create a new account for the application and get some information about users. |
Auth Service |
Allows the client to login in the application. |
Question Generator Service |
Allows to ask him questions and receive the answers of them. |
Question Service |
Saves the questions. |
Friend Service |
Allows to add, list and remove other users of the app as friends. |
6. Runtime View
6.1. Login
For the login, the app shows the login view, which asks the user for his username and his password.
Then, the app does a login request to the users microservice, which redirect the user to the identity provider, which handles the authentication.
If the login is succesfully, the app shows the different options of the game. In case the login isn’t succesfully, a warning message is shown.
6.2. Game
When the user starts a game, the app generates a question and request the correct answer to the WikiData API. When the user choose a posible answer, the app checks if it is the correct answer. Then, this process is repeated until the end of the game.
6.3. History
In this view, the user can watch this options about his past games:
-
Number of games played
-
Best times
-
Correct/incorrect questions
7. Deployment View
7.1. Infrastructure Level 1
7.2. Motivation:
The system is based on a microservices architecture in which each service is responsible for a specific aspect of functionality. One service is the graphical interface (WebApp), which is responsible for the presentation layer of a web application. The user service is responsible for managing user-related functionalities, while the auth service is responsible for authenticating users. The question generation service uses Wikidata, a free and open database, to generate questions automatically. The Friends service is responsible for managing the social aspect of the application, allowing users to connect with their friends. The question service allows to save and retrieve information from the generated questions, and the game service does the same for game-related data and statistics. MongoDB, a NoSQL database, is used to store the information. All microservices connect to the graphical interface through an API Gateway.
7.3. Quality and/or Performance Features::
The main reason we have chosen a microservices architecture is to achieve a fast and efficient application, while allowing changes to be made to certain parts of the application without the need to bring it to a complete halt. The application is deployed in an Azure virtual machine and each of the application components is in a separate container thanks to the use of Docker. The availability and efficiency of the application will be affected by the availability of Wikidata, but only at the time of question generation.
7.4. Mapping of Building Blocks to Infrastructure::
| Element | Description |
|---|---|
Browser |
The browser on the user’s device where they can access to the application. |
WebApp |
The graphical interface through which users can interact. |
API Gateway |
The API that comunicates the rest of the microservices with the graphical interface. |
Question generation service |
The microservice responsible for generating questions through Wikidata. |
Wikidata |
The Wikidata API that allows us to access its information. |
Question service |
The microservice responsible for saving and getting information about the questions. |
Game service |
The microservice responsible for saving and getting information about the games. |
User service |
The microservice responsible for managing users. |
Friends service |
The microservice responsible for managing the social aspect of the application. It allows users to connect with their friends. |
Auth service |
The microservice responsible for managing the authentication of the users. |
MongoDB |
A NoSQL based database where we can save the user’s data. |
8. 1.0 Designs
In the user interface concept, we have opted for a darker shade that is more pleasing to the eye, very easy to use, and fully adapted to any desktop and mobile device. Below are images of some of these interfaces.
8.1. User Page
8.2. Home Page
8.3. Game page
9. Cross-cutting Concepts
9.1. Maintainability:
We designed the application in a modular way to facilitate its maintenance and task division. We separated functions for reuse in different parts of the code, such as React components.
9.2. Usability:
We researched user needs to design a simple and intuitive interface. We employed a user-centered approach and followed recommended usability guidelines such as font size, interface colors, etc.
9.3. Security:
We store only essential information with user passwords encrypted for security. Unregistered users will not be able to access others' information.
9.4. Testing:
Usability and functionality tests are conducted to gather feedback and create the best possible product.
9.5. Expansions:
Various expansions to the application are proposed, such as a multiplayer version or adaptability to mobile devices.
9.6. Data persistence and availability:
Application data is stored using MongoDB, one of the most commonly used NoSQL databases. The application can be deployed at any time locally or in an environment such as a virtual machine.
10. Architecture Decisions
| Decision | Motivation |
|---|---|
Docker |
It is decided to use Docker due to its popularity in the professional field and its ease of execution thanks to the configuration files provided by the subject’s faculty. Docker allows the project to be encapsulated into portable containers, ensuring consistent runtime environments across development, testing, and production. |
Microservices Architecture |
Breaking down the application into independently deployable services offers flexibility, scalability, and fault isolation. Microservices promote team autonomy and facilitate the adoption of diverse architecture decisions for each component. It also facilitates teamwork, by dividing members' tasks, mainly focused on one service per task. |
MongoDB |
It is decided to use MongoDB based on the recommendation of the faculty, as it is one of the most popular NoSQL databases and because it fits perfectly with the application’s needs. MongoDB’s flexible document model aligns well with the application’s data requirements, providing scalability and performance benefits. |
NodeJS |
It is decided to use NodeJS since it is the recommended option by the subject’s faculty and one of the most widely used technologies in this area of web applications, thus having extensive documentation and examples available on the Internet, that extensive library ecosystem and community support offer ample resources for building robust server-side logic. |
React |
It is decided to use React since it is the recommended option by the subject’s faculty. React optimizes rendering performance, ensuring a responsive user interface for the web application. |
11. Quality Requirements
11.1. Quality Scenarios
-
Usage Scenarios
| Quality Goal | Scenario | Response |
|---|---|---|
Performance efficiency |
The user wants to start answering questions. |
The application generates a set of questions. This generation should be as fast as possible. |
Usability |
A new user starts using the application. |
User should be able to do it without difficulty. |
Security |
The application must encript sensible data. |
Data will be only accessible by its owner. |
-
Change Scenarios
| Quality Goal | Scenario | Response |
|---|---|---|
Maintainability |
Introduce new functionality. |
Reuse key components in order to easily add that new functionality. |
12. Risks and Technical Debts
12.1. Risks
| Risk | Description |
|---|---|
Teamwork failures |
The distribution of tasks must be done effectively, so that if one member of the team does not perform an assigned task, it can be solved by another member. |
Version management problems |
Errors in version control can delay the project. Ignorance of the branches and their purpose can lead to code conflicts. |
Lack of time |
Not planning work well can result in difficulties meeting deadlines. |
Use of unknown technologies |
The use of languages and technologies unknown to group members can make it difficult to perform assigned tasks. |
Non-optimal design |
Poorly considered design decisions can lead to a fragile or difficult-to-scale architecture, leading to long-term maintenance issues. |
12.2. Technical debts
| Risk | Description |
|---|---|
Insufficient documentation |
A lack of clear documentation about code and architecture can make it difficult to understand and maintain code, leading to additional work. |
Lack of refactoring |
The accumulation of redundant or outdated code can hinder future modifications and improvements, increasing the technical complexity of the project. |
Poor test coverage |
The absence of adequate test coverage can result in software that is prone to bugs and vulnerabilities that go undetected during the development. |
Bug pile-up |
Failure to properly resolve known bugs during development can result in code that is more problem-prone. |
13. Testing
13.1. Unit Tests
Unit tests are used to test individual units of code, such as functions or methods. In the context of microservices, unit tests can be used to verify the functionality of each microservice. To reduce the possibility of errors that are not due to the microservice being tested, any dependencies that the microservice calls can be mocked.
13.2. Acceptance Tests
Acceptance tests allow us to evaluate the functionality of the graphical part of the application by simulating the behaviour that a user would have.
| Test Case | Description |
|---|---|
Registration |
Test the registration functionality. |
Login |
Test the login functionality. |
Logout |
Test the logout functionality. |
Language Change |
Test the language change functionality. |
Add and Delete Friends |
Test the add and delete friends functionality. |
Play in Classic Mode |
Test the play in classic mode functionality. |
Play in Infinite Mode |
Test the play in infinite mode functionality. |
13.3. Load and stress tests
Load and stress tests allow us to evaluate the behavior of the system under different numbers of users and specific conditions. Load tests test the system’s performance with varying user loads, while stress tests push the system to its limits under extreme conditions.
| Test Case | Description | Response time <800ms | Response time 800-1200ms | Response time >1200ms | No response |
|---|---|---|---|---|---|
Load test 1 |
Test with a low number of users. |
100% |
0% |
0% |
0% |
Load test 2 |
Test with a medium number of users. |
84.3% |
9.1% |
6.6% |
0% |
Stress test 1 |
Test with a peak of 1000 users. |
64.5% |
13.9% |
20.2% |
1.4% |
Stress test 2 |
Test with a peak of 1500 users. |
47.9% |
10.8% |
36.4% |
4.9% |
Stress test 3 |
Test with a peak of 2000 users. |
49.2% |
10.6% |
22.3% |
17.9% |
14. Monitoring with Grafana and Prometheus
Monitoring is a crucial part of application development as it allows us to obtain real-time information about the performance and health of the system. In this case, we used Grafana and Prometheus to collect and visualize monitoring data.
14.1. Memory and CPU Usage
Grafana and Prometheus enable us to monitor the memory and CPU usage of the system. This helps us identify potential bottlenecks and optimize the performance of our application. We can visualize real-time graphs that show the evolution of memory and CPU usage over time.
14.2. Number of Requests and Response Time
In addition to memory and CPU usage, we can also monitor the number of requests our application receives and the response time of these requests. This allows us to identify potential performance issues and optimize the responsiveness of our application. Grafana and Prometheus allow us to visualize graphs that show the evolution of the number of requests and response time.
14.3. Number of Calls to Each Endpoint
Another important metric we can monitor is the number of calls made to each endpoint of our application. This helps us identify the most frequently used endpoints and optimize their performance. Grafana and Prometheus allow us to visualize graphs that show the number of calls to each endpoint.
With monitoring using Grafana and Prometheus, we can gain a comprehensive view of the performance and health of our application. This enables us to make informed decisions to improve the performance and responsiveness of our application. <<<<
15. Glossary
| Term | Definition |
|---|---|
React |
JavScript library, we make use of this User Interface library on the front-end |
Docker |
We use it to deploy applications within virtual containers |
Node.js |
JavaScript runtime environment, we make use of this on the back-end |
GitHub |
Portal used to host the application code and documentation |
MongoDB |
NoSQL database management system used in the application |
Continuous Integration (CI) |
Development practice where developers merge their code changes into a shared repository, triggering automated builds and tests to detect integration errors early in the development process. |
Microservices |
Architectural style where an application is composed of loosely coupled, independently deployable services that are organized around business capabilities. Each service represents a small, focused component. |
Session Management |
The process of handling and maintaining user session information between requests. It involves managing user information during it’s interaction with the web application. |
Scalability |
The ability of a system to handle increased workload or demand by adding resources without impacting performance or availability. |