diff --git a/images/Start a game.png b/images/Start a game.png new file mode 100644 index 00000000..a53c9ae4 Binary files /dev/null and b/images/Start a game.png differ diff --git a/index.html b/index.html index 4b37fdc6..eefcd586 100644 --- a/index.html +++ b/index.html @@ -477,8 +477,41 @@

arc42 T +
  • 6. Runtime View + +
    • +
  • 7. Deployment View + +
    • +
  • 8. Cross-cutting Concepts + +
    • +
  • 9. Architecture Decisions
    • +
  • 10. Quality Requirements + +
    • +
  • 11. Risks and Technical Debts + +
    • +
  • 12. Glossary
    • @@ -1127,350 +1160,470 @@

    5.2. Level 2

    Database

    -

    Component that manages the authentification of users.

    -

    === Level 3

    -

    image::DOCsection5_3.drawio.png["Level 3"]

    -

    .Motivation -Detailed structure of the system. Focused on the components of the Webapp, Users API and Questions API.

    -

    .Contained Building Blocks

    -

    [options="header",cols="1,3"]

    +

    Component that manages the authentification of users.

    -
    -

    | Name | Description

    -
    -

    | User -| Client/User of the application which will interact with it.

    +
    +

    5.3. Level 3

    +
    +
    +Level 3
    -
    -

    | 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.

    +
    Motivation
    +

    Detailed structure of the system. Focused on the components of the Webapp, Users API and Questions API.

    -
    -

    | Questions History -| Component to store previous questions and where user can watch them.

    + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Table 5. Contained Building Blocks
    NameDescription

    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.

    +
    -
    -

    | Main Page -| Component that shows the main functionalities of the system.

    +
    +
    +

    6. Runtime View

    +
    +
    +

    6.1. User plays a game

    -

    | Register Users -| Component to see what users are registered on the system.

    +

    When the game is started, the app will call the createquestion service that is in charge of provide generated questions from wikidata information.

    +
    +
    +
    +Start a game +
    +
    +
    +
    +
    +
    +
    +

    7. Deployment View

    +
    +
    +

    7.1. Infrastructure Level 1

    +
    +
    +07 DeploymentView.drawio +
    +
    Figure 2. Deployment View
    +
    +
    +
    +07 DeploymentViewTest.drawio +
    +
    Figure 3. Deployment View Test environment
    +
    +
    +
    +
    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.

    +
    +
    -

    | Login -| Component to access the system by the user.

    +

    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

    +
    +
    +Domain model +
    +
    +
    +

    8.2. Performance

    -

    | Menu -| Component to navigate through the system.

    +

    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.

    -

    | Users Service -| Component that manages the creation of new users.

    +

    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

    -

    | Questions Service -| Component that manages the creation of the questions.

    +

    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.

    -

    | Historial Service -| Component that manages the history of users.

    +

    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

    -

    | Authentification Service -| Component that manages the authentification of users.

    +

    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.

    -

    | WIQ -| Main component that manages all the system.

    +

    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

    -

    | Wikidata -| Website where to get information for questions.

    +

    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

    +
    -

    | Database -| Component that manages the authentification of users.

    +
    Contents
    +

    Important, expensive, large scale or risky architecture decisions including rationales. +With "decisions" we mean selecting one alternative based on given criteria.

    -+++ - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

    <<<<

    -

    -== Runtime View

    -

    === 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. -[plantuml,"Start a game",png] ----- -actor a as "User" -participant q as "Game GUI" -participant w as "CreateQuestions service" -database d as "Database"

    -

    a → q: Start the game -loop number of questions -q → w: Ask for a question -w -→q: Returns the question -q → d: Store the question -q → a: Returns the question

    -

    a → q: Pick an answer -q → a: Shows if the answer was valid or not -a → q: Asks for next question -end -q → a: Show the game stats -q → d: Store the game with questions, answers and stats -----

    -

    <<<<

    -

    -

    == Deployment View

    -

    === Infrastructure Level 1

    -

    image::07-DeploymentView.drawio.png[title="Deployment View"]

    -

    image::07-DeploymentViewTest.drawio.png[title="Deployment View Test environment"]

    -

    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.

    -

    <<<<

    -

    -== Cross-cutting Concepts

    -

    === Domain model

    -

    image::DOCsection8_1.drawio.png["Domain model"]

    -

    === 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.

    -

    === 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.

    -

    === 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.

    -

    === 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.

    -

    <<<<

    -

    -== Architecture Decisions

    -

    .Contents -Important, expensive, large scale or risky architecture decisions including rationales. -With "decisions" we mean selecting one alternative based on given criteria.

    ====

    Decision

    Consequences

    Risks

    Uso de 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.

    Uso de 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.

    Uso de 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.

    Uso de 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.

    ====

    -

    <<<<

    -

    -== Quality Requirements

    -

    === Quality Tree

    -

    image::10_1_Quality_Tree.png[Business Context Diagram]

    -

    === Quality Scenarios

    -

    [options="header",cols="1,3,3"]
    -
    -

    | 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

    +
    +

    10. Quality Requirements

    +
    +
    +

    10.1. Quality Tree

    +
    +
    +Business Context Diagram
    -
    -

    | 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

    +
    +

    10.2. Quality Scenarios

    -+++ + + + + + + + - + + + + + + + + + + + + + + + + + +
    Quality RequirementsScenariosPriority

    <<<<

    -

    -== Risks and Technical Debts

    -

    === Technical Risks

    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
    -
    -

    | 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.

    +
    +
    +
    +
    +

    11. Risks and Technical Debts

    +
    +
    +

    11.1. Technical Risks

    -+++ - + + + + + + + + + + + + + + + + + + + + + + + + + + + +

    <<<<

    -

    -== Glossary

    -

    [cols="e,2e" options="header"]

    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.
    -
    -

    |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.

    +
    +

    12. Glossary

    +
    ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    TermDefinition

    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.
    -