Merge pull request #227 from Arquisoft/documentation-fixes

Documentation fixes

docs/index.adoc

@@ -7,8 +7,8 @@
 include::src/config.adoc[]
 
 = image:wiq-logo.png[wiq-image] WIQ es04b
-:revnumber: 2
-:revdate: March 2024
+:revnumber: 3
+:revdate: April 2024
 :revremark: ASW - wiq_es04b
 // toc-title definition MUST follow document title without blank line!
 :toc-title: Table of Contents

docs/src/03_system_scope_and_context.adoc

@@ -9,61 +9,116 @@ ifndef::imagesdir[:imagesdir: ../images]
 @startuml
 actor Player as user
 actor "External Developers" as developers
-component System [
+component WebApp [
   <<System>>
-  QuestionGame
+  Web game
 ]
-component WikiData as wikidata
 
-user -down-> System : Uses
-System -left-> wikidata : Retrieves\nInformation to\nform questions\nand answers
-developers -down-> System : Asks for Player\n& Question Data
-System -----> developers : Provides\nPlayer &\n Question Data
+component PlayerService [
+  <<System>>
+  Player Management
+]
+
+component QuestionService [
+  <<System>>
+  Question Management
+]
+
+component WikiData [
+    <<extern>>
+    Wikidata
+]
+
+user ...> WebApp: Plays
+WebApp ---> PlayerService : Handles\nlogin and signup
+WebApp -left-> QuestionService : Retrieves generated\nquestions for game
+WebApp <-- WikiData : Retrieves\nInformation to\nform questions\nand answers
+developers .right.> PlayerService : Modify\nplayer data
+developers <.right. PlayerService : Retrieve\nplayer data
+developers .right.> QuestionService : Modify questions
+developers <.right. QuestionService : Retrieve question list
 @enduml
 
 ----
 * **Player:** Represents users who interact with the application to play games or view their history.
-* **System (QuestionGame):** The main system that hosts the game logic and manages user interactions.
+* **Question management:** The sytem that retrieves the questions generated from Wikidata.
+* **Player management:** The system that manages player data, such as registration, login, and game history.
 * **WikiData:** Component used to retrieve data from Wikidata and automatically generate questions.
-* **Database:** Stores system information, such as user data, generated questions, game history, etc.
-* **External Developers:** Represents developers who access the system's REST API to retrieve player and question data.
+* **External Developers:** Represents developers who access the system to retrieve player and question data.
 
 === Technical Context
 
 [plantuml,"Technical Context Diagram",png]
 ----
-  actor user
-  person developer
-  database Database
-  cloud WikiData
-
-
-  node "User Agent"
-  
-  node "QuestionGame server"
-  
-  user --> [User Agent]
-  [User Agent] --> [QuestionGame server]: HTTPS
-
-  [QuestionGame server] --> Database: Specific driver
-  [QuestionGame server] --> WikiData: HTTP
-  developer --> [QuestionGame server] : HTTPS
+actor Player as user
+actor "External Developers" as developers
+component WebApp [
+  <<System>>
+  Web game
+]
+
+component PlayerService [
+  <<System>>
+  PlayerService
+]
+
+component QuestionService [
+  <<System>>
+  QuestionService
+]
+
+component WikiData [
+    <<extern>>
+    Wikidata
+]
+
+component QuestionGenerator [
+    <<system>>
+    QuestionGenerator
+]
+
+component RestApiService [
+    <<system>>
+    RestApiService
+]
+
+database Database [
+    Database
+]
+
+user .left.> WebApp: HTTPS
+WebApp ---> PlayerService : Handles\nlogin, signup\nand game history
+WebApp -left-> QuestionService : Retrieves generated\nquestions for game
+QuestionGenerator <-up- WikiData : Get entity info\nfrom SPARQL HTTP
+QuestionGenerator --> QuestionService : Generate questions\nwith entity data
+QuestionService --> Database: Save\nquestion\nentities
+QuestionService <-- Database: Retrieve\nsaved\nquestions
+developers .up---.> RestApiService : HTTP\nPOST\nPUT\nDELETE
+developers <.up. RestApiService : HTTP GET
+RestApiService -up-> QuestionService: Retrieve/Modify questions
+RestApiService ---> PlayerService: Retrieve/Modify player data
+
 ----
 
-* **User Agent:** Represents the web or mobile interface used by users.
-* **QuestionGame server:** The server-side components, including the Frontend, QuestionGame logic, User's API, and Question's API.
-* **HTTPS:** Represents the communication channels, with HTTPS being the protocol used for secure communication.
-* **Question Generation:** Represents the means used for question and answers generation.
-* **Database:** Represents whichever system used for data persistence.
+* **Player:** Represents users who interact with the application to play games or view their history.
+* **Question service:** The system that retrieves the questions generated from Wikidata.
+* **Player service:** The system that manages player data, such as registration, login, and game history.
+* **WikiData:** Component used to retrieve data from Wikidata
+* **Question generator:** The system that generates questions based on the data retrieved from Wikidata.
+* **External Developers:** Represents developers who access the system to retrieve player and question data.
+* **Database:** The database that stores player data, game history, and questions.
+* **Rest API Service:** The service that provides an API for external developers to access player and question data.
 
 ==== Input/Output Mapping Table
 
 [options="header",cols="1,2,2"]
 |===
 |Component|Input/Output|Channel/Protocol
-| User's API| User registration, game history| HTTPS
-| Question's API| Question data retrieval| HTTPS
+| RestApiService| External developer interactions| HTTPS
 | Frontend| User interactions, game display| HTTPS
 | Database| User data, game history, questions| Specific database driver
 | WikiData| Data for question generation| HTTP
+| Question Generator| Generated questions| In-memory
+| Question Service| Questions for game| In-memory
+| Player Service| Player data| In-memory
 |===

docs/src/05_building_block_view.adoc

@@ -8,7 +8,7 @@ The Building Block View elaborates on the static structure of the system. It dec
 
 === Whitebox Overall System
 
-This section provides an overview of the main components of the system and their interactions. The core of the system is the WIQ (QuestionGame) component, which interfaces with Users, Wikidata for question generation, a Database for persistence, and offers a REST API for External Developers.
+This section provides an overview of the main components of the system and their interactions. The core of the system is the WIQ (WiqEs04bApplication) component, which interfaces with Users, Wikidata for question generation, a Database for persistence, and offers a REST API for External Developers.
 
 [plantuml,"Whitebox-overall",png]
 ----
@@ -17,19 +17,16 @@ This section provides an overview of the main components of the system and their
 
 actor User
 actor "External Developers" as Dev
-component "[WIQ QuestionGame]" as WIQ {
-  component "[GameSession\nService]" as Logic
-  component "[PlayerService]" as UserMgmt
-  component "[QuestionService]" as QuestMgmt
-  component "[RestApi\nService]" as APIMgmt
+component "com.uniovi.WiqEs04bApplication" as WIQ {
+
 }
 database "Database" as DB
 [WikiData] as WikiData
 
 User --> WIQ : Interacts
 WIQ --> WikiData : Fetches data
 WIQ --> DB : Reads/Writes Data
-Dev --> APIMgmt : Uses APIs
+Dev --> WIQ : Uses APIs
 
 @enduml
 ----
@@ -47,7 +44,7 @@ The decomposition provides a clear, high-level overview of how the WIQ system in
 | User
 | Represents the end users of the WIQ application, interacting with the system to play games and view their history.
 
-| WIQ (QuestionGame)
+| WIQ (WiqEs04bApplication)
 | The central component that manages gameplay logic, user interactions, and integrates external data for question generation.
 
 | Wikidata
@@ -78,23 +75,29 @@ For Level 2 of the Building Block View, the WIQ (QuestionGame) system is further
 @startuml
 !theme plain
 
-package "WIQ QuestionGame" {
-  component "[GameSession\nService]" as Logic
-  component "[PlayerService]" as UserMgmt
-  component "[QuestionService]" as QuestMgmt
-  component "[RestApi\nService]" as APIMgmt
-
-  UserMgmt -[hidden]-> Logic : <<uses>>
-  QuestMgmt -[hidden]-> Logic : <<uses>>
-  APIMgmt -[hidden]-> UserMgmt : <<interfaces>>
-  APIMgmt -[hidden]-> QuestMgmt : <<interfaces>>
-
-  Logic ..> UserMgmt : Uses
-  Logic ..> QuestMgmt : Uses
-  UserMgmt ..> APIMgmt : Interfaces
-  QuestMgmt ..> APIMgmt : Interfaces
+actor User
+actor "External Developers" as Dev
+component "com.uniovi.WiqEs04bApplication" {
+    package "com.uniovi.services" {
+      component "[GameSession\nService]" as Logic
+      component "[PlayerService]" as UserMgmt
+      component "[QuestionService]" as QuestMgmt
+      component "[RestApi\nService]" as APIMgmt
+
+      UserMgmt -[hidden]-> Logic : <<uses>>
+      QuestMgmt -[hidden]-> Logic : <<uses>>
+      APIMgmt -[hidden]-> UserMgmt : <<interfaces>>
+      APIMgmt -[hidden]-> QuestMgmt : <<interfaces>>
+
+      Logic ..> UserMgmt : Uses
+      Logic ..> QuestMgmt : Uses
+      UserMgmt ..> APIMgmt : Interfaces
+      QuestMgmt ..> APIMgmt : Interfaces
+    }
 }
 
+User --> [com.uniovi.WiqEs04bApplication] : Interacts
+Dev --> APIMgmt : Uses APIs
 @enduml
 ----
 
@@ -113,7 +116,7 @@ This level of documentation provides a structured and clear view of the system's
 @startuml
 !theme plain
 
-package "API Management" {
+package "com.uniovi.services.RestApiService" {
   interface "Player Information API" as PlayerAPI
   interface "Question Information API" as QuestAPI
 

docs/src/07_deployment_view.adoc

@@ -22,6 +22,8 @@ The primary motivation behind using Docker for deployment is to streamline the d
 .Mapping of Building Blocks to Infrastructure
 - **Web Server/Application (.jar file):** Packaged within a Docker container, it includes all necessary dependencies to run independently across any Docker-supported platform.
 - **External APIs (e.g., Wikidata API):** Accessed over the network, these APIs provide dynamic content for the game.
+- **Grafana**: Monitoring tool that can be used to visualize and analyze metrics from the application and infrastructure.
+- **Prometheus**: Monitoring tool that collects metrics from the application and infrastructure for Grafana to visualize.
 
 === Infrastructure Level 2
 
@@ -33,6 +35,8 @@ Our app's Docker container is built from a Java base image, which is then layere
 
 In addition to the Spring boot standalone file, we also use the official `MySQL` server docker container image brought by DockerHub. This is our database server and it is used to store the game data, such as user scores, questions, etc. and all the other persistent data.
 
+Moreover, there are two more containers. These are the monitoring tools, `Prometheus` and `Grafana`. These tools are used to monitor the application and infrastructure. Prometheus collects metrics from the application and infrastructure, while Grafana visualizes these metrics.
+
 This setup encapsulates the entire runtime environment required for our application, and does not require extensive configuration.
 
 .Diagram: Docker Container Setup
@@ -48,16 +52,28 @@ rectangle "Docker compose" {
     rectangle "MySQL Server Container" {
         database "MySQL Server" as MySQL
     }
+
+    rectangle "Prometheus Container" {
+        database "Prometheus" as Prometheus
+    }
+
+    rectangle "Grafana Container" {
+        node "Grafana" as Grafana
+    }
 }
 
 cloud "Wikidata API" as API
 
 App --> MySQL : Store game data
 MySQL --> App : Fetch game data
-App --> API : Fetch questions
+App -left-> API : Fetch questions
 App ..> WebServer : Server application
+Prometheus --> App : Collect metrics
+Grafana --> Prometheus : Visualize metrics
 @enduml
 ----
 
 .Explanation:
-This diagram illustrates the internal structure of our Docker containers structure. It shows the Java Spring Boot application, including the embedded web server, packaged as a `.jar` file and the MySQL server. The application interacts with external APIs, like the Wikidata API, to retrieve data necessary for generating game questions. The containerized approach ensures that the application can be deployed consistently across any environment that supports Docker.
+This diagram illustrates the internal structure of our Docker containers structure. It shows the Java Spring Boot application, including the embedded web server, packaged as a `.jar` file and the MySQL server. The application interacts with external APIs, like the Wikidata API, to retrieve data necessary for generating game questions.
+To ensure the application's health and performance, we use Prometheus to collect metrics and Grafana to visualize these metrics.
+The containerized approach ensures that the application can be deployed consistently across any environment that supports Docker.

docs/src/08_concepts.adoc

@@ -172,5 +172,7 @@ Our CI/CD pipeline automates the process of integrating code changes, building t
 === Scalability
 
 Designing for scalability, the application can accommodate an increasing number of users and interactions without performance degradation.
+
 .Explanation:
-Scalable solutions such as Docker containers allow the application to be deployed in a distributed environment, where resources can be adjusted based on demand.
+Scalable solutions such as Docker containers allow the application to be deployed in a distributed environment, where resources can be adjusted based on demand.
+Given that we use a monolithic approach, the application can be easily scaled horizontally by deploying multiple instances of the same service and connect them to a load balancer in order to distribute the load.

docs/src/10_quality_requirements.adoc

@@ -67,7 +67,7 @@ ifndef::imagesdir[:imagesdir: ../images]
 | The testing process is streamlined, allowing QA teams to efficiently create, execute, and analyze test cases, ensuring the reliability and stability of the application.
 
 | SC7
-| As user demand grows, the application scales its resources dynamically to accommodate increased traffic and maintain optimal performance levels, ensuring a consistent user experience.
+| As user demand grows, the deployment does not grow dynamically. However a system can be put in place to deploy more instances of the application to handle the increased workload, trough a load balancer, for example.
 
 | SC8
 | The application seamlessly integrates with other systems, allowing for the exchange of data and functionality without compatibility issues, enhancing its overall interoperability.

docs/src/11_technical_risks.adoc

@@ -6,15 +6,21 @@ ifndef::imagesdir[:imagesdir: ../images]
 |===
 | Priority | Risk | Description
 
-| High | Migration to Java | Migration from the current project language, JavaScript (JS), to Java
+| High | Architecture in Spring Boot | The architecture of the project will be based on Spring Boot, which is a framework that we are not that familiar with, or not at all for some members. This could lead to a delay in the development of the project.
+| Medium | Wikidata | The project will use Wikidata as a source of data. We have never used Wikidata before, so we will have to learn how to use it.
 | Medium | IDE Configuration | Version compatibility, extensions and other preferences to work perfectly without conflicts
-| Medium | Database | Discuss which database is best for the project 
-| Low | Docker  | Know how docker works, what it is for, how it is used and what its alternatives could be.
+| Medium | Docker  | Know how docker works, what it is for, how it is used and what its alternatives could be.
+| Low | Database | The database decision will not be taken based on what technology we know better, but on what is best for the project. Usage of JPA, Hibernate allows us to focus on the business logic and not on the database.
 
 
 |===
 
 [cols="1,2,3a", options="header"]
 |===
 | Priority | Debt | Description
+
+| Medium | Documentation | The documentation of the project will be done in parallel with the development of the project. This could lead to a delay in the development of the project.
+| Medium | Testing | The project will have unit and integration tests, we ensure tests cover the majority of the code. However due to time constraints and how the project is structured, we may not be able to cover all the code with all the possible cases. The aim is to cover at least 80% of the code.
+| Low | Code Quality | The code quality will be ensured by the use of SonarCloud, but due to time constraints, we may not be able to fix all the issues that SonarCloud will find.
+| Low | Security | The project will have security measures in place. Standard practices are put in place. Tougher security measures will not be implemented due to performance constraints.
 |===

docs/src/12_glossary.adoc

@@ -24,4 +24,6 @@ ifndef::imagesdir[:imagesdir: ../images]
 
 |Associations  | Represents the associations between entities. It has internal classes for each association.
 
+|MultiplayerSession | Represents a multiplayer session, which is a game session with more than one player.
+
 |===