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
The project is a quizz game based on the Spanish TV show "Saber y ganar", the users will be able to test their knowledge with questions from different categories and difficulties. Users will autenticate themselves into the system or create an account first.
1.1. Requirements Overview
-
Users will be able to create an account and log in
-
Each question must have a prize associated to it
-
Accesible through the web
-
Historical data of a user will be saved on that user’s account
-
Questions have a time limit to be answered
-
Possible answer will be given to the user, only one of them being correct
-
Information about users and questions will be obtained through API’s
-
Modo multijugador y modo individual
-
Se habilitarán salas de juego en tiempo real para el modo multijugador
1.2. Quality Goals
(based upon the ISO 25010 standard):
| Code | Quality Goal | Scenario |
|---|---|---|
Usability |
The user can easily navigate through the app and find the information they need |
|
Performance |
The app should be able to handle a large amount of users at the same time |
|
Mantainability |
The game should be easy to update in order to add functianlities |
1.3. Stakeholders
| Role/Name | Contact | Expectations |
|---|---|---|
Wikidata |
Wikidata.org |
Public exposure by the use of their services deriving in a greater demand of said services |
Uniovi’s Software Architecture Teacher council |
Provide their students (development team) with a practical experience about the use of Software architecture in projects and making sure the have understood the concepts of it |
|
Development Team |
Acquire experience in the development process of Software Architecture and pass the subject to complete their studies |
|
Users |
Anyone who uses the app |
Test their knowledge on a functional and easy to use quizz game app |
2. Architecture Constraints
When designing the WIQ Application there are several constraints that must be taken into consideration, as they will have a large impact on the final application. These requirements that we must follow, will ensure that the final product meets the needs and expectations of final users and stakeholders. The following table summarizes these constraints and provides a brief explanation of each.
| Constraint | Explanation |
|---|---|
Use of Wikidata |
Wikidata is a collaborative, multilingual knowledge base that provides the required information to popular websites as Wikipedia. Wikidata houses information about a wide range of entities, such as people, places, and concepts, using a linked and interconnected data model. The project will have to generate questions and responses to those questions automatically, and for this task, Wikidata can be very useful. |
Version control and monitoring (GitHub) |
GitHub and Git will be very valuable for the application, facilitating version control and team collaboration during project development. It enables the coordination and management of the development workflow, while also monitoring the modifications and contributions made by individual team members. |
User Experience |
The design of the application must make its use friendly and easy. |
Deployment |
The application must be deployed. |
2.1. Recommended technologies to take into account
The application must be a full stack application consisting of a web app and a server. These are some technologies mentioned to provide a clear understanding of this application and how it works. These are not considered constraints because they were not imposed, but they should be present in this section due to the impact they have on the project.
| Technology | Explanation |
|---|---|
React |
Description: React is a JavaScript library for building user interfaces with a component-based architecture. It promotes a declarative approach and utilizes a virtual DOM for efficient UI updates. Fit for the application: React’s component-based structure is ideal for creating reusable UI elements, aligning well with the modular nature of a trivia app. The virtual DOM enhances performance in real-time scenarios. |
ExpressJS |
Description: Express is a fast and minimalist web framework for Node.js, simplifying the creation of robust web applications and APIs. It follows a middleware pattern, making it versatile for handling various server-side tasks. Fit for the application: Express’s middleware architecture is well-suited for managing authentication, routing, and server-side concerns. Its lightweight nature and scalability support simultaneous user interactions in a multiplayer trivia game. |
MongoDB |
Description: MongoDB is a NoSQL document database storing data in flexible, JSON-like documents. It offers schema flexibility, making it suitable for applications with evolving data structures, and supports scalability and high performance. Fit for the application: MongoDB’s schema-less design allows easy adaptation to different question formats in a trivia app. Its scalability and sharding capabilities make it apt for handling large data volumes and concurrent user interactions. |
3. System Scope and Context
3.1. Business Context
The diagram shows the main 4 services the user interacts with.
Login and validation of answers are handled by external services, such as Google and WikiData.
3.2. Technical Context
The application structure is the following:
The application will be deployed on an Azure Server. It will consist of the following:
The client communicates with the web app, the front-end of the application. Developed with React and JavaScript, this application retrieves information from the server, interacting with the Gateway.
We employ a facade pattern on the server, with a dedicated Gateway service redirecting requests to different internal services.
The services include:
-
Authentication Service
-
Users Service
-
Question Generator Service
-
Game Service
-
Groups Service
All these services interact with the MongoDB database, retrieving and adding information.
To generate questions automatically, communication with the WikiData API is necessary. The Question Generator Service houses an algorithm for question generation.
4. Solution Strategy
This section aims to describe the strategies decided by the team.
4.1. Technologies
The following list names the technologies selected:
-
TypeScript: free and open-source high-level programming languaage deriving from JavaScript. The former provides tools that JavaScript does not. It will be used to program the client part of the application.
-
React: free and open-source front-end JavaScript library for building user interfaces based in components. It allows building complex interfaces in a simpler way, being flexible and easy to maintain.
-
MongoDB: non-relational document database that provides support for JSON-like storage. It has drivers for major programming languages and development environments.
-
NodeJS: cross-platform, opens-source JavaScript library for the server layer that provides the tools to implement the application. It has a large and active community that may be usefull in difficult times.
-
ExpressJS: nodejs web application framework that provides a robust set of features for web and mobile applications.
-
Wikidata Query Service: Wikimedia implementation of SPARQL server to service queries for Wikidata and other data sets.
-
Socket.io: A javascript library that enables real-time communication between client and server through objects called sockets. These objects can broadcast events asynchronously, and can be caught by other sockets to perform different operations. This library is used in the multiplayer service, to allow the players to connect to a game lobby, and compete between each other answering questions.
4.2. Organizational
-
Weekly meetings: to maintain a well communicated team so all are aware of the decissions and team progress.
-
Github: use of issues, pull request, discussions and other tools that Github offers.
5. Building Block View
5.1. Whitebox Overall System
- Motivation
-
Conocer y vencer is an aplication that generates questions using data from wikidata so the user can play a game like Saber y Ganar.
- Contained Building Blocks
| Name | Description |
|---|---|
Saber y conocer |
Aplication based on microservices for the user to interact with and play the game |
Wikidata |
Public Data based used to generate questions for the game |
5.2. Level 2
5.2.1. Webapp
Interface for the user to interact with the game and the diferent functionalities of the aplication. Each of the services have its own easy to use interface.
5.2.2. Microservices
Components of the application, that have the logic of the game and interact with external services (such as Wikidata and Mongodb). There are several microservices, one for each of the functionalities of the game.
5.3. Level 3
5.3.1. Authentification service
Service in charge of create new users in the database
5.3.2. User service
Service in charge of safe and retrieve the data of a user from the database.
5.3.3. Multiplayer
Service in charge of multiplayer rooms, the webapp comunicate directly to this service, without using the gateway.
5.3.4. Group Service
Service in charge of manage groups composed of multiple users.
5.3.5. Game Service
Service in charge of the logic of the game, safe the information of the last game played by a user.
5.3.6. Question Generation Service
Service in charge of generating the questions for the game using data from wikidata.
6. Runtime View
6.1. Interaction with the GroupService
6.2. Interaction with the Single Player Game
6.3. Sing in
6.4. Log in
6.5. Query Service
6.6. Multiplayer Game
7. Deployment View
7.1. Infrastructure Level 1
- Motivation
-
The above diagram represents the current architecture of the system. The system is divided in different services related to distinct functionalities. The application is working with multiples services, all of them are ran through docker containers in a virtual machine in Azure.
The deployment is automated through github actions, therefore when you make a release of a tag in the master branch of the repository, the application updates with the committed changes.
- Quality and/or Performance Features
-
The reasons for using a microservice infratructure are the failure isolation, if one of the service fails, is not necesary that the whole system goes down, the member teams can work on different microservices simultaneously and also each microservice can be written in a different programing language better suit for the task.
In this case, almost all the microservices communicate between each other through HTTP requests. But in the multiplayer service, a different type of communication is needed: Web sockets.
Web sockets is a communication protocol that allow server and client to send messages simultaneously without waiting for a response. This is very useful for real-time applications, like the multiplayer functionality.
- Mapping of Building Blocks to Infrastructure
| Blocks | Description |
|---|---|
Web App |
User interface to interact with the rest of the application. |
Gateway |
Following the facade pattern, the gateway works as an interface that communicates the web app with the different services. |
MongoDB |
Database to save the application’s data. |
Authentication |
Service for the authentification of the users. |
Users |
Service in charge of managing the users. |
Question Generation |
This service retrieves information from Wikidata through SPARQL queries, and generates questions based on custom templates |
Game |
Service to manage the logic of the game like the players and questions in a game. |
Groups |
Service in charge of managing the groups. |
Multiplayer |
Service in charge of the multiplayer functionality, this service uses web sockets, while the others use HTTP requests. Provides the real-time functionality for a multiplayer game. |
8. Cross-cutting Concepts
8.1. BCrypt
Bcrypt is a specialized password-hashing library for securely storing passwords. It employs a key derivation function to hash passwords intentionally in a slow and computationally intensive manner. This design choice enhances security by significantly increasing resistance against brute-force attacks.
| Element | Description |
|---|---|
Hash |
The characters that comprise the resultant hash are ./ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789$. Resultant hashes will be 60 characters long and they will include the salt among other parameters, as follows: "$[algorithm]$[cost]$[salt][hash]" - 2 chars hash algorithm identifier prefix. "$2a$" or "$2b$" indicates BCrypt. - Cost-factor (n). Represents the exponent used to determine how many iterations 2^n. - 16-byte (128-bit) salt, base64 encoded to 22 characters. - 24-byte (192-bit) hash, base64 encoded to 31 characters. |
Salt |
In cryptography, a salt is random data fed as an additional input to a one-way function that hashes data, a password or passphrase. Salting helps defend against attacks that use precomputed tables. |
Cost Factor |
Represents how many times the data is hashed, the burden. |
8.2. RoboHash
RoboHash is a web service that generates unique and customizable robot images. It uses a hash of the input data as the seed for the robot image. This service is useful for generating unique avatars for users. It is used to delegate the task of generating avatars to a third-party service as a way to reduce the complexity of the system.Otherwise we would have to allow users to upload their own images, which would require additional security measures to prevent malicious uploads.
This images have all been created with robohash, using the same input data "ASR", but with different sets. The sets are used to determine the style of the robot image.
8.3. Design and UI
You can see the first version of the prototypes in the following link: Prototypes
9. Architecture Decisions
9.1. Database Selection for Our Application
In this application, we require a database to store information about users, groups, automatically generated questions, and how the user performs on those questions. In this section, we discuss why we chose to use a NoSQL database, specifically MongoDB, for this purpose, and explore the alternatives that we considered and rejected.
9.1.1. Reasons for Choosing MongoDB
Flexibility: NoSQL databases like MongoDB are schema-less, allowing us to store data without a predefined structure. This flexibility is invaluable for applications where the data schema may evolve over time or if we have varying types of questions.
Query Language: MongoDB boasts a powerful and expressive query language that facilitates efficient data retrieval and manipulation. This is particularly useful for fetching specific questions based on criteria.
Performance: NoSQL databases are often optimized for specific use cases, and MongoDB excels in providing good performance for certain types of queries, especially when dealing with large amounts of unstructured or semi-structured data.
9.1.2. Main Alternatives Considered
Relational Database (e.g., PostgreSQL): We decided against this approach because the data we store might not have a well-defined structure and relationships.
Graph Database (e.g., Neo4j): We opted not to follow this approach because the complexity of the data we are dealing with is relatively simple in terms of complex relationships.
9.1.3. Conclusion
Our decision to use MongoDB aligns with the flexible nature of our data, the need for a powerful query language, and the performance requirements of our application.
9.2. Frontend and Backend Technology Stack Decision
In developing our application, we need to make crucial decisions about the technologies we use for the frontend and backend. Here, we discuss why we chose to use React for the frontend and Express.js for the backend, and explore the considerations that influenced this decision.
9.2.1. Frontend: React
Declarative UI: React offers a declarative approach to building user interfaces, making it easier to understand and debug code. This allows us to efficiently design interactive and dynamic user interfaces.
Component-Based Architecture: React’s component-based architecture encourages modularity, reusability, and maintainability in our codebase. This structure is beneficial for building complex applications with distinct features.
Popularity: There is a large number of developers that use React for their web applications, therefore a lot of resources available. This can save development time and provide solutions to common problems.
9.2.2. Backend: Express.js
Lightweight and Flexible: Express.js is a minimal and flexible Node.js web application framework, providing the essential features for building robust web applications. This is also useful because of the use of Docker. Express.js applications can be containerizated very well.
Routing: It provides a simple routing mechanism. It makes it easy to define routes for different parts of the application, and handle requests in an organized way.
Scalability: Express.js is well-suited for building scalable applications. Its non-opinionated nature gives developers the freedom to structure their code as needed, making it adaptable to the evolving needs of our project.
9.2.3. Conclusion
Our decision to use React for the frontend and Express.js for the backend, apart of being the mentioned advantages, was that the initial project was built with these technologies, and we already had a base to work on for future developments.
9.3. Multiplayer Technology
In order to get have multiple player in the same game we decided to use the JavaScript library that enables real-time, bidirectional, and event-based communication between the browser and the server.
9.3.1. Communicating directly with frontend
Socket.IO communicates directly with the frontend without using a gateway because it’s designed to establish a persistent, bidirectional connection between the client (frontend) and the server.
9.4. Deployment Technology: Azure
Scalability: Azure allows us to quickly scale our application up or down to match demand, ensuring we only pay for what we use.
Security: Azure has robust security measures in place, including encryption, multi-factor authentication, and threat detection.
Global Reach: With Azure’s vast global network of data centers, we can deploy our application closer to our users for improved performance.
Analytics and AI: Azure provides powerful analytics and AI services that can be integrated into our application to provide advanced features and insights.
9.4.1. Other alternatives
Certainly, there are several alternatives to Azure for deploying your application. Here are a few:
Amazon Web Services (AWS): AWS is the most popular cloud service provider. It offers a wide range of services for computing, storage, databases, analytics, and more. AWS is known for its scalability, security, and extensive global network.
Google Cloud Platform (GCP): GCP is another major player in the cloud services market. It offers similar services to AWS and Azure, and is particularly strong in areas like machine learning and data analytics.
IBM Cloud: IBM Cloud offers a wide range of services including IaaS, SaaS, and PaaS. It’s known for its AI capabilities, BaaS (Blockchain as a Service), and strong support for open source technologies.
DigitalOcean: DigitalOcean is a cloud infrastructure provider that offers cloud services to help deploy, scale and automate modern applications. It’s known for its developer-friendly platform, predictable pricing, and high performance virtual machines (droplets).
Heroku: Heroku is a cloud platform as a service (PaaS) that supports several programming languages. It’s known for its ease of use, developer-friendly features, and strong support for app deployment automation.
Each of these alternatives has its own strengths and weaknesses, and the best choice depends on your specific needs and circumstances.
9.4.2. Conclusion
Our decision to use Azure for deployment was based on these advantages, as well the support that azure give to students, ganting us credits.
10. Quality Requirements
10.1. Quality Tree
| Quality Category | Quality | Description | Scenario |
|---|---|---|---|
Usability([QG1]) |
Ease of use |
Ease of use for the user |
|
Ease of Learning |
The standard functions should be as easy and intuitive to use as possible without the need for lengthy prior instruction |
||
Compressible questions |
The system shall generate compressible questions using information from Wikidata |
||
Performance([QG2]) |
Responsiveness |
Pages shoud load at a resonable time. During the game the answers to the questions must be processed by the system quickly |
|
Robustness |
The system shall work reliable under all specified environment and operating conditions. |
||
Mantainability([QG3]) |
Ease of update |
The game should be easy to update in order to add functianlities or patch the |
10.2. Quality Scenarios
| Id | Scenario |
|---|---|
After a small tutorial, the user should be able to play the game. |
|
When playing a game, the player whose turn is currently playing will answer autogenerated questions. |
|
When a user accesses the game web page it loads correctly the page in a short time, when he logs in or accesses other pages of the application the same happens. When accessing the game the page loads and informs the player that the game is loading. |
|
When a user under normal connection and a normal number of users in the system, the user navigates though the application and is able to play the game without encountering any errors, white pages, etc. |
|
Due to the microservices structure in order to add a new functinality, is easy to update sections without affecting the rest of the code |
11. Risks and Technical Debts
Risk |
Explanation |
Risk minimization measure |
Bottleneck in response times |
In the team we are worried about possible bottlenecks regarding the porfarmance of the application, specially the performance of the question generation system as it must ask wiki data for information, the time of this my very depending on wich data is asked |
Analize the performance of the application and substituing slow question by faster ones |
Availability of technologies used |
The application depends on some technologies to work properly, most notabilly wikidata, if wikidata or any of the technologies we depend upon are experiencing issues or are not working, the application may not work as expected |
Explore options for the application to still work in those cases |
12. Glossary
| Term | Definition |
|---|---|
Gateway |
Converst information, data or other communications from one protocol or format to another. |
Facade pattern |
Analogous to a facade in architecture, a facade is an object that serves as a front-facing interface masking more complex underlying or structural code. |
JavaScript |
An object-oriented computer proframming language commonly used to create interactive effects within web browsers. |
Database |
Structured set of data held in a computer. |
Prototipe |
A model of the views for the web application. |
Query |
Question or request for information expressed in a formal manner. The retrieved information comes from a database. |
13. Anex I: Load test
When performing a the load test for the login and single player game with 1000 users conecting over a minute, we found that less than a 5% of the response end in a KO. This KO are due to the creation and start of the game.
When we create the game we also create all the questions with wikidata query service. To solve this problem we could look for more optimiced queries or change when the questions are created, once a day we could create a bunch of questions and sav e them in the database, with this approach, when creating a new game the questions would be selected from our local database.
14. Anex II: Usability test
The tests were carried out with a sample of 10 users with different backgrounds. Being 3 of them students from Software Engineering.
14.1. Effectiveness
-
100% of users completed the tasks on the first try.
-
80% of users did not need extra help to navigate the web.
14.2. Efficiency
-
All users did each task in less than 10 seconds, including answering the questions of the game.
-
80% of users did not need extra help to navigate the web.
14.3. Satisfaction
-
1 user though the questions should be harder.
-
2 users found a bug that is now fixed: when you play, close session, login again and go to profile, the last questions do not appear.
-
6 users tried to login with google, but it only works with test users.