Merge pull request #318 from Arquisoft/docs/documentation-fixes

Fixes to the documentation

docs/index.adoc

@@ -78,9 +78,13 @@ include::src/10_quality_requirements.adoc[]
 include::src/11_technical_risks.adoc[]
 
 <<<<
-// 12. Glossary
-include::src/12_glossary.adoc[]
+// 12. Testing
+include::src/12_test.adoc[]
+
+<<<<
+// 13. Glossary
+include::src/13_glossary.adoc[]
 
 <<<<
 // 13. Annex
-include::src/13_annex.adoc[]
+include::src/14_annex.adoc[]

docs/src/09_architecture_decisions.adoc

@@ -6,33 +6,109 @@ ifndef::imagesdir[:imagesdir: ../images]
 
 During the application development process, decisions had to be made as issues emerged. The most interesting design decisions are reflected in this architectural records:
 
-[options="header",cols="1,4"]
-|===
-|Decision|Explanation
-|React
-|Offers a powerful combination of performance, flexibility, and developer experience, making it a popular choice for building modern web applications. One of the members of the group has already worked with it in the past. It allows us to build a good user interface for the application.
+=== Main webapp technology
+*Date Recorded:* 01/02/2024
 
-|SpringBoot
-|This choice is based on the extensive experience accumulated by our team in developing with Java, as well as the familiarity and comfort offered by the tools and practices associated with the Spring Boot ecosystem.
+*Scope:* frontend, webapp
 
-|PostgreSQL
-|We have chosen to use the PostgreSQL database instead of MongoDB due to the relational nature of PostgreSQL, which offers a robust and coherent structure for storing and relating data. We made this decision to ensure data integrity, perform complex queries, and maintain consistency in our storage operations.
+*Description:*
+Offers a powerful combination of performance, flexibility, and developer experience, making it a popular choice for building modern web applications. One of the members of the group has already worked with it in the past. It allows us to build a good user interface for the application.
 
-|React Libraries
-|To enhance the efficiency and effectiveness of our development process, we've taken proactive steps to incorporate specific libraries into our project. These carefully chosen libraries, meticulously outlined in detail within issue #16.
+*Decision taken:*
+The frontend team has agreed to use *React* or a React framework, as all members agree they are not up to the task of maintaining a personalised stylesheet.
 
-|HTTPS
-|To improve security we have decided to make HTTPS as one main requirements in out project as can be seen in issue #51.
+=== React technology to be used
+*Date Recorded:* 01/02/2024
 
-|Architecture of the Question Generator
-|It has been decided to implement the QG in an independent module so it is only run once and it is not generating questions at real time, this way, we are not dependent on wikidata for having our application available.
+*Scope:* frontend, webapp
+
+*Description:*
+The frontend team has been discussing whether to use React or a React framework like Next.js as it is the currently recommended option.
+
+*Decision taken:*
+The frontend team has agreed to use a *pure React-based approach* due to most members not having any kind of prior experience with React and those that do have it are do not feel confident enough in their skills.
+
+=== Main backend technology
+
+*Date Recorded:* 01/02/2024
+
+*Scope:* backend, API
+
+*Description:*
+The backend team wants to deprecate the given Node.js microservices system in favour of a monolithic Springboot-based approach. This is mainly due to only one member having prior experience in Node.js development. No members support keeping the current approach, and when asked if SpringBoot would allow a possible microservices constraint, a member of the backend team has stated that a proper-developed SpringBoot application should be easy to divide between different microservices.
+
+*Decision taken:*
+The backend team has agreed to use *SpringBoot* and *JPA* for the backend.
+
+=== Replacing MongoDB with a relational DBMS
+
+*Date Recorded:* 01/02/2024
+
+*Scope:* database
+
+*Description:*
+A member of the backend has proposed the replacement of MongoDB as DBMS, with PostgreSQL replacing it. A member of the frontend team has supported it, remarking modern DBMS have built-in JSON support if needed. Other members of the backend team have stated their agreement, as many of them do not have prior experience with MongoDB and prefer relational databases.
+
+*Decision taken:*
+The team has agreed to drop MongoDB and to use *PostgreSQL*.
+
+=== Libraries for React
+*Date Recorded:* 09/02/2024
+
+*Scope:* frontend, webapp
+
+*Description:*
+To enhance the efficiency and effectiveness of our development process, we've taken proactive steps to incorporate specific libraries into our project. These carefully chosen libraries, meticulously outlined in detail within issue #16.
+
+*Decision taken:*
+The team has agreed to use Chakra UI as the main library for the frontend.
+
+
+=== HTTP/2 and HTTPS
+*Date Recorded:* 23/02/2024
+
+*Scope:* security
+
+*Description:*
+To improve security we have decided to make HTTP/2 and HTTPS  one of the main requirements in our project as can be seen in issue #51.
+
+*Decision taken:*
+The team has agreed to use *HTTP/2* and *HTTPS*.
+
+=== Architecture of the question generator process
+*Date Recorded:* 03/03/2024
+
+*Scope:* backend, question generator
+
+*Description:*
+The question generator must be a part of our application, but different to the webapp or the API, it doesnt need to be running on a loop. It just needs to be run once everytime we want to load or update questions. Implementing it in the API module would result on more coupling but not duplicating code for the model. On the other hand, implementing it in a new module would make the application cleaner and easier to change.
+
+*Decision taken:*
+The team has decided to implement the question generator as a *separate module* of our application.
+
+=== Connect to the database with the question generator
+*Date Recorded:* 10/03/2024
+
+*Scope:* backend, question generator, database
+
+*Description:*
+The backend team has been discussing whether to use JPA or JDBC to connect to the database with the question generator. When researching JPA it was found that although it is easier to use since the models already exist in our API, the models cannot be used from a different package, which makes us duplicate code as we do not have time to research another way of implementing it. On the other hand, JDBC would be more complex to use and does not have the same level of flexibility as JPA.
+
+
+*Decision taken:*
+The team has agreed to use *JPA* to connect to the database with the question generator. Although this will generate duplication of code in the models, it should be manageable due to the small size of the project. This will be recorded as technical debt and  new approach should be looked into if the project grows in size.
+
+=== Workflow of the game logic
+*Date Recorded:* 19/03/2024
+
+*Scope:* backend, game logic
+
+*Description:*
+The game logic must be implemented in the backend, since implementing it in the frontend would make it very dependent on performance and prone to allowing cheating and exploits. The questions will be served to the frontend each round but then validated in the backend, to prevent cheating. Points will also be automatically calculated in the backend.
+
+*Decision taken:*
+The team has agreed to implement the game logic in the backend to make it more robust and prevent cheating.
 
