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
CyT (Conocer y Triunfar) is a project forked from the University of Oviedo latest base repo offered by the Software Architecture course. The development team (es05b) is formed by the following engineering students:
-
Donato Martín, UO288787@uniovi.es
-
Luna Valdés, UO289321@uniovi.es
-
Álvaro García, UO289295@uniovi.es
-
Rubén Rubio, UO276255@uniovi.es
-
David Álvarez, UO288705@uniovi.es
This is basically a Trivial Pursuit like game inspired in spanish TV show "Saber y Ganar" aimed to develop its users' general knowledge as well as increasing their reflects, analytical thinking and also their focus. This will be achieved with all the main app functionality that includes:
-
Scoring systems based on response times
-
Different question categories
-
A history of past games
1.1. Requirements Overview
The main goal of this project is to develop a web application that will allow users to play a Q&A game with multiple categories. The application must have the following functionalities:
-
A front-end web that allows users to register and play the game.
-
A user registration system with a history of their games.
-
All the questions data must be obtained from the WikiData knowledge database.
-
The application must have an API to obtain users information.
-
The application must have an API to obtain generated questions.
Further information can be found here.
1.2. Quality Goals
The following table describes the project’s quality goals in descending order.
| Quality Goal | Motivation |
|---|---|
Efficiency |
As it’s a game, one of its main objectives is efficiency, as the game needs to run swiftly and smoothly. |
Usability |
The application must be not only easy to learn and use but also fun because if a game has no joy in it, then it shall never be called for that name. |
Maintainability |
Projects must always have enough quality to be able to be modified without making more changes than necessary. Not following this principle would heavily increase costs in new feature implementation or bug solving that may arise in the future. |
Scalability |
Given an exponential growth of users, the application should allow for capacity resizing and overall a robust handling for a large number of connections. |
Testability |
The performance of the system is needed to be tested covering as many use cases as possible so all the other goals will be met. |
Security |
Security is always key and therefore effort will be put into fighting against unauthorised access of information, including the users' personal or sensitive data that the information system may contain. |
1.3. Stakeholders
| Role/Name | Description | Expectations |
|---|---|---|
Development Team |
|
The engineering students are expected to improve communication, teamwork and coding skills adopting a developer role in this project. |
Teachers |
|
Teachers are in charge of supervising the developers work aswell as helping them solve environment, development issues or any other that may arise. |
Users |
|
They are just expected to use this project as it is intended to work. |
2. Architecture Constraints
2.1. 1. Technical Constraints
These constraints are set by the project, and we believe that altering them would be counterproductive, therefore, we have chosen to adhere to them.
2.2. 1. Technical Constraints
| Constraint | Explanation |
|---|---|
Docker |
The app will be running in a Docker Host due to its outstanding interoperability, robust security mechanisms, and its effectiveness in deploying applications |
Wikidata |
This project will be using Wikidata to retrieve the source of the game questions |
Git/GitHub |
Our development process will leverage Git for version control and GitHub as a remote repository. This combination empowers us to: collaborate effectively, maintain a clean codebase and assign tasks |
2.3. 2. Organizational Constraints
| Constraint | Explanation |
|---|---|
Team |
Our team consists of five members who are new to collaborating with each other. |
Time |
Deadline at the end of the semester, the time is divided among two hours per week of in-class work, multiple meetings with team members, and individual self-work. We’ll also have four deliverables spaced every two weeks, where we’ll receive feedback from the instructor. |
Testing |
Various scenarios will be explored to accurately assess the application’s functionality. Diverse testing techniques will be employed to achieve comprehensive coverage, aiming for the highest possible quality assurance. We also work with different levels of testing, including unit, integration, load, and system testing. Additionally, a shift-left testing approach will be used, where testing is performed as early as possible in the development process, following dynamics like Behaviour Driven Development (BDD) or Test Driven Development (TDD) enabling the early detection of bugs and errors. |
Tech proficiency |
All team members are beginners in the majority of the technologies we’re using, and this is our first endeavor in developing a real-world application. As a result, all of us should contribute to the project as fullstack developers. |
2.4. 3. Convention Constraints
| Constraint | Explanation |
|---|---|
Clean Code |
The code composing the application must prioritize clarity and cleanliness, facilitating comprehension and ease of maintenance in the long term. We adhere to camelCase for JavaScript and PascalCase for React, ensuring clear and descriptive names while steering clear of confusing prefixes. We need to adhere to the conventions of the programming languages we’re using, including JavaScript , HTML and CSS. |
Arc42 |
The project utilizes Arc42 for documentation purposes. |
Usability |
The application must be user-friendly, with a clean and intuitive interface that is easy to navigate. The user experience should be seamless and engaging, with a focus on accessibility and adaptability. So, to achieve this, we should use tools like Google LightHouse to measure the performance of the application. |
3. System Scope and Context
3.1. Business Context
Business Context diagram
| Communication partners | Inputs | Outputs |
|---|---|---|
Conocer y Triunfar |
Interaction with Wikidata to get the questions and answers and with the user to know their response |
Response to the answers of the user |
Users |
Answers to questions from the app, provides authentication data |
Interaction with the app interface to log in and play |
Wikidata |
Request an specific category’s questions and their possible answers |
Game sources |
3.2. Technical Context
Technical Context diagram
| Communication partners | Inputs | Outputs |
|---|---|---|
Jordi |
Question data-index |
Questions and answers |
User service |
Login info |
User info (account page) |
History service |
Session user info |
User’s history |
Users |
Questions and possible answers |
Interaction to log in and answer to questions |
Wikidata |
Request for question data with category |
Question sources |
Persistence |
RAW data for questions and answers |
Structured data of questions and answers |
Webapp |
User inputs |
Browser outputs |
4. Solution Strategy
4.1. Technology Decisions
In order to develop an application that meets the expected quality criteria, we have decided to use the following technologies, as they were the one given to us in the base project:
-
JavaScript: Main programming language. It is used in both back and front end.
-
React: JavaScript library used in the design of graphical user interfaces.
-
Express.js: Framework built on the top of Node.js and used in the backend.
-
MongoDB: Several instances are used to persist the information of the app.
-
GitHub: Used for versioning the project and as a mean of communication for the dev team.
-
Docker: Used for the app deployment.
-
GitHub actions: Used for testing purposes, app deployment and as a CI/CD tool.
4.2. Top-level Decomposition
We have decided to implement a microservices architecture, with different modules for different purposes. For instance, we currently have the following microservices:
-
User service: Service used to add new users, and also manage friends system.
-
Auth service: Service used for the authentication of users.
-
Gateway service: Service exposed to the public and used as a proxy to the two previous ones.
-
Webapp service. Web application that uses the gateway service to allow basic login and user features.
-
Jordi service. Service to generate and return questions from the Wikidata API.
-
User history service. Service to generate the user’s history and global ranking.
4.3. Decisions taken to achieve quality goals
| Quality goal | Decision made |
|---|---|
Usability |
The user must be able to use the application without any doubt or trouble. For this purpose, we must use internationalize the app, so it can be used by people from different countries, elect a good font and its size, and make the app responsive. |
Performance |
To optimize performance and reduce the risk of system overload, we are strategically reducing our requests to WikiData. This measure will help maintain stable service. Additionally, we are enhancing our infrastructure by upgrading from an Azure B1s VM to a more capable Oracle Cloud VM.Standard.A1.Flex instance, which features 4 CPU cores, 24 GB of RAM, and 50 GB of storage. To further alleviate server stress, we have recalibrated our monitoring probes to gather data at 15-second intervals. We are also implementing a reverse proxy in our application to serve as a load balancer. This setup efficiently distributes traffic across various microservices and caches static content, significantly reducing backend server load and improving user response times. |
Maintainability and Scalability |
The application must be well-structured so that modifications or expansions can be made in a straightforward manner without requiring excessive alterations to existing code. To achieve this, along with employing a microservices architecture, we will utilize design patterns and coding conventions to maintain clean, maintainable code. To be more specific, the Gateway Pattern and the Single Responsibility Pattern define the architectural design principles that we will follow in our microservices implementation. The Gateway Pattern will be used to provide a unified entry point for all external requests, while the Single Responsibility Pattern will ensure that each microservice has a clear and specific role. Also, we will integrate a reverse proxy to our application to serve as a load balancer, which will help us to scale our application horizontally. Also simplifies the SSL configuration and the management of the certificates. |
4.4. Organizational Decisions
We have taken the following organizational decisions:
-
Tasks: We have decided to distribute the tasks equally per person so that everyone has approximately the same workload. We think it is a good idea that once a task is done, it should be reviewed by at least 50% of the group to be taken as valid.
-
GitHub Issues: We make use of GitHub Issues to create the tasks mentioned above and assign them to different team members. We will also use them to discuss any critical decisions that need to be made about the project.
-
GitHub Projects: We also take into account GitHub Projects to organize the workflow and to track the progress of the project.
-
Language: We have agreed that we will develop the project in English so the code and documentation will use it as the main language. This way we will guarantee that the project is accessible to everyone.
-
External Meetings: We have decided to have meetings on a regular basis to discuss the progress of the project and to make decisions about the next steps to be taken.
-
Internal Communication: We have decided to use Discord as the main communication channel for the project. We will use it to discuss any issues that arise during the development of the project. The support of Github Webhooks will be used to notify the team of any changes in the repository.
-
Documentation: We have decided to use Asciidoc as the main documentation tool. This is mainly because the deployment of the documentation is easier and more intuitive given the tools that Wiq0 provides.
5. Building Block View
5.1. Whitebox Overall System
- Motivation
-
The main purpose of the system is to run a quiz game using info dynamically retrieved from the Wikidata API.
- Contained Building Blocks
| Name | Description |
|---|---|
User Agent |
Client of the application that will interact with the system. |
App |
The main component of the system to be developed. In charge of generating the questions based on the data retrieved from the Wikidata API and present them to the user as a quiz game format. |
Wikidata API |
Web service that will provide the data to be used by the application . |
5.2. Level 2:
- Motivation
-
This level aims to shed some light on the internal structure of the App component and the information flow in it.
- Contained Building Blocks
| Name | Description |
|---|---|
Web App |
React frontend in which the game will take place |
Gateway |
Service in charge of communicating the web app with the backend. Its main purpose its to forward all the requests sent from the client to the corresponding service and return the response to the client. |
Authentication |
Service which will handle the user authentication process when a new user logs in |
Users |
Service containing all user related information. |
Questions |
Service that bears the responsibility of interacting with te Wikidata API and generating the questions to be presented to the user. |
History |
Service that stores the user’s game history. |
5.3. Level 3:
- Motivation
-
This third level provides a deeper insight into the questions microservice. As the diagram showcases, it is implemented using an n-layer architecture so as to ensure a clear separation of concerns and a high degree of modularity, which in turn will make the system more maintainable.
| Name | Description |
|---|---|
Controller |
Component in charge of handling the requests sent from the gateway and returning the corresponding response. |
Service |
Module that contains the business logic of the service. It is responsible for processing the data retrieved from both the model and the Wikidata API and returning it to the controller. |
Model |
Component that interacts with the database and retrieves the data to be processed by the service. |
NoSQL Database |
Component independent for each service that contains the data related to it. |
6. Runtime View
6.1. Register
6.2. Login
6.3. Question Flow
6.4. Ranking View Flow
7. Deployment View
The infrastructure of our system consists mainly on a single server, which is hosted in an Oracle Virtual Machine arm64 running Ubuntu 22.04 LTS. It contains a dockerized Node.js app based on microservices architecture which exposes port 443 and 80 to the internet as an entry point to the user interface of the system aswell as for the API. The server contains a MongoDB database used to store the application data. The system also interacts with the Wikidata API in order to provide dynamic-generated content to the user based on the information retrieved.
7.1. Infrastructure Level 1
7.1.1. Overview Diagram
- Motivation
-
The main reason for this infrastructure choice lies in the simplicity, flexibility, and platform agnosticism of a dockerized microservice architecture solution. This allows for a fast and straightforward deployment of the system in any environment, regardless of the underlying platform. This would allow an easy migration of the system to another cloud provider if necessary, as well as the ability to scale the system horizontally by adding more instances of the same service with ease thanks to the container orchestrator.
- Quality and/or Performance Features
-
-
Scalability: The system can be easily scaled horizontally by adding more instances of the same service with ease thanks to the container orchestrator.
-
Portability: The app can be deployed in any environment that supports docker containers, which allows the system to be easily migrated to other cloud providers should it be necessary.
-
Maintainability: The system can be updated (each container can be maintained/updated individually) by replacing the docker containers with new versions of the application, which allows the system to be maintained without remarkable issues.
-
Security: The system is hosted in a secure environment (each container is a isolated environment, so in the case of a security breach, it only affects one of them) provided by the Azure cloud platform, which ensures its security and availability.
-
- Mapping of Building Blocks to Infrastructure
| Component | Description |
|---|---|
User agent |
The client that will access the system through the web app. |
Azure B1s Virtual Machine |
Server in which the system is hosted. |
Docker |
Containerization platform used to deploy the system. |
Wikidata API |
External service used to retrieve dynamic content for the system. |
8. Cross-cutting Concepts
8.1. Domain Model
8.2. User Experience
While we haven’t settled on the final appearance of the app, its core functionality revolves around a quiz game. It features multiple questions across different categories, offering various possible answers with only one being correct
8.3. Security
As we prioritize user information security, it’s crucial for our app. We’ll be encrypting users' passwords and minimizing the amount of information we request from them
8.4. Testing
To ensure the system functions correctly, we’ve opted to implement unit tests for the majority of its components. Additionally, we’ll conduct thorough checks on the overall functionality of the app to enhance the user experience. To facilitate testing procedures, we’ve are going to create a dedicated branch. This branch will be utilized specifically for conducting tests when needed
8.5. Usability
Usability is crucial for any application, as it directly impacts user interaction efficiency. To ensure our app’s usability, we conducted extensive user research, leading to an intuitive interface design. Employing a user-centric approach throughout development, we prioritized user experience, facilitating easy navigation
9. Architecture Decisions
The initial architecture decisions are in the GitHub Wiki: Wiki ADRS
10. Quality Requirements
The required quality goals are:
-
Performance: Performance is critical in the application, especially in the game itself. This is intended to save the user long waiting times between questions, providing a fast and fluid experience.
-
Maintainability and Scalability: The application must be well-structured so that functionalities can be added or modified at any time in a simple and intuitive way, which will facilitate the work of the developers.
-
Scalability: The application should be able to handle a large number of concurrent users and scale horizontally as the user base grows.
-
Availability: The application should be highly available, with minimal downtime and the ability to recover quickly from failures.
-
Reliability: The application should be reliable, with minimal errors or failures, and provide consistent and accurate results to users.
-
Testability: The application should be designed in a way that allows for easy testing, both unit tests and integration tests, to ensure the correctness of the system.
-
Monitoring and Logging: The application should have proper monitoring and logging mechanisms in place to track performance, detect issues, and facilitate troubleshooting.
-
Resilience: The application should be able to recover from failures and continue to operate in a degraded state, without impacting the overall user experience.
-
Internationalization: The application should support multiple languages and cultural preferences to cater to a global user base.
10.1. Quality Tree
10.2. Quality Scenarios
10.2.1. Usage scenarios
Privacy
| Usage Scenario | System Response |
|---|---|
The user reaches the landing page, enters the login screen and logs in. |
The system checks that the user’s information is correct, if it is, it takes them to the main page of the game, if not, it returns them to the login screen and informs them of the error. |
Performance
| Usage Scenario | System Response |
|---|---|
On the main page the user can view the different game modes, of which they must choose one |
When a game mode is chosen, the system will choose various questions to ask the user, obtain all the information corresponding to the answers and show them to the user. |
Usability
| Usage Scenario | System Response |
|---|---|
A new user starts using the application, given the design of the page, they quickly know what they have to do to register and how they have to use the application. |
Since the app has been designed with usability in mind, it will be very easy to use for new users. |
10.2.2. Change scenarios
Maintainability and Scalability
| Change Scenario | System Response |
|---|---|
Add new game mode |
When new game modes are added, the previous ones should not be modified or influenced by the new changes. All previous functionality should still be usable. |
Add alternative forms of login / signup |
When new login / signup forms of login are added (e.g. with Google accounts), the previous ones should still be valid and work properly. |
Implement hotfixes |
When critical errors are found, they must be corrected and applied on the go, in a transparent way to the user and avoiding having to shut down the service for a long period of time. |
11. Risks and Technical Debts
The technical risks and technical debts section of the document provides an overview of potential challenges and issues that may arise during the development and maintenance of the project. These risks and debts need to be carefully considered and addressed to ensure the successful completion and long-term viability of the project. The following subsections outline the internal and external technical risks, as well as the technical debts that should be taken into account.
11.1. Technical risks
We consider a technical risk a potential event that can threaten the successful completion of the project, delay timelines, increase costs, or even lead to project failure if not properly managed. The following subsections outline the internal and external technical risks that have been identified for the project.
11.1.1. Internal
| Description | Priority | Considerations |
|---|---|---|
Poor knowledge of base project and tools used |
8 |
This factor will clearly constraint the development as it creates a new set of research tasks to be accomplished by each team member, but given the deadline and the consequences of starting greenfield, it seems like the most reasonable option |
Limited expertise in emerging technologies |
7 |
Ignorance of emerging technologies relevant to the project might result in missed opportunities for innovation and efficiency. Regular training sessions or workshops should be considered to keep the team updated on the latest industry trends. |
Use of ARM64 machine |
6 |
The use of an ARM64 machine for development and deployment may introduce compatibility issues with certain software libraries and tools that are primarily designed for x86 architecture. This could result in additional effort and time required to ensure compatibility and may limit the availability of certain features or optimizations. Thorough testing and evaluation of software dependencies on ARM64 architecture is necessary to mitigate potential risks. |
Incomplete infrastructure planning |
5 |
A lack of comprehensive planning for the project’s infrastructure can result in delayed implementation and increased costs. Ensuring a detailed infrastructure plan is in place, including hardware and software requirements, is vital for a smooth project start. |
Unequal distribution of efforts across the team |
4 |
If team members are not assigned tasks and responsibilities properly, it can lead to an uneven distribution of efforts. This can result in delays, bottlenecks, and decreased productivity. Regular monitoring and effective communication are essential to ensure a balanced workload and maximize team efficiency. |
11.1.2. External
| Description | Priority | Considerations |
|---|---|---|
Oracle Cloud Failure |
8 |
The project relies on Oracle Cloud services for hosting and deployment. Any failure or downtime of Oracle Cloud services could result in service interruptions, data loss, and a poor user experience. This impact is only reduced thanks to the ease of migration of our dockerized services. |
Wikidata API failure |
3 |
Even though an API failure is possible, it’s a low impact event because we have the questions stored in the database and the game would still work. |
11.2. Technical debts
| Description | Priority | Considerations |
|---|---|---|
Lack of actual scalability |
8 |
While the project’s microservices architecture is designed to be scalable, the current implementation may not be able to handle a significant increase in traffic. This could result in performance issues, downtime, and a poor user experience. Regular load testing and performance monitoring are essential to identify scalability issues and address them before they become critical. This is mainly because load balancing and auto-scaling are not implemented yet. |
Code quality issues |
5 |
The project’s codebase may contain quality issues such as code smells, duplication, and poor code documentation. This can make the codebase difficult to maintain, extend, and debug. Regular code reviews, refactoring, and documentation updates are essential to ensure the project’s code quality and maintainability. |
Inadequate security measures |
4 |
The project’s security measures may not be sufficient to protect against common threats such as, cross-site scripting, and DDoS attacks. Regular security audits and penetration testing are essential to identify vulnerabilities and ensure that the project’s security measures are up-to-date. |
Make the entire web internationalized |
6 |
The questions are not internationalized, so you can only play in english |
Optional requirements |
8 |
Not all optional requirements are implemented |
12. 12. Testing report
12.1. 12.1. Unit tests
Every component is equipped with its own unit tests to ensure its functionality operates accurately, thereby enhancing the project’s security and resilience.
TODO finish when merge
12.2. 12.1.1. Coverage result
We employ the Sonar tool to validate that our code is thoroughly tested. If the coverage falls below 80% or if there’s more than 3% duplication, it triggers an error, halting integration until the minimum coverage is met.
12.3. 12.2. E2E tests
An end-to-end (E2E) test checks the entire application’s functionality from start to finish, simulating real user interactions to ensure it works as expected. Our end-to-end approach focused on this functionality: - Check game integrity - Menu categories - Answering a game question - Game result - Login / register
12.4. 12.3. Load tests
Load tests are conducted to assess performance under anticipated normal or peak loads. For these tests, we utilized the Gatling tool, enabling the recording of a usage scenario and adjusting the load intensity accordingly.
We approached our testing by simulating gameplay with multiple users, employing two distinct scenarios. In the first scenario, we initially load 205 requests simultaneously, followed by a 5-second pause. Subsequently, we introduce an additional 401 requests distributed over 21 seconds, concluding with a load of 48 users per second maintained for 16 seconds.
In the second scenario, we initiated 26060 requests, of which 18935 passed succesfully, with a response time lower than 1200 ms, and 7125 that failed, leaving it with a percentaje of failure of 27%.
12.5. 12.4. Usability tests
In today’s digital age, web usability plays a crucial role in ensuring a positive user experience. A website that is intuitive, easy to navigate, and responsive not only attracts users but also keeps them engaged and satisfied. Recognizing this importance, our team prioritized usability testing to ensure our website meets the needs and expectations of our target audience. To conduct comprehensive testing, we divided our participants into two distinct groups. The first group consisted of individuals with prior experience using computers and navigating websites. Their insights and feedback helped us assess the effectiveness of our interface design and navigation structure for users familiar with digital platforms. In contrast, the second group consisted of individuals with limited or no experience using computers. By including these participants, we aimed to identify any usability barriers or challenges that might difficult their interaction with our website. Their feedback provided valuable insights into areas where we could improve accessibility for individuals with varying levels of digital knowledge. By testing our website with these diverse groups, we gained a comprehensive understanding of its usability across different users. This approach not only ensures inclusivity but also enhances the overall user experience, ultimately contributing to the success of our website in meeting its objectives.
12.5.1. Group 1: Individuals with high computer exp
| User | Challenges | Strengths |
|---|---|---|
User 1 |
Tried to click the response too quickly and got confused with the answers |
Good aesthetics |
User 2 |
Too little time to answer questions, area category too weird |
Intuitive colors for correct and incorrect answers |
User 3 |
Confused by the swap button, thought that it meant switching accounts, couldn’t find logout |
Nice endgame, liked being able to see his points and time |
12.5.2. Group 2: Those with limited computer usage experience
| User | Challenges | Strengths |
|---|---|---|
User 1 |
There are too many categories simultaneously. Overwhelming, problems with register(trying to log in without an account), low time, all geography categories, wrong password message not found |
fun game, nice looking |
User 2 |
Account not found, would like a "how to play" screen, low time |
Somewhat intuitive |
User 3 |
Didn´t know that by clicking in a history game it would show details, low time |
nothing to highlight |
12.5.3. Improvements based on usability testing
Added more time to answer the questions and how to play menu
12.6. 12.4. Accessibility tests
Accessibility testing is a critical aspect of web development, ensuring that websites are usable by all individuals. By conducting accessibility tests, we can identify and address potential barriers that may prevent users from accessing or interacting with our website effectively. Our team is committed to creating an inclusive and accessible website that meets the needs of all users, regardless of their abilities or limitations.
Using lighthouse, we tested two of the views of our website, the home page, and the game page. The results are shown below.
12.6.1. Menu view
With the desktop setting we got good results:
With the mobile setting we got worse results, but as expected as the application is not fully accommodated to smaller screens.
12.6.2. Game view
With the desktop setting we got good results, a bit worse than the menu:
Same happens with the mobile setting
13. Glossary
| Term | Definition |
|---|---|
CyT |
Conocer y Triunfar |
"Saber y Ganar" |
A spanish TV show hosted by Jordi Hurtado which inspires this project |
HappySw |
The company in charge of the development of this app |
Arc42 |
Architecture documentation template used in this project |
Wikidata |
API consumed by the application to generate the questions of the game |
ADR |
Architectural Design Record. |
Continuous integration and delivery |
The process of automating the integration of code changes from multiple contributors into a single software project. |
Microservice |
Each of the components/modules in which the application is divided into. Each one is independent and can be developed, deployed and scaled independently. |
14. Legend
