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

first 4 parts updated

docs/diagrams/BusinessContextDiagram.puml → docs/diagrams/c4/C4-Level1.puml

@@ -2,22 +2,20 @@
 !includeurl https://raw.githubusercontent.com/RicardoNiepel/C4-PlantUML/master/C4_Container.puml
 !include <c4/C4_Context.puml>
 
-title Context Diagram for the WIQ System
+title Context Diagram for the Kiwiq System (C4 Level 1)
 AddElementTag("Person", $bgColor="#salmon", $fontColor="#white")
 AddElementTag("Internal system", $bgColor="#peachpuff", $fontColor="#963b17")
 AddElementTag("External system", $bgColor="#darksalmon", $fontColor="#white")
 
 'Containers
-Person(player, Player,"An authenticated player that wants to play WIQ games", $tags="Person")
+Person(player, Player,"An authenticated player that wants to play Kiwiq games", $tags="Person")
 
-Container(wiq, "WIQ Application","", "Application that allows the users to play WIQ games", $tags="Internal system")
+Container(kiwiq, "Kiwiq System","", "System that allows the users to play Kiwiq games", $tags="Internal system")
 
-Container(question_generator, "Question Generator Module","", "Organizes everything related with questions", $tags="Internal system")
 
 System_Ext(wikidata,"WikiData API","Contains the information used for the question generation", $tags="External system")
 
 'RELATIONS
-Rel(player,wiq,"Plays games")
-Rel(wiq, question_generator, "Asks for questions and answers")
-Rel(question_generator,wikidata,"Asks for data for question generation")
+Rel(player,kiwiq,"Plays games")
+Rel(kiwiq,wikidata,"Asks for data for question generation")
 @enduml

docs/diagrams/c4/C4-Level2.puml

