Skip to content

Commit

Permalink
Merge pull request #352 from Arquisoft/documentation
Browse files Browse the repository at this point in the history
Adding documentation to develop branch
  • Loading branch information
uo289689 authored Apr 28, 2024
2 parents 2e258c7 + 92c264d commit a05bd01
Show file tree
Hide file tree
Showing 75 changed files with 410 additions and 162 deletions.
Binary file modified docs/images/05_level1.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/05_level2_gatewayService.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/05_level2_multiplayerService.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/05_level2_questionGenerationService.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/05_level2_userService.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/05_level2_webApp.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/05_level3_routesQuestionGenerationService.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/05_level3_routesUserService.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/05_level3_servicesUserService.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/05_level3_srcWebApp.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion docs/images/06_create_a_group_seq.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions docs/images/06_exit_a_group_seq.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion docs/images/06_group_details_seq.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion docs/images/06_join_a_group_seq.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion docs/images/06_login_seq.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion docs/images/06_play_seq.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions docs/images/06_profile_seq.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions docs/images/06_ranking_seq.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion docs/images/06_register_seq.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion docs/images/06_statistics_seq.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/07_deployment_view.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed docs/images/07_development view.png
Binary file not shown.
Binary file modified docs/images/08_domain_model_1.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/08_domain_model_2.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/08_homepage.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/10_quality_tree.PNG
Binary file added docs/images/13_conf_recording_gatling_1.png
Binary file added docs/images/13_responses_per_second_2.png
Binary file added docs/images/13_responses_per_seconds_1.png
Binary file added docs/images/13_results_gatling_1.png
Binary file added docs/images/13_results_gatling_2.png
Binary file added docs/images/13_statistics_1.png
Binary file added docs/images/13_statistics_2.png
Binary file added docs/images/14_coverage.png
Binary file added docs/images/14_graphic_sonarcloud.png
Binary file added docs/images/15_monitoring_1.png
Binary file added docs/images/15_monitoring_graphics.png
Binary file added docs/images/15_monitoring_metrics.png
10 changes: 10 additions & 0 deletions docs/index.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -96,4 +96,14 @@ include::src/11_technical_risks.adoc[]
// 12. Glossary
include::src/12_glossary.adoc[]

<<<<
// 13. Appendix I: Load tests
include::src/13_appendix1_load_tests.adoc[]

<<<<
// 14. Appendix I: Other tests
include::src/14_appendix2_testing.adoc[]

<<<<
// 15. Appendix I: Monitoring
include::src/15_appendix3_monitoring.adoc[]
4 changes: 2 additions & 2 deletions docs/src/01_introduction_and_goals.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ One of the most relevant requirement is that the questions are generated from Wi
To do the game we are going to develop a web application that will be available to enter from any device with internet connection.

Regarding quality requirements, the goal is to achieve an optimal level, especially in terms of usability,
maintainability, efficiency, security, and testability.
maintainability, efficiency, and testability.

The main stakeholders in the project are several. Firstly, Professor José Emilio Labra, who teaches the
subject. Also, the students and members of the HappySoftware development team. Lastly, potential users of
Expand Down Expand Up @@ -92,7 +92,7 @@ A table with quality goals and concrete scenarios, ordered by priorities
|Quality goal|Concrete scenario
|Usability|It must be easy to use the app, thus everybody could use it
|Availability|The system should be available the most time possible
|Security|The user's data must remain confidential.
|Testability|Functionalities must be covered with tests to ensure correct behavior
|Performance|Using the system must be as smooth as possible. Especially, the question generation must be fast.
|===

Expand Down
7 changes: 4 additions & 3 deletions docs/src/04_solution_strategy.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@ To develop the app we will use the following technologies:
* Docker Compose to deploy all the microservices
* GitHub for version control
* WikiData API to obtain question and answer information
* ExpressJS to build the backend

We have considered the trade-offs that belong to each technology, such as SpringBoot or PHP for the backend of the app.
However, JavaScript was the language that adapted better to our requirements due to the simplicity of the language and its
Expand Down Expand Up @@ -105,14 +106,14 @@ Quality goals are explained in detail in point 10.
|Quality goal| Decisions to achieve it.
|Usability| We are going to use real users to test the app interface and improve it according to their feedback.
|Availability| Docker Compose will be helpful to avoid problems with the deploy of the app. In addition we will use web hosting to expose it to the internet.
|Security| A login system with encrypted password storage will be used to protect the user data.
|Testability| We created unit and e2e (integration) test set to test the application
|Performance| We will use the minimum required calls to the APIs to mantain the minimum time response, for example, with bulk requests.
|===

=== Relevant organizational decisions