-|Template method pattern
-|We chose to apply our software design knowledge and generate the questions following a template method in Java. This allows us to create new questions easily and without duplicating too much code.
 
-|Use of JPA in the Question Generator
-|We used JPA in favor of JDBC as when tables are related in a DB, JPA makes it easier to write into the DB.
-|===
 
-If needed, more details are given in the link:https://github.com/Arquisoft/wiq_en2b/wiki[wiki].
 

docs/src/10_quality_requirements.adoc

@@ -20,53 +20,42 @@ To obtain a measurable system response to stimulus corresponding to the various
 | Reliability | The system shall reliably generate accurate and diverse questions from Wikidata. User registrations, logins, and game data storage shall be handled without errors. | High, Medium
 | Availability | The system shall be available 99% of the time when a user attempts to access it. | High, High
 | Performance efficiency | The system shall deliver optimal performance, ensuring responsive interactions for users. It shall efficiently generate questions from Wikidata and handle real-time gameplay with up to 1000 concurrent users. | High, High
-| Usability | The system shall provide a user-friendly interface, allowing users to register, log in, and play the game with a learning time of less than 4 hours. | High, Medium
+| Usability | The system shall provide a user-friendly interface, allowing users to register, log in, and play the game with a learning time of less than 15 minutes. Other functionalities that are not that obvious, such us rules or about pages, are allowed for 2 hours. | High, Medium
 | Security | User data shall be securely handled. Robust authentication mechanisms shall be in place for user registration and login. API access points for user information and generated questions shall be secured with proper authorization. | Medium, High 
 | Compatibility | The system shall be compatible with various web browsers and devices, providing a seamless experience for users regardless of their choice of platform. It shall be well-optimized for different screen sizes and functionalities. | High, Medium
-| Testability | The unit tests shall have at least 80% coverage. | High, Medium
-| Monitoring | The system shall have monitoring in place to track the performance and availability of the system. | High, Medium
 |===
 ==== Change Scenarios
 [options="header",cols="1,3,1"]
 |===
 |Quality attribute|Scenario|Priority
 | Modifiability | The system shall be designed and implemented in a way that allows for easy maintenance and updates. | High, Medium
 | Maintainability | The code of the system shall be well-documented, and modular, allowing for efficient troubleshooting and modifications. | High, Medium
+| Testability | The unit tests shall have at least 80% coverage. | High, Medium
+| Monitoring | The system shall have monitoring in place to track the performance and availability of the system. | High, Medium
 |===
 
 ==== Implementation
+===== Security
+The system is secured using Spring Security. The user data is stored in a database and the passwords are hashed using BCrypt. The API access points are secured with proper authorization. HTTPS is used to encrypt the data in transit.
 
-===== Performance efficiency
-The tests were done with a 2 core and 4 GB of memory system.
-This system's efficiency has been measured with Gatling. For the script that we used, a user already created, logged in and played a full game. After that, the user clicked to look the statistics.
-The scripts were run a total of 4 times. One with 1 user, other with 100 users, another one with 1000 users and finally one with 10000 users.
-The results of this scripts show that response times are reasonable up until 1000 users. Having 10000 users playing a game at the same time make a lot of failures.
-Here are the results.
-
-**1 user:**
-
-image::Gatling_1_user.png[align="center", title="Gatling results with 1 user"]
-
-**100 users:**
-
-image::Gatling_100_users.png[align="center", title="Gatling results with 100 user"]
+The system is also protected against SQL injection via using JPA repositories and prepared statements.
 
