From 06137806d025ab6168c0230c60467ffb9abb5bef Mon Sep 17 00:00:00 2001 From: jjgancfer Date: Mon, 29 Apr 2024 22:49:32 +0200 Subject: [PATCH] Updates --- index.html | 434 ++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 313 insertions(+), 121 deletions(-) diff --git a/index.html b/index.html index 9648f67a..8ce995a9 100644 --- a/index.html +++ b/index.html @@ -490,7 +490,19 @@

arc42 K
  • 8. Cross-cutting Concepts
    • -
  • 9. Architecture Decisions
    • +
  • 9. Architecture Decisions + +
  • 10. Quality Requirements
  • 11. Risks and Technical Debts
    • -
  • 12. Glossary
    • -
  • 13. Annex +
  • 12. Testing +
    • +
  • 13. Glossary
    • +
  • 14. Annex +
    • @@ -1495,58 +1514,162 @@

    9. Architecture Decisions

    During the application development process, decisions had to be made as issues emerged. The most interesting design decisions are reflected in this architectural records:

    - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    DecisionExplanation

    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.

    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.

    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.

    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.

    HTTPS

    To improve security we have decided to make HTTPS as one main requirements in out project as can be seen in issue #51.

    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.

    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.

    +
    +

    9.1. Main webapp technology

    +
    +

    Date Recorded: 01/02/2024

    +
    +
    +

    Scope: frontend, webapp

    +
    +
    +

    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.

    +
    +
    +

    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.

    +
    +
    +
    +

    9.2. React technology to be used

    +
    +

    Date Recorded: 01/02/2024

    +
    +
    +

    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.

    +
    +
    +
    +

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

    +
    +
    +
    +

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

    +
    +
    +
    +

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

    +
    +
    +
    +

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

    +
    +
    +
    +

    9.7. Architecture of the question generator process

    +
    +

    Date Recorded: 03/03/2024

    +
    +
    +

    Scope: backend, question generator

    +
    -

    If needed, more details are given in the wiki.

    +

    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.

    +
    +
    +
    +

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

    +
    +
    +
    +

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

    +

    10. Quality Requirements

    @@ -1604,7 +1727,7 @@

    10.2.1. Usage Scenarios

    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.

    +

    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

    @@ -1617,16 +1740,6 @@

    10.2.1. Usage Scenarios

    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

    -
    @@ -1656,58 +1769,22 @@

    10.2.2. Change Scenarios

    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

    +

    10.2.3. Implementation

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

    -
    -
    -
    -Gatling 1 user -
    -
    Figure 19. Gatling results with 1 user
    -
    -
    -

    100 users:

    -
    -
    -
    -Gatling 100 users -
    -
    Figure 20. Gatling results with 100 user
    -
    -
    -

    1000 users:

    -
    -
    -
    -Gatling 1000 users -
    -
    Figure 21. Gatling results with 1000 user
    -
    -
    -

    10000 users:

    -
    -
    -
    -Gatling 10000 users -
    -
    Figure 22. Gatling results with 10000 user
    -
    -
    -
    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.

    @@ -1721,7 +1798,31 @@
    Security
    Testability
    - +
    +

    Many different tests were done to this project as they were considered as a critical requirement for the development.

    +
    +
    +
      +
    • +

      Unit tests: The strongest constraint, as an 80% code coverage is mandatory to ensure code works properly.

      +
      • +
    • +

      Load tests: They show how the system will behave under expected workloads.

      +
      • +
    • +

      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.

      +
      • +
    • +

      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.

      +
      • +
    • +

      Usability tests: They aim for the idea of knowing how easy the product is to learn and to use.

      +
      • +
    +
    +
    +

    More information about testing can be seen in Section 12.

    +
    Monitoring
    @@ -1735,7 +1836,7 @@
    Monitoring
    actuator
    -
    Figure 23. Spring Boot Actuator
    +
    Figure 19. Spring Boot Actuator

    The Prometheus server is deployed in http://20.199.84.5:9090.

    @@ -1744,7 +1845,7 @@
    Monitoring
    prometheus
    -
    Figure 24. Prometheus
    +
    Figure 20. Prometheus

    The Grafana is deployed in http://20.199.84.5:9091. The Grafana dashboard is available at the following link with user asw@uniovi.es and password aswgrafana.

    @@ -1757,7 +1858,7 @@
    Monitoring
    grafana
    -
    Figure 25. Graphana Spring Boot dashboard
    +
    Figure 21. Graphana Spring Boot dashboard
    @@ -1769,7 +1870,7 @@
    Maintainability
    codescene general
    -
    Figure 26. CodeScene general view
    +
    Figure 22. CodeScene general view
    @@ -1873,7 +1974,98 @@

    11. Risks and Technical Debts

    -

    12. Glossary

    +

    12. Testing

    +
    +
    +

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

    +
    +
    +
    +Gatling 1 user +
    +
    Figure 23. Gatling results with 1 user
    +
    +
    +

    100 users:

    +
    +
    +
    +Gatling 100 users +
    +
    Figure 24. Gatling results with 100 user
    +
    +
    +

    1000 users:

    +
    +
    +
    +Gatling 1000 users +
    +
    Figure 25. 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.

    +
    +
    +
    +Gatling 10000 users +
    +
    Figure 26. Gatling results with 10000 user
    +
    +
    +
    +

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

    +
    +
    +
    +

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

    +
    +
    +
    +
    +
    +
    +

    13. Glossary

    @@ -1905,12 +2097,12 @@

    12. Glossary

    -

    13. Annex

    +

    14. Annex

    -

    13.1. Functional Requirements

    +

    14.1. Functional Requirements

    -

    13.1.1. Users Sign up.

    +

    14.1.1. Users Sign up.

    • @@ -1966,7 +2158,7 @@

      13.1.1. Users Sign up.

    -

    13.1.2. Users Log in.

    +

    14.1.2. Users Log in.

    • @@ -2022,7 +2214,7 @@

      13.1.2. Users Log in.

    -

    13.1.3. Data management by the user.

    +

    14.1.3. Data management by the user.

    • @@ -2048,7 +2240,7 @@

      13.1.3. Data management by the user.

    -

    13.1.4. Play to WIQ.

    +

    14.1.4. Play to WIQ.

    • @@ -2169,7 +2361,7 @@

      13.1.4. Play to WIQ.