Our framework will be based on working every week with two weekly meetings, one will be held during lab time in order to assign tasks and make minor decisions.
On the other hand, the weekend meeting will be intended for more thorough reviews as well as more significant decisions.
Our framework will be based on working every week with meetings when necessary, one will be held always during lab time in order to assign tasks and make minor decisions.
On the other hand, further meetings will be intended for more thorough reviews as well as more significant decisions.

Each assigned task will be created as an Issue in GitHub to track the progress done. In addition, we are going to use GitHub Projects to organize the workflow of the team.
To merge the code to the develop branch we are going to use Pull Requests in order to be approved by every person of the team.
Expand Down
79 changes: 39 additions & 40 deletions docs/src/05_building_block_view.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -108,11 +108,11 @@ Motivation::
First decomposition of the system.

Contained Building Blocks::
* **Web App**: It is the main module of the application.
* **Gateway Service**: Handles the communication between the user service and question service modules with the web app service.
* **Question Generation Service**: Gets questions from Wikidata and handles their loading into the database.
* **User Service**: Handles the user management.
* **Multiplayer Service**: Handles the multiplayer management.
* **webapp**: It is the main module of the application.
* **gateway**: Handles the communication between the user service and question service modules with the web app service. Is is the API REST.
* **questions**: Gets questions from Wikidata and handles their loading into the database.
* **users**: Handles the user management.
* **multiplayer**: Handles the multiplayer management.
* **MongoDB**: MongoDB database.
* **MariaDB**: MaiaDB database.

Expand All @@ -125,13 +125,13 @@ Other Important Interfaces::
****
Here you can specify the inner structure of (some) building blocks from level 1 as white boxes.
****
==== White Box Users Service
==== White Box users

image:05_level2_userService.png["Diagram White Box Users Service"]
image:05_level2_userService.png["Diagram White users"]

Motivation::

Decomposition of the User Service black box from level 1 system.
Decomposition of the users black box from level 1 system.

Contained Building Blocks::
* **Routes**: Contains route handlers for the users.
Expand All @@ -140,55 +140,55 @@ Contained Building Blocks::
Other Important Interfaces::
* **index**: Define the entry point of the User Service.

==== White Box Question Generation Service
==== White Box questions

image:05_level2_questionGenerationService.png["Diagram White Box Question Generation Service"]
image:05_level2_questionGenerationService.png["Diagram White Box questions"]

Motivation::

Decomposition of the Question Generation Service black box from level 1 system.
Decomposition of the questions black box from level 1 system.

Contained Building Blocks::
* **Routes**: Contains route handlers for the questions.
* **Services**: Contains data logic.

Other Important Interfaces::
* **index**: Define the entry point of the Question Generation Service.
* **index**: Define the entry point of the questions.
* **utils**: Define auxiliar functions and questions structure.

==== White Box Web App

image:05_level2_webApp.png["Diagram White Box Web App"]
image:05_level2_webApp.png["Diagram White webapp"]

Motivation::

Decomposition of the Web App black box from level 1 system.
Decomposition of the webapp black box from level 1 system.

Contained Building Blocks::
* **public**: Contains image and audio files.
* **src**: Contains the components, pages and data of the front-end application.

==== White Box GatewayService Service
==== White Box gateway

image:05_level2_gatewayService.png["Diagram White Box GatewayService Service"]
image:05_level2_gatewayService.png["Diagram White Box gateway"]

Motivation::

Decomposition of the Gateway Service black box from level 1 system.
Decomposition of the gateway black box from level 1 system.

Contained Building Blocks::
* **gateway-service**: Define the routes for handling the communication between the user service and question service modules with the web app service.

* **prometheus**: Contains the configuration of grapfana and prometheus
Other Important Interfaces::
* **monitoring**: Uses Grafana and Prometheus to monitor the application.

==== White Box Multiplayer Service
==== White Box multiplayer

image:05_level2_multiplayerService.png["Diagram White Box Multiplayer Service"]
image:05_level2_multiplayerService.png["Diagram White Box multiplayer"]

Motivation::

Decomposition of the Multiplayer Service black box from level 1 system.
Decomposition of the multiplayer black box from level 1 system.

Contained Building Blocks::
* **index**: Handles the multiplayer management.
Expand All @@ -199,68 +199,67 @@ Contained Building Blocks::
****
Here you can specify the inner structure of (some) building blocks from level 2 as white boxes.
****
==== White Box routes from User Service
==== White Box routes from users

image:05_level3_routesUserService.png["Diagram White Box routes from User Service"]
image:05_level3_routesUserService.png["Diagram White Box routes from users"]

Motivation::

Decomposition of the black box routes from User Service white box from level 2 system.
Decomposition of the black box routes from users white box from level 2 system.