-**1000 users:**
+The system is also designed in such a way that prevents cheating, by limiting the options available for the user and doing all validation in the backend, such as checking if the answer is correct, preventing request forgery.
 
-image::Gatling_1000_users.png[align="center", title="Gatling results with 1000 user"]
+===== Testability
+Many different tests were done to this project as they were considered as a critical requirement for the development.
 
-**10000 users:**
+* **Unit tests:** The strongest constraint, as an 80% code coverage is mandatory to ensure code works properly.
 
-image::Gatling_10000_users.png[align="center", title="Gatling results with 10000 user"]
+* **Load tests:** They show how the system will behave under expected workloads.
 
-===== Security
-The system is secured using Spring Security. The user data is stored in a database and the passwords are hashed using BCrypt. The API access points are secured with proper authorization. HTTPS is used to encrypt the data in transit.
+* **Stress tests:** This way we can the behaviour of the system under unexpected loads, such as DDoS attacks. Although we are not protected against them yet, we could do it by using CloudFare as discussed issue #266.
 
-The system is also protected against SQL injection via using JPA repositories and prepared statements.
+* **Acceptance (e2e) tests:** The idea behind them is to ensure the correct functionality of the whole system so real user interactions will work as expected.
 
-The system is also designed in such a way that prevents cheating, by limiting the options available for the user and doing all validation in the backend, such as checking if the answer is correct, preventing request forgery.
+* **Usability tests:** They aim for the idea of knowing how easy the product is to learn and to use.
 
-===== Testability
+More information about testing can be seen in Section 12.
 
 ===== Monitoring
 The system is monitored using Spring Boot Actuator and Prometheus. The monitoring data is visualized using Grafana.

docs/src/12_test.adoc

@@ -0,0 +1,50 @@
+ifndef::imagesdir[:imagesdir: ../images]
+
+== Testing
+=== Performance efficiency
+The tests were done with a 2 core and 4 GB of memory system. However, real used VM has 2GB and 1 vCPU in order to keep costs low.
+If required, a more powerful machine could be easily used instead of the current one.
+The difference between machines is not such significant as real VM only loads API and the docker image for the DB, while the testing machine must also take care of loading the front of the website.
+
+This system's efficiency has been measured with Gatling. For the script that we used, a user already created, logged in and played a full game. After that, the user clicked to look the statistics.
+
+The scripts were run a total of 4 times. For load testing, one with 1 user, other with 100 users and another one with 1000 users. Finally one with 10000 for stress testing.
+Regarding load testing, the results of these scripts show that response times are reasonable up until 1000 users, although roughly 25% of the requests fail.
+Here are the results.
+
+**1 user:**
+
+image::Gatling_1_user.png[align="center", title="Gatling results with 1 user"]
+
+**100 users:**
+
+image::Gatling_100_users.png[align="center", title="Gatling results with 100 user"]
+
+**1000 users:**
+
+image::Gatling_1000_users.png[align="center", title="Gatling results with 1000 user"]
+
+**10000 users:**
+
+Having 10000 users playing a game at the same time make a lot of failures. However, the server does not get down so after all those users leave, the system could still run normally.
+
+image::Gatling_10000_users.png[align="center", title="Gatling results with 10000 user"]
+
+=== Functional Suitability
+To ensure the users are able to do what they are supposed to do and nothing else, both unit and acceptance testing were done.
+
+Acceptance testing tries to see if the user is able to use the application properly without crashing. However, as security is one of the most important requirements, unit testing from a 'back-end' point of view, so that as few unexpected inputs or bugs may happen in any part of the application (front-end included).
+
+On top of it, strong e2e testing was built to reensure the integrity of the software, as negative and positive test cases were introduced. Via e2e, we can also know what the user is capable of by means of normal application usage and how the system reacts to it.
+
+Unit testing was done via Jupyter for API while Jest and React Testing Library for React components in front-end views.
+Gherkin was used for acceptance testing and user story building.
+Finally, e2e tests were done in JS using Cucumber and Puppeteer.
+
+=== Usability tests
+Although they were not as much as desired, 4 usability tests were done as a way to know how easy our product is. The people tested all use internet daily, although they do not share the same level of expertise.
+
+Most people had no problem to complete the basic task (registering and playing a full game). However, one wanted to log in before signing up (probably that was just a dumb mistake).
+Regarding some more complex task, such us seeing the rules, some of the users had problems as they had not noticed the button for deploying the lateral menu.
+
+Overall, usability tests were good enough, although we would like to have some more people with a wider range of age