@@ -0,0 +1,31 @@
+@startuml
+!includeurl https://raw.githubusercontent.com/RicardoNiepel/C4-PlantUML/master/C4_Container.puml
+!include <c4/C4_Context.puml>
+
+title Container Diagram for the Kiwiq System (C4 Level 2)
+AddElementTag("Person", $bgColor="#salmon", $fontColor="#white")
+AddElementTag("Internal system", $bgColor="#peachpuff", $fontColor="#963b17")
+AddElementTag("External system", $bgColor="#gray", $fontColor="#white")
+AddElementTag("Database", $bgColor="#darksalmon", $fontColor="#white")
+'Containers
+Person(player, Player's Browser,"Preferred browser (Firefox, Chrome, Opera...)")
+
+System_Boundary(wiq,"Kiwiq Server"){
+    Container(proxy,"Proxy","Nginx","Nginx web server", $tags="Internal system")
+    Container(web_app, "Kiwiq Client", "React, Typescript", "nginx web server", $tags="Internal system")
+    Container(backend_api, "Kiwiq REST API","Java SpringBoot 3",".jar file", $tags="Internal system")
+    Container(question_generator,"Question generator","Java, JPA",".jar file",$tags="Internal system")
+    ContainerDb(database,"Kiwiq Database","PostgreSQL","PostgreSQL docker container", $tags="Database")
+}
+System_Ext(wikidata,"WikiData API","REST API", $tags="External system")
+
+'RELATIONS
+Rel(player,proxy,"Uses","HTTPS")
+Rel(proxy,web_app,"Serves","HTTPS")
+Rel(question_generator,wikidata,"Asks for data","SPARQL,HTTPS")
+Rel(web_app,backend_api,"Asks for user/game information","JSON,HTTPS")
+Rel(question_generator, database,"Stores questions ","JPA")
+Rel(backend_api,database,"Stores game/user information","JPA")
+
+
+@enduml

docs/src/01_introduction_and_goals.adoc

@@ -2,19 +2,18 @@ ifndef::imagesdir[:imagesdir: ../images]
 
 [[section-introduction-and-goals]]
 == Introduction and Goals
-RTVE has hired the company HappySw, composed of students from the Oviedo School of Software Engineering, to develop a new experimental version of the quiz show Saber y Ganar. This application will be called KiWiq, where users will be able to register and log in to play. The application will consist of answering questions of different types generated with Wikidata. For each question answered correctly, points will be obtained.
+RTVE has hired the company HappySw, composed of students from the Oviedo School of Software Engineering, to develop a new game-show like web application. This application will be called KiWiq, where users will be able to register and log in to play. The application will consist of answering questions of different types generated with Wikidata. Questions answered correctly will count towards statistics that are displayed in a ranking.
 
 === Requirements Overview
 * The system shall provide non-registered users with the option to sign up.
 * The system shall provide unidentified users with the option to log in.
 * The system shall only be used by registered users.
-* The system shall have a game mode with 9 rounds.
-* In each round, the system shall generate a question.
-* In each round, the system shall generate four answers, with only one being correct.
+* The system shall have a game mode with a 9 rounds.
+* In each round, the system shall fetch and display a question.
+* In each round, the system shall display four answers, with only one being correct.
 * The system shall offer registered users access to the number of games they have played.
 * The system shall offer registered users access the number of questions they have answered correctly.
 * The system shall offer registered users access the number of questions they have answered incorrectly.
-* The system shall offer registered users access the time they have spent within the system.
 * The system shall offer registered users access the ranking of the game.
 * The system shall set a time limit for registered users to respond to each question.
 
@@ -39,7 +38,7 @@ See the complete functional requirements in the xref:#section-annex[Annex] of th
 [options="header",cols="1,2"]
 |===
 |Role/Name|Expectations
-| RTVE  | To have a new experimental version of the Saber y Ganar quiz show.
+| RTVE  | To have a new application for a quiz game.
 | HappySw | Develop a good application that fulfills the requirements expected by the client.
 | Registered user | To play with an entertaining and easy-to-use application. An application with which the user learn about different topics.
 | Wikidata | Being able to offer service allowing people to use the data through the API.

docs/src/02_architecture_constraints.adoc

@@ -3,7 +3,7 @@ ifndef::imagesdir[:imagesdir: ../images]
 [[section-architecture-constraints]]
 == Architecture Constraints
 
-The application must be developed according to some constraints that were defined by the professors. These constraints are meant to be the cornerstones of our project as they are mandatory and provide a baseline to work on. The following tables will define the constraints.
+The application must be developed according to some constraints that were defined by the client. These constraints are meant to be the cornerstones of our project as they are mandatory and provide a baseline to work on. The following tables will define the constraints.
 
 
 *Technical constraints*

docs/src/03_system_scope_and_context.adoc

@@ -3,16 +3,33 @@ ifndef::imagesdir[:imagesdir: ../images]
 == System Scope and Context
 === Business Context
 
-[plantuml,"Business context diagram",png, align="center", title="Overall view of the business context"]
+[plantuml,"C4 Level 1 - Business context diagram",png, align="center", title="Overall view of the business context"]
 ----
-include::../diagrams/BusinessContextDiagram.puml[]
+include::../diagrams/c4/C4-Level1.puml[]
 ----
-
-The WIQ application will communicate with the WikiData API through REST HTTP calls using SPARQL for the queries. It will ask the API for information that will later be used for generating the questions that will be shown to the player. This information will come in the form of text, images or audio.
+The player interacts with the Kiwiq system, which will communicate with the WikiData API through REST HTTP calls using SPARQL for the queries. It will ask the API for information that will later be used for generating the questions that will be shown to the player. This information will come in the form of text or images.
 
 === Technical Context
-image::TechnicalContextDiagram.png[align="center",title="Technical Context",link="TechnicalContextDiagram.png]
 
-The WIQ application will be deployed together in the same server. The WIQ client will be deployed on a nginx web server. This client will communicate with the API through HTTPS REST calls and exchange information through JSON objects. The WIQ REST API will be run as a .jar file on the server and connect to a Database run on a postgresql docker container. The connection layer between the SpringBoot API and the database will be JPA.
-The REST API will request information to the WikiData REST API through HTTPS calls passing a SPARQL query in order to retrieve data.
+[plantuml,"C4 Level 2 - Container context diagram",png, align="center", title="Overall view of the technical context"]
+----
+include::../diagrams/c4/C4-Level2.puml[]
+----
+The Kiwiq system will be deployed together in the same server and contains different modules:
+
+* **Kiwiq Proxy: **
+When interacting with the server, an nginx proxy will be tasked with redirecting the queries to the petitions to the Kiwiq client will also be deployed on a nginx web server.
+
+* **Kiwiq Client: **
+This client will be served to the client and communicates with the API through HTTPS REST calls and exchanges information through JSON objects.
+
+* **Kiwiq REST API:**
+The Kiwiq REST API will be run as a .jar file on the server and connect to a database running on a PostgreSQL docker container. The connection layer between the SpringBoot API and the database will be JPA.
+
+* **Kiwiq database:**
+In the database the questions and answers generated by the Question Generator module will be stored, written in Java and using JPA as a connection layer.
+
+* **Question generator:**
+The Question Generator will also use the WikiData REST API to retrieve information to generate questions. It  will generate the questions by connecting to the Wikidata REST API through HTTPs calls and passing a SPARQL query to retrieve the data that will later be used in the question generation.
+
 

docs/src/04_solution_strategy.adoc

@@ -13,7 +13,7 @@ Regarding the technologies, we decided to use the following ones:
 
  ** As a consecuence of this, pure JavaScript is being used due to React 18 not supporting Typescript 5.
 
- * **PostgreSQL** as DBMS to store the information. We nearly immediately discarded using MongoDB due to many of us not having experience with it, and those who did, preferred SQL. Many modern DBMS also include either JSON or JSONB data types, so using a DBMS whose main appeal is JSON and not many of us have experience with did not sit well with us.
+ * **PostgreSQL** as DBMS to store the information. We nearly immediately discarded using MongoDB due to many of us not having experience with it, and those who did, preferred relational databases. Many modern DBMS also include either JSON or JSONB data types, so using a DBMS whose main appeal is JSON and not many of us have experience with did not sit well with us.
 
  * **Java SpringBoot 3** for the backend/API, it being a language we are all comfortable with. The server will easily support multithreading if needed due to SpringBoot being an abstraction over servlets, something we would be able only to simulate if we used Node.js as it uses a single-threaded event loop.
 
@@ -31,21 +31,65 @@ We also have a Whatsapp community for the team, and a Notion wiki.
 |===
 |Quality attribute pursued|Solution chosen
 |Privacy|All stored password will be hashed, both client-side and server-side, to avoid password disclosure. The client-side password is also intended to prevent password discoverage in case it is a repeated one.
-|Robustness|Currently, all validations will take place server-side to avoid not being properly taken care of due to JavaScript desactivation, such as when using the NoScript plug-in
-|Availability|Since Wikidata has a 1 minute limit related to the API, the backend will start querying it upon start and fill the database with questions to increase speed and thus improve user experience|
+|Robustness|Currently, all validations will take place server-side to avoid not being properly taken care of due to JavaScript desactivation, such as when using the NoScript plug-in or sending a request via cURL.
+|Availability|Since Wikidata has a 1-minute limit related to the API, the backend will start querying it upon start and fill the database with questions to increase speed and thus improve user experience. This makes it so we are not dependent on the Wikidata API to be up for our system to work|
 |===
 
 === Workflow
 
+==== Team Workflow:
 We have divided ourselves in teams related to our own areas of expertise, but those divisions are indicative, and frontend teams may review or comment PRs if they wish, or vice versa. The frontend team may also ask input from the backend team if they wish, and the backend team may do the same.
 
-All in all, we strive to achieve a very flexible workflow in which everyone's input may be considered if they wish to give it.
+Separation of the group into teams though, tends to reflect on the final structure of the project, as stated in Conway's law. To prevent this, we employed the use of API definition tools such as Swagger to make the integration of frontend and backend not dependent on having members of both teams present. Conway's law still affected in other aspects, though.
 
-=== Code Style
+Meetings are also organized each week so as to keep the team updated, decide what should be worked on next and discuss any problems that may arise from implementation.
 
-Regarding the code style, we must make two important distinctions: the frontend and backend. In the latter, we will mainly use Object Oriented Programming because our language of choice is Java, which strongly favours it. Regarding the former, it will be more of a case-by-case approach, as for instance, OOP-oriented React is deprecated in favor of a functional approach, but sometimes we may need OOP's strengths.
+==== Coding workflow:
+Pair programming was implemented in the backend team, which helped immensely to shorten the existing knowledge gaps and achieve a consistent coding style. This also reduced the number of PRs that needed to be validated, since having 2 people write the code increases its reliability.
 
- * In the backend, the structure will be that of a typical Maven project.
+==== Git workflow:
+Trunk Based Development was used as source-control branching model, using develop as our trunk branch, and merging into master for tested releases.
+
+For commit messages we used the specification on https://www.conventionalcommits.org/en/v1.0.0/ so as to keep them consistent.
+
+For branch naming we used a variation of Conventional Commits commit naming, naming branches with its purpose first (docs,feat,fix...).
+
+Pull Requests were the main method of contributing to the project, these needing to be validated by at least 2 other teammates before merging to ensure code quality.
+
+=== Code Style/Structure
+
+Regarding the code style, we must make two important distinctions: the frontend and backend. In the latter, we will mainly use Object-Oriented Programming because our language of choice is Java, which strongly favours it. Regarding the former, it will be more of a case-by-case approach, as for instance, OOP-oriented React is deprecated in favor of a functional approach, but sometimes we may need OOP's strengths.
+
+==== Backend
+===== API
+In the backend, the structure will be that of a typical Maven project, using different packages for different modules of the project:
+
+ * The `auth` package is used for *authentication* related endpoints and configuration.
+ * The `game` package is used for *game* related endpoints and logic
+ * The `questions` package is used for *question* related endpoints and logic
+ * The `statistics` package is used for *statistics* related endpoints and logic
+ * The `commons` package is used for common logic that may be used among different packages, such as *utils* classes or *user* logic.
+
+In each of this packages, the following structure is followed:
+
+ * The `dtos` package stores *Data Transfer Objects*, used for sending or receiving data
+ * The `mappers` package stores classes used for mapping from *models* to *DTOs* or vice versa.
+
+In our Spring Boot project the following structure is found in each of our modules, following a Domain Driven Design approach:
+
+ * A `Controller` handles the requests done to our API.
+ * A `Service` handles the retrieval of the *Models* from the database using *Repositories*.
+ * A `Model` is retrieved and handles its domain logic.
+ * A `Repository` is used for retrieving *Models* from the database.
+
+A crucial part of the design is that the models are the ones handling the logic, as described in Jimmy Bogard's talk: https://www.youtube.com/watch?v=UYmTUw5LXwQ
+
+In regard to testing, a Test First approach was employed when possible, and the logic of the *Models* and the *Services* was tested, as well as the responses given by the *Controllers* in different situations.
+
+===== Question Generator
+ //fill in here pls
+
+==== Frontend
  * In the frontend, the structure will be quite different:
  ** The `src/components` will contain single components which we may reuse.
  ** The `src/pages` will contain the endpoints and will follow a simple structure. For instance, given a `/statistics/personal` and a `/statistics/general` endpoints, both will be independent React components that will return the page and be placed under the `src/pages/statistics` folder.