From f0bd5b60d7ee8320225f358b275a94742bfb98d2 Mon Sep 17 00:00:00 2001 From: "Dario G. Mori" Date: Fri, 26 Apr 2024 19:41:38 +0200 Subject: [PATCH 01/12] docs: functional requirements --- docs/src/01_introduction_and_goals.adoc | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/src/01_introduction_and_goals.adoc b/docs/src/01_introduction_and_goals.adoc index d3a42dfb..41277211 100644 --- a/docs/src/01_introduction_and_goals.adoc +++ b/docs/src/01_introduction_and_goals.adoc @@ -8,13 +8,12 @@ RTVE has hired the company HappySw, composed of students from the Oviedo School * 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. From 0825672805aace8ff8d45a3b8a6418a291872c36 Mon Sep 17 00:00:00 2001 From: "Dario G. Mori" Date: Fri, 26 Apr 2024 19:55:39 +0200 Subject: [PATCH 02/12] docs: doc 1 --- docs/src/01_introduction_and_goals.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/01_introduction_and_goals.adoc b/docs/src/01_introduction_and_goals.adoc index 41277211..e39519b7 100644 --- a/docs/src/01_introduction_and_goals.adoc +++ b/docs/src/01_introduction_and_goals.adoc @@ -38,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. From 9e621627dd70f349214ac523f115d216ea636707 Mon Sep 17 00:00:00 2001 From: "Dario G. Mori" Date: Fri, 26 Apr 2024 20:23:33 +0200 Subject: [PATCH 03/12] docs: updated c4 diagrams --- docs/diagrams/c4/C4-Level1.puml | 21 ++++++++++++++++ docs/diagrams/c4/C4-Level2.puml | 29 +++++++++++++++++++++++ docs/src/03_system_scope_and_context.adoc | 12 ++++++---- 3 files changed, 58 insertions(+), 4 deletions(-) create mode 100644 docs/diagrams/c4/C4-Level1.puml create mode 100644 docs/diagrams/c4/C4-Level2.puml diff --git a/docs/diagrams/c4/C4-Level1.puml b/docs/diagrams/c4/C4-Level1.puml new file mode 100644 index 00000000..7d1fe379 --- /dev/null +++ b/docs/diagrams/c4/C4-Level1.puml @@ -0,0 +1,21 @@ +@startuml +!includeurl https://raw.githubusercontent.com/RicardoNiepel/C4-PlantUML/master/C4_Container.puml +!include + +title Context Diagram for the WIQ 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 Kiwiq games", $tags="Person") + +Container(kiwiq, "Kiwiq Application","", "Application that allows the users to play Kiwiq games", $tags="Internal system") + + +System_Ext(wikidata,"WikiData API","Contains the information used for the question generation", $tags="External system") + +'RELATIONS +Rel(player,kiwiq,"Plays games") +Rel(kiwiq,wikidata,"Asks for data for question generation") +@enduml \ No newline at end of file diff --git a/docs/diagrams/c4/C4-Level2.puml b/docs/diagrams/c4/C4-Level2.puml new file mode 100644 index 00000000..df4a3d6e --- /dev/null +++ b/docs/diagrams/c4/C4-Level2.puml @@ -0,0 +1,29 @@ +@startuml +!includeurl https://raw.githubusercontent.com/RicardoNiepel/C4-PlantUML/master/C4_Container.puml +!include + +title Container Diagram for the WIQ 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,"WIQ Server"){ + Container(web_app, "WIQ Client", "React, Typescript", "nginx web server", $tags="Internal system") + Container(backend_api, "WIQ REST API","Java SpringBoot 3",".jar file", $tags="Internal system") + Container(question_generator,"Question generator","Java, JPA",".jar file",$tags="Internal system") + ContainerDb(database,"WIQ Database","PostgreSQL","PostgreSQL docker container", $tags="Database") +} +System_Ext(wikidata,"WikiData API","REST API", $tags="External system") + +'RELATIONS +Rel(player,web_app,"Uses","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 \ No newline at end of file diff --git a/docs/src/03_system_scope_and_context.adoc b/docs/src/03_system_scope_and_context.adoc index 36fc857d..b10e0979 100644 --- a/docs/src/03_system_scope_and_context.adoc +++ b/docs/src/03_system_scope_and_context.adoc @@ -3,15 +3,19 @@ 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 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 or images. === Technical Context -image::TechnicalContextDiagram.png[align="center",title="Technical Context",link="TechnicalContextDiagram.png] + +[plantuml,"C4 Level 2 - Container context diagram",png, align="center", title="Overall view of the technical context"] +---- +include::../diagrams/c4/C4-Level2.puml[] +---- 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. From cb9acd23707d0dc7fb5a46aa5844b2336552a9c4 Mon Sep 17 00:00:00 2001 From: "Dario G. Mori" Date: Fri, 26 Apr 2024 20:24:00 +0200 Subject: [PATCH 04/12] docs: removed old diagrams --- docs/diagrams/BusinessContextDiagram.puml | 23 ------------------ docs/diagrams/TechnicalContextDiagram.puml | 27 ---------------------- 2 files changed, 50 deletions(-) delete mode 100644 docs/diagrams/BusinessContextDiagram.puml delete mode 100644 docs/diagrams/TechnicalContextDiagram.puml diff --git a/docs/diagrams/BusinessContextDiagram.puml b/docs/diagrams/BusinessContextDiagram.puml deleted file mode 100644 index 0fdbcad7..00000000 --- a/docs/diagrams/BusinessContextDiagram.puml +++ /dev/null @@ -1,23 +0,0 @@ -@startuml -!includeurl https://raw.githubusercontent.com/RicardoNiepel/C4-PlantUML/master/C4_Container.puml -!include - -title Context Diagram for the WIQ System -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") - -Container(wiq, "WIQ Application","", "Application that allows the users to play WIQ 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") -@enduml \ No newline at end of file diff --git a/docs/diagrams/TechnicalContextDiagram.puml b/docs/diagrams/TechnicalContextDiagram.puml deleted file mode 100644 index 2d2e0f1a..00000000 --- a/docs/diagrams/TechnicalContextDiagram.puml +++ /dev/null @@ -1,27 +0,0 @@ -@startuml -!includeurl https://raw.githubusercontent.com/RicardoNiepel/C4-PlantUML/master/C4_Container.puml -!include - -title Context Diagram for the WIQ System -AddElementTag("Person", $bgColor="#salmon", $fontColor="#white") -AddElementTag("Internal system", $bgColor="#peachpuff", $fontColor="#963b17") -AddElementTag("External system", $bgColor="#darksalmon", $fontColor="#white") - -'Containers -Person(player, Player's Browser,"Preferred browser (Firefox, Chrome, Opera...)") - -System_Boundary(wiq,"WIQ Server"){ - Container(web_app, "WIQ Client", "React, Typescript", "nginx web server", $tags="Internal system") - Container(backend_api, "WIQ REST API","Java SpringBoot 3",".jar file", $tags="Internal system") - ContainerDb(database,"WIQ Database","PostgreSQL","PostgreSQL docker container", $tags="Internal system") -} -System_Ext(wikidata,"WikiData API","REST API", $tags="External system") - -'RELATIONS -Rel(player,web_app,"Uses","HTTPS") -Rel(backend_api,wikidata,"Asks for data","SPARQL,HTTPS") -Rel(web_app,backend_api,"Asks for user/game information","JSON,HTTPS") -Rel(backend_api,database,"Stores game/user information","JPA") - - -@enduml \ No newline at end of file From e2a70db976a9259cccf466c1fe800a445aa6fb43 Mon Sep 17 00:00:00 2001 From: "Dario G. Mori" Date: Fri, 26 Apr 2024 20:24:25 +0200 Subject: [PATCH 05/12] docs: updated doc 2 --- docs/src/02_architecture_constraints.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/02_architecture_constraints.adoc b/docs/src/02_architecture_constraints.adoc index 3b28b338..1fad8854 100644 --- a/docs/src/02_architecture_constraints.adoc +++ b/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* From 9f73f46fb93834e5191d79ab19c90fbb454a0644 Mon Sep 17 00:00:00 2001 From: "Dario G. Mori" Date: Fri, 26 Apr 2024 20:25:59 +0200 Subject: [PATCH 06/12] docs: added proxy --- docs/diagrams/c4/C4-Level2.puml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/diagrams/c4/C4-Level2.puml b/docs/diagrams/c4/C4-Level2.puml index df4a3d6e..223d477f 100644 --- a/docs/diagrams/c4/C4-Level2.puml +++ b/docs/diagrams/c4/C4-Level2.puml @@ -11,6 +11,7 @@ AddElementTag("Database", $bgColor="#darksalmon", $fontColor="#white") Person(player, Player's Browser,"Preferred browser (Firefox, Chrome, Opera...)") System_Boundary(wiq,"WIQ Server"){ + Container(proxy,"Proxy","Nginx","Nginx web server", $tags="Internal system") Container(web_app, "WIQ Client", "React, Typescript", "nginx web server", $tags="Internal system") Container(backend_api, "WIQ REST API","Java SpringBoot 3",".jar file", $tags="Internal system") Container(question_generator,"Question generator","Java, JPA",".jar file",$tags="Internal system") @@ -19,7 +20,8 @@ System_Boundary(wiq,"WIQ Server"){ System_Ext(wikidata,"WikiData API","REST API", $tags="External system") 'RELATIONS -Rel(player,web_app,"Uses","HTTPS") +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") From cfd8d11109eefa87a26444d96a0b0b2c3ced15ed Mon Sep 17 00:00:00 2001 From: Dario Date: Sat, 27 Apr 2024 10:23:22 +0200 Subject: [PATCH 07/12] docs: updated doc 1 --- docs/src/01_introduction_and_goals.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/01_introduction_and_goals.adoc b/docs/src/01_introduction_and_goals.adoc index e39519b7..aa8975c0 100644 --- a/docs/src/01_introduction_and_goals.adoc +++ b/docs/src/01_introduction_and_goals.adoc @@ -2,7 +2,7 @@ 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. From 00b53eb45f316fd5c67173e741b5523bc3bf00c3 Mon Sep 17 00:00:00 2001 From: Dario Date: Sat, 27 Apr 2024 10:51:10 +0200 Subject: [PATCH 08/12] docs: c4 level 1 and 2 --- docs/diagrams/c4/C4-Level1.puml | 4 ++-- docs/diagrams/c4/C4-Level2.puml | 10 +++++----- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/diagrams/c4/C4-Level1.puml b/docs/diagrams/c4/C4-Level1.puml index 7d1fe379..2ff9f8f4 100644 --- a/docs/diagrams/c4/C4-Level1.puml +++ b/docs/diagrams/c4/C4-Level1.puml @@ -2,7 +2,7 @@ !includeurl https://raw.githubusercontent.com/RicardoNiepel/C4-PlantUML/master/C4_Container.puml !include -title Context Diagram for the WIQ System (C4 Level 1) +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") @@ -10,7 +10,7 @@ AddElementTag("External system", $bgColor="#darksalmon", $fontColor="#white") 'Containers Person(player, Player,"An authenticated player that wants to play Kiwiq games", $tags="Person") -Container(kiwiq, "Kiwiq Application","", "Application that allows the users to play Kiwiq games", $tags="Internal system") +Container(kiwiq, "Kiwiq System","", "System that allows the users to play Kiwiq games", $tags="Internal system") System_Ext(wikidata,"WikiData API","Contains the information used for the question generation", $tags="External system") diff --git a/docs/diagrams/c4/C4-Level2.puml b/docs/diagrams/c4/C4-Level2.puml index 223d477f..11f045f1 100644 --- a/docs/diagrams/c4/C4-Level2.puml +++ b/docs/diagrams/c4/C4-Level2.puml @@ -2,7 +2,7 @@ !includeurl https://raw.githubusercontent.com/RicardoNiepel/C4-PlantUML/master/C4_Container.puml !include -title Container Diagram for the WIQ System (C4 Level 2) +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") @@ -10,12 +10,12 @@ AddElementTag("Database", $bgColor="#darksalmon", $fontColor="#white") 'Containers Person(player, Player's Browser,"Preferred browser (Firefox, Chrome, Opera...)") -System_Boundary(wiq,"WIQ Server"){ +System_Boundary(wiq,"Kiwiq Server"){ Container(proxy,"Proxy","Nginx","Nginx web server", $tags="Internal system") - Container(web_app, "WIQ Client", "React, Typescript", "nginx web server", $tags="Internal system") - Container(backend_api, "WIQ REST API","Java SpringBoot 3",".jar file", $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,"WIQ Database","PostgreSQL","PostgreSQL docker container", $tags="Database") + ContainerDb(database,"Kiwiq Database","PostgreSQL","PostgreSQL docker container", $tags="Database") } System_Ext(wikidata,"WikiData API","REST API", $tags="External system") From fe1b2470df4333e693ab5e9ed9f9734feef4353a Mon Sep 17 00:00:00 2001 From: Dario Date: Sat, 27 Apr 2024 10:51:24 +0200 Subject: [PATCH 09/12] docs: rewritten doc 3 --- docs/src/03_system_scope_and_context.adoc | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/docs/src/03_system_scope_and_context.adoc b/docs/src/03_system_scope_and_context.adoc index b10e0979..378f2ee3 100644 --- a/docs/src/03_system_scope_and_context.adoc +++ b/docs/src/03_system_scope_and_context.adoc @@ -7,8 +7,7 @@ ifndef::imagesdir[:imagesdir: ../images] ---- 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 or images. +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 @@ -16,7 +15,21 @@ The WIQ application will communicate with the WikiData API through REST HTTP cal ---- 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. -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. From 164ce3954ecb74fecae96dc2b6fba74566efa6ce Mon Sep 17 00:00:00 2001 From: Dario Date: Sat, 27 Apr 2024 11:23:15 +0200 Subject: [PATCH 10/12] docs: workflow --- docs/src/04_solution_strategy.adoc | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/docs/src/04_solution_strategy.adoc b/docs/src/04_solution_strategy.adoc index 7d189696..434381e7 100644 --- a/docs/src/04_solution_strategy.adoc +++ b/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,19 +31,34 @@ 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. + +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. + +==== 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. + +==== 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 -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. +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. * In the backend, the structure will be that of a typical Maven project. * In the frontend, the structure will be quite different: From 92c8dada30f1323f863e620646e459ef3a63f9be Mon Sep 17 00:00:00 2001 From: Dario Date: Sat, 27 Apr 2024 11:46:10 +0200 Subject: [PATCH 11/12] docs: solution strategy --- docs/src/04_solution_strategy.adoc | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/docs/src/04_solution_strategy.adoc b/docs/src/04_solution_strategy.adoc index 434381e7..0dd2b698 100644 --- a/docs/src/04_solution_strategy.adoc +++ b/docs/src/04_solution_strategy.adoc @@ -60,7 +60,32 @@ Pull Requests were the main method of contributing to the project, these needing 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. - * In the backend, the structure will be that of a typical Maven project. +==== 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 + +With regards 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. + +==== 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. From 3dab0f00839a2bc79fc6c4073fe617b11ab9160d Mon Sep 17 00:00:00 2001 From: Dario Date: Sat, 27 Apr 2024 11:49:53 +0200 Subject: [PATCH 12/12] docs: solution strategy updated --- docs/src/04_solution_strategy.adoc | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/src/04_solution_strategy.adoc b/docs/src/04_solution_strategy.adoc index 0dd2b698..927a82f6 100644 --- a/docs/src/04_solution_strategy.adoc +++ b/docs/src/04_solution_strategy.adoc @@ -56,11 +56,12 @@ For branch naming we used a variation of Conventional Commits commit naming, nam 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 +=== 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. -==== API +==== 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. @@ -83,7 +84,10 @@ In our Spring Boot project the following structure is found in each of our modul 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 -With regards 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. +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: