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 Spanish TV and news company RTVE has hired the software company HappySW to develop a web application based on the successful TV program "Saber y Ganar" called WIQ. The application will be a trivia style game composed by a series of questions with multiple answers dynamically generated by the use of the WikiData API.
1.1. Requirements Overview
The system will follow the functionality of the "Saber y Ganar" TV program, and so it will allow the users to select an answer between some options.
The questions and answers will be automatically generated using the WikiData API, that will also determine which of the answers is in fact the correct one.
In adition to this, the system will also store the historical data of the users, thanks to the login and registering service featured in the application, and users will be able to access their information.
The application will have at least English as an available language.
Moreover, the project will be stored and deployed through GitHub.
Lastly, the system will give access to non sensitive user’s information through a public API as well as another API for the questions generated.
1.2. Quality Goals
Quality attribute | Scenario |
---|---|
Usability |
The user must be able to start playing a game before the minute mark. |
Performance |
The application will be able to operate within reasonable response times, taking into account the already present waiting times (time to answer, between questions, etc). |
Security & Privacy |
The information stored about a user can only be accessed by said user, never others. |
Robustness |
The application will be able to handle any user or external systems (Wikidata) errors. |
Accessibility |
The application will be accessible by all users, even if the suffer from visual impediments such as colorblindness. |
1.3. Stakeholders
Role/Name | Contact | Expectations |
---|---|---|
Development team |
Lucía Ruiz Núñez, Mario Junquera Rojas, Jorge Cano Martinez, Laura Gómez Menéndez, Ahmet Erdem Yabaci, Daniel Sinne Argüelles |
A working, tested and well documented application. |
Professors |
Pablo González |
Provide guidance and help during the whole development, as well as evaluate the final product. |
RTVE |
RTVE |
A working and robust application that the users can enjoy using. |
Users |
Users |
A working and enjoyable application to play with. |
2. Architecture Constraints
2.1. Technical constraints
- Wikidata
-
The information needed must be got from this central storage.
- GitHub
-
All the communication and code-sharing will be done by GitHub, so all the work will be recorded there.
- Open API
-
Give access about users and generated questions through an open API.
2.2. Organizational constraints
- Team size
-
The team is formed by 6 people.
- Meetings
-
There will be a meeting every week where will be discussions about problems we could have, make an overview about the work done and the work to be done among other things.
- Time
-
There will be several deliveries and the entire project must be developed and finished in the semester of the course.
- Budget
-
There will not be any financial support.
2.3. Political constraints
- Data protection
-
The private information of the users must be stored securely.
2.4. Conventions
- English
-
As this course is taught in English, the project must be also developed in that language.
- ARC42
-
The documentation must follow the arc42 template
3. System Scope and Context
3.1. Business Context
Table for entities, inputs and outputs
Entity | Inputs | Outputs |
---|---|---|
User Interface UI |
Users request a question to be shown |
The question and the set of answers corresponding to that question are presented |
Question Generation |
System requests a question and the information extracted from wikidata |
The question and the set of answers corresponding to that question are created |
Wikidata API |
Topic to create a question |
Correct anwser for the topic asked |
3.2. Technical Context
The user will access the web application via the HTTP protocol
The home will allow user to be redirected to the login and authentication phase via the HTTP protocol
The login will access the users database directly via an internal network
The login will allow the user to enter the game menu
The game will access the users database directly via an internal network
The game will access the questions database directly via an internal network
The question generator will access the question database directly via an internal network
4. Solution Strategy
4.1. Technology decisions
- The technologies chosen for developing the WIQ web app are
-
-
Java : Java is a high-level, object-oriented programming language developed by Sun Microsystems. It is known for its portability, security features, and wide range of applications, from mobile to enterprise systems.
-
Nodejs : Node.js is an open-source, cross-platform JavaScript runtime environment that executes JavaScript code outside of a web browser, allowing developers to build scalable network applications.
-
ReactJS : A JavaScript library that facilitates the creation of interactive grafical interfaces.
-
Wikidata Toolkit : Wikidata Toolkit is a Java library for accessing Wikidata and other Wikibase installations. It can be used to create bots, to perform data extraction tasks (e.g., convert all data in Wikidata to a new format), and to do large-scale analyses that are too complex for using a simple SPARQL query service.
-
Express : Express is a minimal and flexible Node.js web application framework that provides a robust set of features for building web and mobile applications.
-
Mongo DB : MongoDB is a popular open-source NoSQL database management system that stores data flexible, JSON-like documents with dynamic schemas.
-
Docker : Docker provides tools and a runtime environment to manage these containers efficiently, allowing developers to build, ship, and run applications consistently across different environments.
-
- This decisions were eventually discarded
-
-
Sass : A scripting language that is compiled into CSS. It extends CSS by providing several mechanisms such as variables, nested rules, mixins, functions, and inheritance.
-
TypeScript : A superset of JavaScript that adds various features that can resolve code errors before running the actual code.
-
SpringBoot : An extension of the Spring framework for creating Java applications. SpringBoot offers many preconfigurations that accelerate the code production process.
-
MySql : MySQL is an open-source relational database management system that uses SQL for managing and manipulating data.
-
4.2. Top-level Decomposition
To be updated along the development of the application where we will add the most important architectural and design patterns
4.2.1. Architectural Patterns
-
Microservices : Selected as our main architecture. We will have various small independent services that interact between them to support all the fuctionalities of the web application.
-
API Gateway : This API gateway serves as a centralized point for managing, securing, and routing requests between clients and multiple backend services or APIs. This is applied to centralized the calls to the different microservices.
-
Shared data : An architectural pattern used to communicate two services through a data repository. In our case, we will communicate the questions generator and the game through a database for a better efficiency and robustness.
4.2.2. Design Patterns
-
Façade : Pattern used to communicate between different parts of the whole application (APIs).
-
Template : Pattern used to set some fixed steps of an algorithm. This was used for the different questions generators.
4.3. Decisions for achieving quality goals
Quality Goal |
Decision |
Usability |
We will try to make some rounds of usability tests with people outside of the development team |
Performance |
Our goal is to have a system that will response under 1 second to all petitions, however the consecuences of peak times are unknow |
Security |
Using HTTPS, applying input validation, encripting sensible information (As we face new security failures we will add measures) |
Robustness |
We will apply different mechanism to reduce the risks that could crash the application |
Accesibility |
Testing our User Interface with third party tools like Google’s Lighthouse in order to correct them |
Will be updated whenever we find a new quality goal or we change the approach to achieve it
4.4. Organizational Decisions
Third Party Product |
Reason |
Git |
Easy to use distributed version control application |
Github |
Web-based platform for hosting and managing Git repositories. It also provides different services like: a wiki, issues, github actions and many more |
Microsoft Azure |
Cloud service use for creating virtual machines in order to deploy the application |
5. Building Block View
5.1. Scope and Context
- Motivation
-
In this level of descomposition of our system we present an overall view of it. This captures the whole system interaction at once without much detail.
- Contained Building Blocks
-
-
WIQ: Resembles the whole system. Manages the interactions with the users and communicates with the outside services (wikidata).
-
5.2. Level 1
- Motivation
-
In this level of descomposition we separate the main services of our system showing how not every part of the system communicates with the exterior.
- Contained Building Blocks
-
-
Webapp : The web part of our application that will use the wiq services to let the user play.
-
Gateway service : Service that will redirect every call to our endpoints to the specific one.
-
WIQ Services : Our collection of endpoints that will attend any need of our Webapp as well as giving support to external calls.
-
5.3. Level 2
- Motivation
-
In this level of descomposition of the system we identify the different views of the webapp and microservices of the WIQ services.
- Contained Building Blocks
-
-
Webapp Home : First view of the webapp.
-
Webapp Log in and Register : Views of the webapp that allow the user to get into the application.
-
Webapp Game menu : Intermediate view between the records and the actual game.
-
Webapp User’s games records : View where the user will be able to see different statistics of the games played (Correct answers, points, total games).
-
Webapp Question Game : Game view where the user will be able answer the random question by choosing 1 of 4 possibilities.
-
WIQ Services Authentication service : Microservice that will let the user log in a created account.
-
WIQ Services User service : Microservice that will let the user create an account.
-
WIQ Services Record service : Microservice that will manage the records of all users and will let anyone get the records of a user.
-
WIQ Services Question service Microservice that will get some random questions for an user game. It will also let anyone get random questions from outside our system.
-
WIQ Services Question generator Microservice that will generate the random questions accesing wikidata and load them into the system.
-
6. Runtime View
In this section we will focus on developing which views of the webapp use which microservices from the WIQ Services. Mind that some of these processes work the same way when called from outside the system (look for them at the API docs)
6.1. Runtime Scenario: Signup
6.2. Runtime Scenario: Login
6.3. Runtime Scenario: Generation of questions
6.4. Runtime Scenario: Play a game
6.5. Runtime Scenario: Accessing a record
7. Deployment View
7.1. Infrastructure Level 1
This diagram shows the infrastructure of our application when deployed.
8. Cross-cutting Concepts
8.1. Domain concepts
8.1.1. Domain model
8.2. User experience concepts
8.2.1. Consistency
Design elements should be consistent throuhgout the design, so that the user does not get confused.
8.2.2. Progress indicators
Provide the users with some sort of progress indicator within the quiz. This helps users understand their current position in the quiz.
8.2.3. Feedback on correct or incorrect answers
Provide immediate feedback to users after they answer each question, indicating whether their response was correct or incorrect.
8.2.4. Internationalization
Provide language options other than english.
8.3. Security and Safety concepts
8.3.1. Secure storage
Make sure to never store the user passwords in plain text, to secure the users data.
8.3.2. Data encryption
Utilize encryption techniques to secure data in any transmission between actors of our application.
8.4. Architecture and design patterns concepts
8.4.1. Microservices
The microservices pattern combines design patterns to create multiple services that work interdependently to create a larger application. Because each application is small, it’s easier to update them when needed. We will be using this pattern during development.
8.5. Under-the-hood concepts
8.5.1. Question and User Databases
To enhance consistency and reduce reliance on Wikidata, our project employs two distinct databases. The first database serves as a repository for questions generated via Wikidata’s API, which are then utilized within the application. The second database stores various other datasets, including user information.
8.6. Developement concepts
8.6.1. Continous Integration
The developement will intent for the maximum possible code coverage, and to be deployed in an Azure Virtual Machine using Continous Integration.
8.6.2. Task branching
We should create 1 branch per issue and merge them as soon as possible.
8.6.3. Error handling
In case of an exception/error, the system will pressent user-friendly messages informing of the error. This messages will only be delivered in the worst case, when all other attempts to resolve the issue have been exhausted.
8.7. Operational concepts
8.7.1. User history
The application will maintain a record of user game history, encompassing details such as game timestamps, earned points, questions posed, correct response and selected response.
9. Architecture Decisions
The application will be carried out following a Microservices architecture.
The service in charge of comunicating with WikiData will be coded using Java.
As the generation of questions is a huge part of our application we will play it safe by using Java, a language where most of the team is "fluent" at.
The backend will we develop using a combination of SpringBoot, for the question generation, and Express.
The use of SpringBoot was a requirement in order to generate the questions in Java.
10/03/24
We will apply a data share strategy where we will load the questions generated and access them when needed through the backend.
This is done to increase the efficiency, as questions are not generated when needed, and robustness of the application, as we can give service even if Wikidata is down.
14/03/24
We have done a redisign of the architecture of the project where we will implement the whole backend using Express.
This was done to have a more homogeneus backend as we have de-coupled the question generation from the backend and we dont need all to be Java.
10. Quality Requirements
10.1. Quality Tree
10.2. Quality Scenarios
Quality | Scenario |
---|---|
Usability |
The application must be easy to use and usable in a computer. |
Accessibility |
The application must be usable by people with disabilities. |
Integrity |
The personal information of a user will only be viewable by him/her and user data must be stored securely. |
Performance |
The application must have fast response times. |
Robustness |
The application must answer as expected under all conditions. |
11. Risks and Technical Debts
In decision-making processes, we often face constraints. These constraints, known as risks and technical debt, are compromises made to achieve goals. Risk involves the possibility of not desired outcomes, while technical debt entails short-term solutions instead of long-term sustainability. Both are important considerations, as excessive acceptance can lead to future complications.
11.1. Risks
There is the table of risks the team is taking for development purposes.
Risk | Explanation | Solution |
---|---|---|
Insufficient knowledge of Tecnologies |
None of our team members worked with React nor Express nor MongoDB before. |
The people who’s going to work on these technologies are going to learn it which trades time for a better application as we use stronger technologies (React instead of HTML). |
Working with a team |
It might be difficult working with people on projects, as every person has their own way of doing things. |
Have weekly meetings deciding on what’s going to get solved, how and by whom, keeping bus factor in mind. |
Time |
It should be kept in mind that the team has deadlines with different requirements, demanding them to work regularly. |
Have better time-management skills, keep track of and help each other to not waste any time on hard / complex parts of the project. |
11.2. Technical debts
There is the table of technical debt shortcuts the team is taking sacrificing long-term solutions.
Technical debt | Explanation |
---|---|
CORS |
The team has fully enabled CORS through the backend this is a risk as external users can access endpoints like adduser |
12. Testing
Here lies a detailed description of some of the test of the application.
12.1. Jest tests
These tests are used to check that all what must be rendered in a component, it is really rendered. There must be one jest test for each React component. If there is a React component named Login.js, its should be named Login.tests.js. As many times, to test one component we need others, we must to mock the responses from Gateway, using axios.
12.2. End-to-End tests
End-to-End tests are commonly known as e2e tests and are used to simulate the user interaction with the application from start to finish, validating its overall functionality. They are composed of two files: the "file.feature" which has written the steps that are specified in the other file "file.steps.js". They follow the convention of "Given-When-Then" and were done using Puppeter and Cucumber
12.3. Generator tests
For the generator some unitary tests were developed. There are two different types.
12.3.1. Question tests
This ones are designed to test that the questions work perfectly. This does not test whether the questions are generated properly, for that is the resposability of other tests. They do not require to access Wikidata, since they are testing the most internal parts of our application.
12.3.2. Generator tests
This tests are designed to test each one of the specific generators (for example, CapitalGenerator, VideogameDeveloperGenerator, DirectorGenerator, etc). As opposed to the question tests, this are focused on the correct access to Wikidata and generation of the questions. They do require to access Wikidata, since they test how our application generates the questions, which are obtained from Wikidata.
12.4. Load testing
For load testing two different kind of test were designed. The first ones were based on the pressencce of a high number of users, across a "long" period of time. On the other hand, the second ones were though with the idea of a big number of users arriving almost simmultaniously.
The first ones were designed to test the application under "normal" circunstances, while the second ones were designed with an unexpected user peak in mind.
12.4.1. Constant traffic tests
-
600 users playing as guests: Arriving in batches of 10 users per second over 60 seconds. → Result PDF
-
1200 users playing as guests: Arriving in batches of 20 users per second over 60 seconds. → Result PDF
-
20 users playing normally: Arriving in batches of 2 users per second over 10 seconds. They log in, play and check the results. → Result PDF
12.4.2. Burst traffic tests
-
2400 users playing as guests: Arriving in batches of 200 people per second over 12 seconds. → Result PDF
-
1200 users playing normally: Arriving in batches of 100 people per second over 12 seconds. They log in, play and check the results. → Result PDF
As we can see, in the first kind of testing, the percentage of successful requests is between 99 and 100%. However things change when moving into the second kind, with a success rate of 91% for the ones playing as a guest and 82% for the ones logging in. Despite not being such great numbers as the other ones, this still represent a lot of successes under a very stresfull situation for our application.
13. Glossary
Term | Definition |
---|---|
Docker’s container |
A Docker container is a lightweight, standalone, executable package that contains everything needed to run a piece of software, including the code, runtime, libraries, and dependencies. |
Github actions |
Github actions let you build, test, and deploy your code right from your repository, making it easier to manage and automate your software development processes. |
Google’s Lighthouse |
Google’s Lighthouse is an open-source tool that provides audits for performance, accessibility, progressive web apps, and more, giving developers actionable feedback on how to improve their websites. |
HTTPS |
HTTPS (Hypertext Transfer Protocol Secure) is the secure version of HTTP, the protocol used for transferring data between a web browser and a website. |
Stakeholder |
Anyone involved in the development process of the system, or that is affected by it somehow. |
CORS |
CORS (Cross-Origin Resource Sharing) is a mechanism that allows resources on a web page to be requested from another domain outside the domain from which the resource originated. |