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
+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, …). |
+
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 |
+
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. |
+
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. |
+
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. |
+
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. |
+
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/). |
+
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/). |
+
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. |
+
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. |
+
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. |
+
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. |
+
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/). |
+
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. |
+
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. |
+
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. |
+
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. |
+
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. |
+