Contained Building Blocks::
* **user-routes**: Contains route handlers for the register, ranking,groups management and statistics management.
* **user-routes**: Contains route handlers for the register, ranking, groups management, statistics management and questions record management.
* **auth-routes**: Contains route handlers for the login.

==== White Box services from User Service
==== White Box services from users

image:05_level3_servicesUserService.png["Diagram White Box services from User Service"]
image:05_level3_servicesUserService.png["Diagram White Box services from users"]

Motivation::

Decomposition of the black box services from User Service white box from level 2 system.
Decomposition of the black box services from users white box from level 2 system.

Contained Building Blocks::
* **user-model**: Define the User, Statistics and Group database schemas.
* **authVerifyMiddleWare**: Authentication Middleware.

==== White Box routes from Question Generation Service
==== White Box routes from questions

image:05_level3_routesQuestionGenerationService.png["Diagram White Box routes from Question Generation Service"]
image:05_level3_routesQuestionGenerationService.png["Diagram White Box routes from questions"]

Motivation::

Decomposition of the black box routes from Question Generation Service white box from level 2 system.
Decomposition of the black box routes from questions white box from level 2 system.

Contained Building Blocks::
* **question-routes**: Contains route handlers for the questions management.

==== White Box services from Question Generation Service
==== White Box services from questions

image:05_level3_servicesQuestionGenerationService.png["Diagram White Box services from Question Generation Service"]
image:05_level3_servicesQuestionGenerationService.png["Diagram White Box services from questions"]

Motivation::

Decomposition of the black box routes from Question Generation Service white box from level 2 system.
Decomposition of the black box routes from questions white box from level 2 system.

Contained Building Blocks::
* **question-data-model**: Define the Question database schema.
* **question-data-service**: Responsible for managing questions in the database.
* **wikidata-service**: Responsible for getting questions from Wikidata.

==== White Box src from Web App
==== White Box src from webapp

image:05_level3_srcWebApp.png["Diagram White Box src from Web App"]
image:05_level3_srcWebApp.png["Diagram White Box src from webapp"]

Motivation::

Decomposition of the black box src from Web App white box from level 2 system.
Decomposition of the black box src from webapp white box from level 2 system.

Contained Building Blocks::
* **components**: Defines common elements in the pages like the nav-bar, footer, etc.
* **pages**: Defines the different screens of the application.
* **data**: It contains the data used by the pages.
* **App**: Main entry point for the application logic. Defines the application's theme and navbar routes.
* **index**: Initializes the application and renders the main component (App.js) to the DOM.

Other Important Interfaces::
* **index**: Define the entry point of the Web app.


16 changes: 15 additions & 1 deletion docs/src/06_runtime_view.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,11 @@ image:06_statistics_seq.svg["See User Statistics Sequence"]
image:06_instructions_seq.svg["See Games Instrucions Sequence"]


=== See Users and Groups Ranking

image:06_ranking_seq.svg["See Ranking Sequence"]


=== Groups
==== Group List and Creation

Expand All @@ -67,11 +72,20 @@ image:06_create_a_group_seq.svg["Group Creation Sequence"]

image:06_join_a_group_seq.svg["Group Joining Sequence"]

==== Group Exiting/Deletion

image:06_exit_a_group_seq.svg["Group Exiting Sequence"]

==== Group Details

image:06_group_details_seq.svg["Group Details Sequence"]


=== Play Games

image:06_play_seq.svg["Play Games Sequence"]
image:06_play_seq.svg["Play Games Sequence"]


=== See and edit your profile

image:06_profile_seq.svg["See Profile Sequence"]
12 changes: 7 additions & 5 deletions docs/src/07_deployment_view.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -42,16 +42,18 @@ See https://docs.arc42.org/section-7/[Deployment View] in the arc42 documentatio
****

We have several services deployed in a single containter using Docker Compose, this eases the deployment.
We have several services deployed in a single virtual machine using containers and Docker Compose, this eases the deployment.
This are the different container and their relations:

- WebApp: The web page. Gets data from Gateway Service.
- Gateway Service: data access interface for services.
- AuthService and UserService: manages authentication and login systems.
- MongoDB: persistance system used in the application.
- Users: manages authentication and statistics about users.
- MariaDB: persistance system used in the users data.
- MongoDB: persistance system used in the questions data.
- Grafana and Prometeus: code monitoring systems.
- QuestionGenerationSystem: generates questions to use in the game.
- Questions: generates questions to use in the game.
- Multiplayer: permits users to play multiplayer games.

We are going to use an Azure VM to deploy all this services.

image::07_development view["Deployment View"]
image:07_deployment_view.png["Deployment View"]
Loading

0 comments on commit a05bd01

Please sign in to comment.