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 the project of the current course of the Software Architecture course, which will be developed by the ES2B team composed by:
-
Raymond Debasa Peralta
-
Coral Izquierdo Muñiz
-
Carlos Sánchez Rodríguez
-
Pablo Fernando Urones Clavera
It consists of an application in which users can register and enter to play the quiz game.
1.1. Requirements Overview
-
The system will have at least one web frontend deployed and access will be through the Web.
-
Users will be able to register in the system and consult the history of their participation in the system: number of games, number of correct/failed questions, times, etc.
-
Questions will be automatically generated from Wikidata data.
-
Questions must be answered within a given time limit.
-
Each question will have one correct answer and several incorrect or distracting answers. Both the correct and incorrect answers will be generated automatically.
-
The system will allow access to user information through an API.
-
The system will allow access to the information of the questions generated through an API.
1.2. Quality Goals
| Goals | Details |
|---|---|
Performance |
We are going to need the application to have a good performance since we are going to make several calls and we need that these calls do not take too much time for the system to be efficient and dynamic during its use |
Usability |
The use of the application must be an intuitive and simple process for the client user |
Maintainability |
We will try to take care of the architecture of the application so that functionality can be added, modified or removed with as few changes as possible |
Testeability |
Our application may also be testable, that is, it will be subjected to a series of unit tests that we will perform to ensure proper operation of the system, in addition to identifying small errors and being able to correct them in such a case |
1.3. Stakeholders
| Role/Name | Contact | Expectations |
|---|---|---|
Client |
RTVE |
An application that emulates a quiz show and meets the requirements of section 1.1 |
Contrated Company |
HappySw |
Generic software development |
Development Staff |
Raymond Debasa Peralta, Coral Izquierdo Muñiz, Carlos Sánchez Rodríguez and Pablo Fernando Urones Clavera |
Successfully develop the application based on the documentation in a way that reflects the architectural knowledge acquired |
Users |
Future users of the application |
A usable and simple application that allows them to play quiz games |
2. Architecture Constraints
In the development of the WIQ Application, various constraints have been identified to guide the project towards success. These constraints are crucial in aligning with user expectations and meeting the diverse needs of stakeholders.
2.1. Functionality-related Constraints
These constraints pertain to the core functionality of the application.
| Constraint | Explanation |
|---|---|
Integration with Wikidata API |
Enabling seamless integration with the Wikidata API is imperative. This integration allows automatic generation of questions and responses, enhancing the application’s functionality. |
User Authentication |
Implementation of a robust login system is mandated to safeguard user privacy and control access to sensitive information within the application. |
Web Deployment |
The application must be easily deployable, ensuring convenient access for users through the web. |
2.2. Process-related Constraints
These constraints focus on the development process itself.
| Constraint | Explanation |
|---|---|
Version Control (GitHub) |
Utilization of GitHub and Git for version control is essential. This facilitates collaboration and maintains a structured workflow with effective monitoring of team contributions. |
2.3. Data Management Constraints
These constraints are associated with the management of application data.
| Constraint | Explanation |
|---|---|
MongoDB Database |
The application will leverage MongoDB, a NoSQL document database known for its flexibility in handling dynamic data structures, scalability, and high performance. |
2.4. User Interface Constraints
These constraints focus on the user interface design.
| Constraint | Explanation |
|---|---|
React for User Interface |
The application’s user interface will be built using React, a JavaScript library with a component-based architecture. This choice aims to provide a user-friendly and modular interface with efficient UI updates. |
While not constraints, the following technologies are recommended for optimal performance and functionality of the WIQ Application.
| Technology | Explanation |
|---|---|
React |
A JavaScript library for building user interfaces, known for its component-based architecture and efficient UI updates. |
ExpressJS |
A fast and minimalist web framework for Node.js, suitable for server-side tasks and supporting various web applications. |
MongoDB |
A NoSQL document database, offering schema flexibility, scalability, and high performance for storing application data. |
These constraints and recommended technologies collectively shape the architectural decisions, ensuring a robust and effective development process for the WIQ Application.
3. System Scope and Context
3.1. Business Context
Comunication Partner |
Description |
User |
Registration and participation in the competition and 1uiz results, correct and wrong questions, times and statistics. |
Database |
Queries and user-related writing and questions and system-related results, questions and users. |
Wikidata |
Requesting data for question generation from properties and categories and data to generate questions and answers. |
User’s API |
Request user information and user data, history and game statistics. |
Question’s API |
Request generated questions and history of generated questions and answers |
Graphana |
Visualization and analytics of data integrates with Prometheus to create dashboards and display metrics. |
Prometheus |
Monitoring time-series data of the application. Used to gather metrics related to the performance and health of the system. |
The agents involved in the WIQ system environment are the following:
-
User: interacts directly with the WIQ system through its web Frontend being able to register, participate in a game by answering questions and consult its history and statistics.
-
Wikidata: provides data that will be used in the automatic creation of questions.
-
Database: stores relevant WIQ data such as user information, game histories and the questions that have been generated. It also communicates directly with the system to manage and retrieve data.
-
User’s API: is given by the system to provide user information such as user histories and statistics.
-
Question’s API: is given by the system to provide information about the questions generated.
-
Grafana and Prometheus: are used to collect data about the application and display the metrics obtained.
3.2. Technical Context
Channels |
Type |
Input/Output |
SSH |
Input |
User → Frontend Web |
HTTP/REST |
Output |
WIQ → User’s API |
HTTP/REST |
Output |
WIQ → Question’s API |
HTTP/REST |
Input |
WIQ → Wikidata |
HTTP |
Input |
WIQ → Database communication |
HTTP |
Output |
WIQ → Database communication |
HTTP |
Output |
WIQ → Data monitoring and visualization |
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. |
React |
JavaScript library that allows us to create interactive user interfaces in a simple way. It is based on components. |
MongoDB |
Open source, document-oriented database system |
Docker |
A tool that makes it easy to create, deploy and run applications using containers. Containers allow you to package an application with all the parts you need, such as libraries and other dependencies, and deploy it as a single package. |
Wikidata |
Website where the information is taken from |
Javascript |
An interpreted programming language based on prototypes, imperative and dynamic. We will use it on both frontend and backend. |
CSS |
A graphic programming language oriented to define the repesentation of a document. |
Bootstrap |
A popular front-end framework for building responsive websites. |
4.2. Decisions on how to achieve key quality goals
-
Usability: The team will take care to design a clear and accessible interface for any user. This will be based on web usability standards.
-
Performance: Minimize delays in data processing, communication, or task execution to improve overall system responsiveness. As well, optimize system components, algorithms, and configurations.
-
Maintainbility: The architecture of the application must allow new functionalities to be added or existing ones to be modified with as few changes as possible.
-
Testability: This is an important quality objective to ensure that the software is reliable, robust and error-free. It is important to implement appropriate software development practices, such as separation of concerns and modular design.
4.3. Relevant Organizational Decisions
Regarding the organization within the team, we have taken the following decisions:
-
Extraordinary meetings, we do them through Discord or Microsoft Teams, because all team members are familiar with that tool.
-
Communication between team members occurs mainly through a WhatsApp group, but any problem that arises is also reflected as an issue in Github.
-
We use a Kanban board within github to have well organized and in a very clear way the tasks that each team member has to perform/is performing.
5. Building Block View
5.1. Whitebox Overall System
WIQ is the general structure of the system, where the users are going to register in the database, play answering the questions generated with Wikidata or view their previous games among other functionalities.
| Name | Description |
|---|---|
User |
Client/User of the application which will interact with it. |
WIQ application |
System developed to be used by the users. |
Wikidata |
Provides data to elaborate all the questions |
5.2. Level 2
Shows how is the system internally in general terms.
| Name | Description |
|---|---|
User |
Client/User of the application which will interact with it. |
Webapp |
It contains the user interface (frontend) and the development branch (backend). |
Microservices |
Part that takes care of the functionalities. |
WIQ |
Main component that manages all the system. |
Wikidata |
Website where to get information for questions. |
Database |
Component that manages the authentification of users. |
5.3. Level 3
Detailed structure of the system. Focused on the components of the Webapp, Users API and Questions API.
| Name | Description |
|---|---|
User |
Client/User of the application which will interact with it. |
Games History |
Component to store games played by each user and where user can watch their previous games. |
Play New Game |
Component to create all related to play a new game. |
Questions History |
Component to store previous questions and where user can watch them. |
Main Page |
Component that shows the main functionalities of the system. |
Register Users |
Component to see what users are registered on the system. |
Login |
Component to access the system by the user. |
Menu |
Component to navigate through the system. |
Users Service |
Component that manages the creation of new users. |
Questions Service |
Component that manages the creation of the questions. |
Historial Service |
Component that manages the history of users. |
Authentification Service |
Component that manages the authentification of users. |
WIQ |
Main component that manages all the system. |
Wikidata |
Website where to get information for questions. |
Database |
Component that manages the authentification of users. |
6. Runtime View
6.1. User plays a game
When the game is started, the app will call the createquestion service that is in charge of provide generated questions from wikidata information.
7. Deployment View
7.1. Infrastructure Level 1
- Motivation
-
During the development phase of the application, each team member is using Docker to run all the necessary services on a local server. For the production environment, it is planned to use a Microsoft Azure cloud server for the deployment of the application.
The infrastructure includes user access via a user agent on their computer, which connects to the web interface of the WIQ application. In this configuration, several services will be active, such as the user authentication service, monitoring services and data analysis using Grafana and Prometheus. In addition, two internal APIs dedicated to the generation and retrieval of the history of questions asked and games played by each user are provided.
- Quality and/or Performance Features
-
The quality and performance of the application have not yet been evaluated, but it is noted that we have high availability, reaching approximately 95%, thanks to the cloud service provided by Microsoft Azure.
- Mapping of Building Blocks to Infrastructure
-
For the implementation, it has been decided to implement the following elements in the infrastructure:
-
Quiz Game Application: The main application is deployed in the development environment inside different Docker containers on each team member’s local server, so that a web application made with React is deployed on port
3000. In the case of the production environment, the application would be deployed in the Microsoft Azure cloud and can be accessed publicly. -
Questions API: It is an API in charge of generating questions to the WikiData API dynamically and it also keeps a history of the questions already asked.
-
WikiData API: The application makes calls to the WikiData API to generate the game questions dynamically and it is accessed both in the development and production environment.
-
MongoDB Database: The database is executed inside a Docker container in the development environment, so that user data and game information is stored. In the production environment, this database will be managed in a Microsoft Azure service.
-
Authentication Service: The authentication service allows a user to register and log in to the application so that the data associated with their games are always linked and accessible to their user.
-
Monitoring data: The application data monitoring and analysis service is made up of two different services, one with Grafana and the other with Prometheus. Both services work together analysing and monitoring application data so that a record can be kept of the information obtained in the form of dashboards.
-
8. Cross-cutting Concepts
8.1. Domain model
8.2. Performance
A system that performs well provides a positive user experience. Users expect applications and services to respond promptly to their requests. A higher performance leads to increased user satisfaction and engagement. Also, a good performance help to get a better efficiency.
We are going to look for a good performance with the code optimization, without overloading the system and memory and doing some performance test.
8.3. Usability
Usability is a fundamental aspect of any application, as it determines the ease and efficiency with which users can interact with it. To ensure the usability of our application, we have followed a series of specific practices and techniques.
We have thoroughly researched user needs and expectations, which has allowed us to design an intuitive and easy-to-use user interface.
8.4. Maintainability
The maintainability of the application is an important section since it is necessary that the code is easily modifiable in case in the future we are asked for new features to implement.
We are going to use React, which is a framework that facilitates interactivity with the user interface, so it is important to reach users.
8.5. Testeability
As a best practice, throughout development, we will subject our code to multiple unit tests, in order to ensure the robustness and effectiveness of our product before it is deployed on the web. As well, we will test the functionality of the whole app itself, so that the user experience is the best possible.
9. Architecture Decisions
Important, expensive, large scale or risky architecture decisions including rationales. With "decisions" we mean selecting one alternative based on given criteria.
Decision |
Consequences |
Risks |
Use of React.js |
- Facilitates the development of user interfaces. - React.js is a widely popular library in the development community. - Improves the efficiency of frontend development. |
- Limited experience with React.js. - Possible learning curve for the team. |
Use of JavaScript |
- Team’s prior knowledge in JavaScript. - Extensive support and resources available. - Suitable language for frontend and backend development. |
- Limitations in compile-time error detection. - Potential challenges in performance for large projects. |
Use of MongoDB |
- Flexible schema and horizontal scalability. - Widely used in modern applications. - Compatibility with unstructured data. - Already implemented in user registration and login. |
- Not familiar with NoSQL databases. - Possible learning curve. |
Use of Docker |
- Containerization that facilitates deployment and scalability. - Consistent environment in development and production. - Streamlines dependency management. |
- Potential initial complexity in Docker configuration. - Requires additional learning resources. |
Use of Bootstrap |
- Simplifies and accelerates the development of responsive and mobile-first web applications. - Provides a wide range of pre-designed components and styles. - Offers extensive documentation and community support. |
- Learning curve for team members unfamiliar with Bootstrap. - Risk of over-reliance on Bootstrap components, leading to less customizability. |
10. Quality Requirements
10.1. Quality Tree
10.2. Quality Scenarios
| Quality Requirements | Scenarios | Priority |
|---|---|---|
Performance |
We’ll run some performance testing and search for a good code optimization performance without taxing the system’s resources or memory. Optimize the setups, algorithms, and system parts as well. |
High |
Usability |
We want to offer the user the possibility to see his personal statistics, as well as a service of access to information and data storage, in an intuitive and efficient system for customers (as fast as possible). |
High |
Maintainability |
The design and architecture will allow for flexibility in the face of unexpected events during development, this feature is important because we want to reduce costs in terms of time. |
Medium |
Testeability |
The application will be subjected to unit, acceptance and load testing to prove that it works correctly. If new functionality is added to the map, it must be thoroughly tested before deployment. |
High |
11. Risks and Technical Debts
11.1. Technical Risks
Risk |
Explanation |
Solution |
No knowladge of React |
Non member of the team has worked with React before. |
Read React’s documentation and search for exercises and tutorials of how to use the technology. |
Github |
Most of us have use it, however, some have not in a project of that magnitude. Also there are some new features for everyone. |
Transfer the knowledge of essential operations in Github from those who now them to those who don’t, as well as search information about how to use the new features for everyone. |
Lost of team members |
Any member could leave the project due to personal reasons. Risk that gets importance if we take into account we only are four members. |
Don’t make any member categorically essential, so we can avoid any part of the project from being orphaned. |
External dependencies |
As the app will be deployed on an external server, there could be a situation where we can not deployed it due to an external issue. |
Have a second deployment server in order to replace the first if it is not available. |
Insufficient tests |
The lack of tests could trigger the release of some features with a not expected behaviour. |
Make exhaustive tests on all the features that will be released on the app. |
12. Glossary
| Term | Definition |
|---|---|
React |
JavaScript library that allows us to create interactive user interfaces in a simple way. It is based on components. |
Git |
Software version control system. |
GitHub |
Cloud-based service that hosts the aforementioned version control system. |
Wikidata |
Website where the information is taken from |
Docker |
A tool that makes it easy to create, deploy and run applications using containers. |
MongoDB |
Open source, document-oriented database system. |
JavaScript |
Interpreted programming language based on prototypes, imperative and dynamic. |
CSS |
Cascading Style Sheets. Graphic programming language oriented to define the repesentation of a document. |
Draw.io |
Free application for diagramming. |
Lucidchart |
Web-based diagramming tool that allows users to collaborate and work together in real time, creating flowcharts, flowcharts, website schematics, UML designs, mind maps, software prototypes and many other types of diagrams. |
Visual Studio Code |
Independent source code editor. |
Microsoft Azure |
Cloud computing platform created by Microsoft to build, test, deploy and manage applications and services using its data centers. |
Grafana |
Grafana is a real-time data analysis and visualisation platform, especially used for monitoring and observability. |
Prometheus |
Prometheus is an open source monitoring and alarming system designed to collect metrics, store them and enable queries and alerts in modern technology environments. |
API (Application Programming Interface) |
A set of rules and tools that allow different software to communicate with each other. It facilitates the interaction and exchange of data, functions or services between different applications. |
13. Testability
Testability is a crucial aspect of software development. It refers to the ease with which a software system can be tested to ensure its correctness and reliability. By writing tests, developers can verify that their code behaves as expected and identify any potential issues or bugs. There are various types of tests that can be performed, such as unit tests, integration tests, and end-to-end tests. Unit tests focus on testing individual components or functions in isolation, while integration tests verify the interaction between different components. End-to-end tests simulate real-world scenarios to ensure the entire system functions correctly.
To achieve good testability, it is important to write code that is modular, decoupled, and follows best practices such as dependency injection. Additionally, using testing frameworks and tools can simplify the process of writing and executing tests.
13.1. Load Testing
These tests will focus on evaluating the performance of our system under high traffic and heavy usage conditions. This type of testing is crucial to identify bottlenecks and ensure that our application can effectively handle the volume of users and transactions expected in production, without compromising performance and stability.
Initially, a test was carried out with the following procedure: 1. Create a new user 2. Log in with this new user 3. View the main page
Then, a slightly more complex test was then performed, which followed the following procedure: 1. Log in to the app 2. View the main page 3. Play a new game 4. View the game history 5. View the previous game specific data 6. View the history of questions
