From 2605247beabb6a3aac6e3f904e803a975d4c57d8 Mon Sep 17 00:00:00 2001 From: Dario Date: Sat, 27 Apr 2024 12:56:37 +0200 Subject: [PATCH 01/11] docs: technologies in technical context --- docs/src/03_system_scope_and_context.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/src/03_system_scope_and_context.adoc b/docs/src/03_system_scope_and_context.adoc index 378f2ee3..a9341dc8 100644 --- a/docs/src/03_system_scope_and_context.adoc +++ b/docs/src/03_system_scope_and_context.adoc @@ -21,15 +21,15 @@ The Kiwiq system will be deployed together in the same server and contains diffe 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. +This client will be served to the client and communicates with the API through HTTPS REST calls and exchanges information through JSON objects. The client will be developed in React and Javascript and is deployed via a nginx server. * **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. +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. The DBMS is PostgreSQL. * **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 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. It is written in Java and uses JPA From 21e109bdfe7de9c2063f511eb7d9e61b3277833d Mon Sep 17 00:00:00 2001 From: Dario Date: Sat, 27 Apr 2024 14:36:08 +0200 Subject: [PATCH 02/11] feat: updated colors --- docs/diagrams/c4/C4-Level1.puml | 7 +++---- docs/diagrams/c4/C4-Level2.puml | 7 ++++--- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/diagrams/c4/C4-Level1.puml b/docs/diagrams/c4/C4-Level1.puml index 2ff9f8f4..289451f5 100644 --- a/docs/diagrams/c4/C4-Level1.puml +++ b/docs/diagrams/c4/C4-Level1.puml @@ -3,10 +3,9 @@ !include 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") - +AddElementTag("Person", $bgColor="#darkgreen", $fontColor="#white") +AddElementTag("Internal system", $bgColor="#darkseagreen", $fontColor="#003300") +AddElementTag("External system", $bgColor="#gray", $fontColor="#white") 'Containers Person(player, Player,"An authenticated player that wants to play Kiwiq games", $tags="Person") diff --git a/docs/diagrams/c4/C4-Level2.puml b/docs/diagrams/c4/C4-Level2.puml index 11f045f1..68eb91b4 100644 --- a/docs/diagrams/c4/C4-Level2.puml +++ b/docs/diagrams/c4/C4-Level2.puml @@ -3,10 +3,11 @@ !include title Container Diagram for the Kiwiq System (C4 Level 2) -AddElementTag("Person", $bgColor="#salmon", $fontColor="#white") -AddElementTag("Internal system", $bgColor="#peachpuff", $fontColor="#963b17") +AddElementTag("Person", $bgColor="#darkgreen", $fontColor="#white") +AddElementTag("Internal system", $bgColor="#darkseagreen", $fontColor="#003300") AddElementTag("External system", $bgColor="#gray", $fontColor="#white") -AddElementTag("Database", $bgColor="#darksalmon", $fontColor="#white") +AddElementTag("Database", $bgColor="#darkgreen", $fontColor="#white") +AddElementTag("Component", $bgColor="#darkolivegreen", $fontColor="#white") 'Containers Person(player, Player's Browser,"Preferred browser (Firefox, Chrome, Opera...)") From 2637fbf4d2628cdb6171d23c6f219e0c8c6fe77f Mon Sep 17 00:00:00 2001 From: Dario Date: Sat, 27 Apr 2024 14:36:25 +0200 Subject: [PATCH 03/11] docs: level 3 diagram --- docs/diagrams/c4/C4-Level3.puml | 48 +++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 docs/diagrams/c4/C4-Level3.puml diff --git a/docs/diagrams/c4/C4-Level3.puml b/docs/diagrams/c4/C4-Level3.puml new file mode 100644 index 00000000..39eb3eac --- /dev/null +++ b/docs/diagrams/c4/C4-Level3.puml @@ -0,0 +1,48 @@ +@startuml +!includeurl https://raw.githubusercontent.com/RicardoNiepel/C4-PlantUML/master/C4_Container.puml +!include +!include +title Container Diagram for the Kiwiq System (C4 Level 3) +AddElementTag("Person", $bgColor="#darkgreen", $fontColor="#white") +AddElementTag("Internal system", $bgColor="#darkseagreen", $fontColor="#003300") +AddElementTag("External system", $bgColor="#gray", $fontColor="#white") +AddElementTag("Database", $bgColor="#darkgreen", $fontColor="#white") +AddElementTag("Component", $bgColor="#darkolivegreen", $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") + System_Boundary(backend_api,"Kiwiq REST API"){ + Component(auth,"Authentication module") + Component(games,"Game module") + Component(questions,"Question module") + Component(statistics,"Statistics module") + } + + 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(question_generator, database,"Stores questions ","JPA") + +Rel(web_app,questions,"Asks for question information","JSON,HTTPS") +Rel(web_app,games,"Plays a game","JSON,HTTPS") +Rel(web_app,auth,"Ask for login and register","JSON,HTTPS") +Rel(web_app,statistics,"Asks for statistics","JSON,HTTPS") + + +Rel(games,database,"Stores game/user information","JPA") + +Rel(games,questions,"Gets questions") +Rel(questions,database,"Stores game/user information","JPA") +Rel(statistics,database,"Stores game/user information","JPA") +Rel(auth,database,"Stores game/user information","JPA") +@enduml \ No newline at end of file From ab5703a21d0fefbb8d004a13e598322fa8539099 Mon Sep 17 00:00:00 2001 From: Dario Date: Sat, 27 Apr 2024 15:30:35 +0200 Subject: [PATCH 04/11] docs: document 5 --- docs/src/05_building_block_view.adoc | 55 +++++++++++++++++++++------- 1 file changed, 41 insertions(+), 14 deletions(-) diff --git a/docs/src/05_building_block_view.adoc b/docs/src/05_building_block_view.adoc index 147b29e1..3ac37f46 100644 --- a/docs/src/05_building_block_view.adoc +++ b/docs/src/05_building_block_view.adoc @@ -5,13 +5,12 @@ ifndef::imagesdir[:imagesdir: ../images] == Building Block View - -=== Whitebox Overall System +=== Whitebox Overall System (C4 Level 1) _**Overview Diagram**_ [plantuml,"Business context diagram",png, align="center", title="Overall view of the business context"] ---- -include::../diagrams/BusinessContextDiagram.puml[] +include::../diagrams/c4/C4-Level1.puml[] ---- Motivation:: @@ -21,31 +20,59 @@ Contained Building Blocks:: **** * **Player:** This is the user that will be playing with our application. They will need to be authenticated to be able to play. -* **WIQ Application:** This is the main application that will reproduce how the game will work. This part will be more detailed in the following parts. +* **Kiwiq Application:** This is the main application that will reproduce how the game will work. This part will be more detailed in the following parts. * **WikiData API:** This is an external API, which will provide us with the information to produce the questions. **** Important Interfaces:: -This part will be more detailed later, since the structure of the different interfaces/classes has not been discussed by the team yet. - +The user will interact with the system via the web client, which will allow them to play games. The system will then interact with the WikiData API via the question generator module by doing HTTPs requests with SPARQL queries in them. -=== Level 2 +=== Container Diagram (C4 Level 2) +[plantuml,"Container diagram",png, align="center", title="Overall view of the container context"] +---- +include::../diagrams/c4/C4-Level2.puml[] +---- Motivation:: -An inner view on the WIQ Application and its components inside. How the WIQ application will be structured inside and its main components. +An inner view on the Kiwiq Application and its components inside. How the Kiwiq application will be structured inside and its main components. Contained Building Blocks:: **** -* **WIQ Client:** This is the connection between the user and the application. It will allow the users to play the WIQ game. This part will be developed in React with Typescript for its clear component structure, simplified code quality and separation of concerns. -* **WIQ REST API:** This is the part responsible for managing the users that log into the application, managing also the logic of the game and sending the request to the Wikidata API for the question generation. This part is going to be developed in SpringBoot due to its foundations on the Java programming language, which is the language that the developers find the easiest to develop in. +* **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 is the connection between the user and the application. It will allow the users to play the WIQ game. This part will be developed in React with Typescript for its clear component structure, simplified code quality and separation of concerns. +* **Kiwiq REST API:** This is the part responsible for managing the users that log into the application, managing also the logic of the game and sending the request to the Wikidata API for the question generation. This part is going to be developed in SpringBoot due to its foundations on the Java programming language, which is the language that the developers find the easiest to develop in. * **Question Generator Module:** This component is in charge of everything related with the questions. It retrieves the information from WikiData QS and stores it in the WIQ Database, which later is queried for questions and answers from the REST API. -* **WIQ Database:** This is where the most important data is going to be stored. Such as, users questions and other game info that will be specified in the future. The database we chose to use is PostgreSQL, since it is compatible with Docker and it's an object-relational kind of database, which is easier for the developers to use. Another alternative would've been to use MySQL. +* **Kiwiq Database:** This is where the most important data is going to be stored. Such as, users questions and other game info that will be specified in the future. The database we chose to use is PostgreSQL, since it is compatible with Docker and it's an object-relational kind of database, which is easier for the developers to use. Another alternative would've been to use MySQL. **** Important Interfaces:: -We are connecting the front end with the back end via REST API. Also, the Question Generator Module communicates with WikiData QS this way. -The Question Generator Module connects to the WIQ DataBase through JPA. -In the near future, we are planning on allowing HTTPS connections, so there would be a proxy server in between the user's agent and the back end. +We are connecting the front end with the back end via a REST API, using HTTPs requests. Also, the Question Generator Module communicates with WikiData QS this way. +The Question Generator Module connects to the WIQ DataBase through JPA, where it stores the questions that will later be used by the REST API. + +=== Component Diagram (C4 Level 3) +[plantuml,"Component diagram",png, align="center", title="Overall view of the component context"] +---- +include::../diagrams/c4/C4-Level3.puml[] +---- +Motivation:: +An inner view on the Kiwiq API and its components inside. How the Kiwiq API will be structured inside and its main components. + +Contained Components:: +**** +* **Authentication module:** +Tasked with handling of the login and register of the users as well as restricting the user access. +* **Game module:** +Tasked with handling the games allowing for creating new games, starting rounds, sending answers and updating statistics. +* **Question module:** +Tasked with handling the questions, allowing to get any question from the system, as well as retrieving them from the database. +* **Statistics module:** +Tasked with handling the statistics, allowing to check the top 10 users in the system, as well as saving the statistics. + +All the previously mentioned modules also use a common module named *commons*, that contains logic common to all of them, like the user handling or some util classes. +**** + From b6177891af9754c4eff8b38b2bbf06e8812e86e7 Mon Sep 17 00:00:00 2001 From: Dario Date: Sat, 27 Apr 2024 15:38:41 +0200 Subject: [PATCH 05/11] docs: changed colors --- .../sequence/SequenceDiagramGame.puml | 22 +++++++++---------- .../sequence/SequenceDiagramLogIn.puml | 18 +++++++-------- .../sequence/SequenceDiagramSignUp.puml | 18 +++++++-------- 3 files changed, 29 insertions(+), 29 deletions(-) diff --git a/docs/diagrams/sequence/SequenceDiagramGame.puml b/docs/diagrams/sequence/SequenceDiagramGame.puml index 5b5a2c0a..1d66695c 100644 --- a/docs/diagrams/sequence/SequenceDiagramGame.puml +++ b/docs/diagrams/sequence/SequenceDiagramGame.puml @@ -1,34 +1,34 @@ @startuml Game's life cycle title Game Sequence Diagram -actor Client #darksalmon -participant API #darksalmon -database DB #salmon +actor Client #darkolivegreen +participant API #darkolivegreen +database DB #darkolivegreen skinparam Style strictuml skinparam SequenceMessageAlignment center Client -> API : start game -activate API #darksalmon +activate API #darkolivegreen API -> DB : store game info -activate DB #salmon +activate DB #darkolivegreen DB --> API : game info stored deactivate DB API --> Client : return game info deactivate API -loop #PeachPuff Round +loop #darkseagreen Round Client -> API : start round - activate API #darksalmon + activate API #darkolivegreen API -> DB : ask for question - activate DB #salmon + activate DB #darkolivegreen DB --> API : return question deactivate DB API --> Client : return question with all answers deactivate API Client -> API : send chosen answer - activate API #darksalmon + activate API #darkolivegreen API -> API : check answer is correct API -> DB : update game info - activate DB #salmon + activate DB #darkolivegreen DB --> API : game info updated deactivate DB API --> Client : inform user if guessed right @@ -37,7 +37,7 @@ loop #PeachPuff Round end loop One question API -> DB : [if last round] update ranking -activate DB #salmon +activate DB #darkolivegreen DB --> API : ranking updated deactivate DB API --> Client : inform user if guessed right diff --git a/docs/diagrams/sequence/SequenceDiagramLogIn.puml b/docs/diagrams/sequence/SequenceDiagramLogIn.puml index a30ad948..0b10edc6 100644 --- a/docs/diagrams/sequence/SequenceDiagramLogIn.puml +++ b/docs/diagrams/sequence/SequenceDiagramLogIn.puml @@ -1,30 +1,30 @@ @startuml login title Login Sequence Diagram -actor Client #darksalmon -participant API #darksalmon -database DB #salmon +actor Client #darkolivegreen +participant API #darkolivegreen +database DB #darkolivegreen skinparam Style strictuml skinparam SequenceMessageAlignment center Client -> API : enters credentials -activate API #darksalmon +activate API #darkolivegreen API -> DB : check credentials correct -alt #PeachPuff credentials correct - activate DB #salmon +alt #darkseagreen credentials correct + activate DB #darkolivegreen DB --> API : returns result deactivate DB API -> API : generate jwt and refresh tokens API -> DB : save tokens - activate DB #salmon + activate DB #darkolivegreen DB --> API : saves tokens deactivate DB API --> Client : return jwt dto deactivate API else credentials incorrect - activate DB #salmon + activate DB #darkolivegreen DB --> API : returns error deactivate DB - activate API #darksalmon + activate API #darkolivegreen API --> Client : return 403 error deactivate API end diff --git a/docs/diagrams/sequence/SequenceDiagramSignUp.puml b/docs/diagrams/sequence/SequenceDiagramSignUp.puml index 8d9fe1e2..8ba91312 100644 --- a/docs/diagrams/sequence/SequenceDiagramSignUp.puml +++ b/docs/diagrams/sequence/SequenceDiagramSignUp.puml @@ -1,31 +1,31 @@ @startuml sign up title Sign Up Sequence Diagram -actor Client #darksalmon -participant API #darksalmon -database DB #salmon +actor Client #darkolivegreen +participant API #darkolivegreen +database DB #darkolivegreen skinparam Style strictuml skinparam SequenceMessageAlignment center Client -> API : account details -activate API #darksalmon +activate API #darkolivegreen API -> API : validate details API -> DB : check email is unused -alt #PeachPuff email is unused - activate DB #salmon +alt #darkseagreen email is unused + activate DB #darkolivegreen DB --> API : email is unused deactivate DB API -> DB : register user - activate DB #salmon + activate DB #darkolivegreen DB --> API : user registered deactivate DB API --> Client : return confirmation deactivate API else email is used - activate DB #salmon + activate DB #darkolivegreen DB --> API : email is used deactivate DB - activate API #darksalmon + activate API #darkolivegreen API --> Client : 400 error deactivate API end From bfe36449cd48dda8c2a19dd3149786345defadaf Mon Sep 17 00:00:00 2001 From: Dario Date: Sat, 27 Apr 2024 15:38:48 +0200 Subject: [PATCH 06/11] docs: removed unused tag --- docs/diagrams/c4/C4-Level2.puml | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/diagrams/c4/C4-Level2.puml b/docs/diagrams/c4/C4-Level2.puml index 68eb91b4..e6ff9dca 100644 --- a/docs/diagrams/c4/C4-Level2.puml +++ b/docs/diagrams/c4/C4-Level2.puml @@ -7,7 +7,6 @@ AddElementTag("Person", $bgColor="#darkgreen", $fontColor="#white") AddElementTag("Internal system", $bgColor="#darkseagreen", $fontColor="#003300") AddElementTag("External system", $bgColor="#gray", $fontColor="#white") AddElementTag("Database", $bgColor="#darkgreen", $fontColor="#white") -AddElementTag("Component", $bgColor="#darkolivegreen", $fontColor="#white") 'Containers Person(player, Player's Browser,"Preferred browser (Firefox, Chrome, Opera...)") From 3df300c52cd7160df0a64b934598591757676090 Mon Sep 17 00:00:00 2001 From: Dario Date: Sat, 27 Apr 2024 15:38:58 +0200 Subject: [PATCH 07/11] docs: changed color --- .../SequenceDiagramQuestionGeneration.puml | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/diagrams/sequence/SequenceDiagramQuestionGeneration.puml b/docs/diagrams/sequence/SequenceDiagramQuestionGeneration.puml index fd7e49a5..8426374a 100644 --- a/docs/diagrams/sequence/SequenceDiagramQuestionGeneration.puml +++ b/docs/diagrams/sequence/SequenceDiagramQuestionGeneration.puml @@ -1,20 +1,20 @@ @startuml question generator title Question Generator Sequence Diagram -participant QuestionGenerator #darksalmon -participant WikiDataQS #darksalmon -database DB #salmon +participant QuestionGenerator #darkolivegreen +participant WikiDataQS #darkolivegreen +database DB #darkolivegreen skinparam Style strictuml skinparam SequenceMessageAlignment center -loop #PeachPuff Generate question templates -activate QuestionGenerator #darksalmon +loop #darkseagreen Generate question templates +activate QuestionGenerator #darkolivegreen QuestionGenerator -> WikiDataQS : request query template -activate WikiDataQS #darksalmon +activate WikiDataQS #darkolivegreen QuestionGenerator <-- WikiDataQS : returns query answers deactivate WikiDataQS QuestionGenerator -> QuestionGenerator : process query answer QuestionGenerator -> DB : store answers -activate DB #salmon +activate DB #darkolivegreen QuestionGenerator -> DB : store questions DB --> QuestionGenerator : info saved deactivate DB From 33734306181bf82b8aaf3189a06437f55fbf6a56 Mon Sep 17 00:00:00 2001 From: Dario Date: Sat, 27 Apr 2024 15:57:34 +0200 Subject: [PATCH 08/11] docs: changed colors --- docs/src/07_deployment_view.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/07_deployment_view.adoc b/docs/src/07_deployment_view.adoc index 703b45f0..19a15f53 100644 --- a/docs/src/07_deployment_view.adoc +++ b/docs/src/07_deployment_view.adoc @@ -5,7 +5,7 @@ ifndef::imagesdir[:imagesdir: ../images] == Deployment View [plantuml,"Deployment diagram",png] ---- -include::../diagrams/deployment/DeploymentDiagram.puml[] +include::../diagrams/deployment/DeploymentDiagramLevel1.puml[] ---- === Infrastructure Level 1 From 0ac26ea0b2780eb090fe18d26d69da35678840c9 Mon Sep 17 00:00:00 2001 From: Dario Date: Sat, 27 Apr 2024 15:57:38 +0200 Subject: [PATCH 09/11] docs: changed colors --- .../deployment/DeploymentDiagram.puml | 36 ---------------- .../deployment/DeploymentDiagramLevel1.puml | 42 +++++++++++++++++++ 2 files changed, 42 insertions(+), 36 deletions(-) delete mode 100644 docs/diagrams/deployment/DeploymentDiagram.puml create mode 100644 docs/diagrams/deployment/DeploymentDiagramLevel1.puml diff --git a/docs/diagrams/deployment/DeploymentDiagram.puml b/docs/diagrams/deployment/DeploymentDiagram.puml deleted file mode 100644 index 19174a75..00000000 --- a/docs/diagrams/deployment/DeploymentDiagram.puml +++ /dev/null @@ -1,36 +0,0 @@ -@startuml - -title WIQ Deployment View - -legend right - |Color| Type | - |<#PeachPuff>| WIQ Server | - |<#DarkSalmon>| External Service | -end legend - -node "Server Hosting WIQ" #PeachPuff { - node "WIQ WebApp Server"{ - component "WIQ React Application" - } - node "WIQ API" { - component "WIQ_API.jar" - } - node "PostgreSQL Docker" { - database "WIQ Database" - } - node "Question generator" { - component "Question_Generator.jar" - } -} -node "User Computer" #DarkSalmon{ - frame "Web Client" -} -node "WikiData Server" #DarkSalmon { - frame "WikiData REST API" -} -"Web Client" ..> "WIQ React Application" : "HTTPS" -"WIQ React Application" ..> "WIQ_API.jar" : "HTTPS" -"WIQ_API.jar" ..> "WIQ Database" : "JPA" -"Question_Generator.jar" ..> "WikiData REST API" : "HTTPS, SPARQL" -"Question_Generator.jar" ..> "WIQ Database" : "JPA" -@enduml \ No newline at end of file diff --git a/docs/diagrams/deployment/DeploymentDiagramLevel1.puml b/docs/diagrams/deployment/DeploymentDiagramLevel1.puml new file mode 100644 index 00000000..95445a8b --- /dev/null +++ b/docs/diagrams/deployment/DeploymentDiagramLevel1.puml @@ -0,0 +1,42 @@ +@startuml + +title WIQ Deployment View + +legend right + |Color| Type | + |<#darkseagreen>| WIQ Server | + |<#darkolivegreen>| External Service | +end legend + +node "Server Hosting WIQ" #darkseagreen { + node "KIWIQ Proxy" + node "KIWIQ WebApp Server" { + component "KIWIQ React Application" + } + node "KIWIQ API"{ + component "KIWIQ_API.jar" + } + node "PostgreSQL Docker" { + database "KIWIQ Database" + } + node "Question generator" { + component "Question_Generator.jar" + } + node "Grafana" + node "Prometheus" +} +node "User Computer" #darkolivegreen{ + frame "Web Client" +} +node "WikiData Server" #darkolivegreen { + frame "WikiData REST API" +} +"Web Client" ..> "KIWIQ Proxy" : "HTTPS" +"KIWIQ Proxy" ..> "KIWIQ React Application" +"KIWIQ React Application" ..> "KIWIQ_API.jar" : "HTTPS" +"KIWIQ_API.jar" ..> "KIWIQ Database" : "JPA" +"Question_Generator.jar" ..> "WikiData REST API" : "HTTPS, SPARQL" +"Question_Generator.jar" ..> "KIWIQ Database" : "JPA" +"Prometheus" ..> "KIWIQ_API.jar" : "Actuator" +"Grafana" ..> "Prometheus" +@enduml \ No newline at end of file From 6ccd8978ba0d981773529bd2689c2fac40d0fb70 Mon Sep 17 00:00:00 2001 From: Dario Date: Sat, 27 Apr 2024 16:43:51 +0200 Subject: [PATCH 10/11] docs: deployment levels --- .../deployment/DeploymentDiagramLevel1.puml | 25 ++++++++++--------- .../deployment/DeploymentDiagramLevel2.puml | 25 +++++++++++++++++++ docs/src/07_deployment_view.adoc | 14 ++++++++--- 3 files changed, 48 insertions(+), 16 deletions(-) create mode 100644 docs/diagrams/deployment/DeploymentDiagramLevel2.puml diff --git a/docs/diagrams/deployment/DeploymentDiagramLevel1.puml b/docs/diagrams/deployment/DeploymentDiagramLevel1.puml index 95445a8b..f361abf8 100644 --- a/docs/diagrams/deployment/DeploymentDiagramLevel1.puml +++ b/docs/diagrams/deployment/DeploymentDiagramLevel1.puml @@ -4,31 +4,32 @@ title WIQ Deployment View legend right |Color| Type | - |<#darkseagreen>| WIQ Server | - |<#darkolivegreen>| External Service | + |<#darkseagreen>| Container | + |<#darkolivegreen>| WIQ Server | + |<#OliveDrab>| External Service | end legend -node "Server Hosting WIQ" #darkseagreen { - node "KIWIQ Proxy" - node "KIWIQ WebApp Server" { +node "Server Hosting WIQ" #darkolivegreen { + node "KIWIQ Proxy" #darkseagreen + node "KIWIQ WebApp Server" #darkseagreen { component "KIWIQ React Application" } - node "KIWIQ API"{ + node "KIWIQ API" #darkseagreen{ component "KIWIQ_API.jar" } - node "PostgreSQL Docker" { + node "PostgreSQL Docker" #darkseagreen{ database "KIWIQ Database" } - node "Question generator" { + node "Question generator" #darkseagreen{ component "Question_Generator.jar" } - node "Grafana" - node "Prometheus" + node "Grafana" #darkseagreen + node "Prometheus" #darkseagreen } -node "User Computer" #darkolivegreen{ +node "User Computer" #OliveDrab { frame "Web Client" } -node "WikiData Server" #darkolivegreen { +node "WikiData Server" #OliveDrab { frame "WikiData REST API" } "Web Client" ..> "KIWIQ Proxy" : "HTTPS" diff --git a/docs/diagrams/deployment/DeploymentDiagramLevel2.puml b/docs/diagrams/deployment/DeploymentDiagramLevel2.puml new file mode 100644 index 00000000..fec796b2 --- /dev/null +++ b/docs/diagrams/deployment/DeploymentDiagramLevel2.puml @@ -0,0 +1,25 @@ +@startuml + +title KIWIQ API Deployment View + +legend right + |Color| Type | + |<#darkseagreen>| WIQ artifact | + |<#OliveDrab>| Package | +end legend + +node "KIWIQ_API.jar" #darkseagreen { + component "auth" #OliveDrab + component "commons"#OliveDrab + component "game" #OliveDrab + component "questions" #OliveDrab + component "statistics" #OliveDrab + +} +"auth" ..> "commons" +"game" ..> "commons" +"questions" ..> "commons" +"statistics" ..> "commons" +"game" ..> "questions" +"game" ..> "statistics" +@enduml \ No newline at end of file diff --git a/docs/src/07_deployment_view.adoc b/docs/src/07_deployment_view.adoc index 19a15f53..d9398810 100644 --- a/docs/src/07_deployment_view.adoc +++ b/docs/src/07_deployment_view.adoc @@ -21,10 +21,13 @@ As stated before, we consider the main advantage of this architecture the interc Mapping of Building Blocks to Infrastructure:: * The webapp/frontend/client is contained within the `webapp` subfolder. - * The API/backend is contained within the `api` subfolder. + * The API/backend is contained within the `quiz-api` subfolder. ** The database will be generated on deployment. ** Wikidata is an external component, so although it is an important part of the deployment architecture, it is something we do not have access to changing. + ** The grafana config is found within the `monitoring/grafana` subdirectory + ** The prometheus config is found within the `monitoring/prometheus` subdirectory * The question generator is a separate component that will be deployed on the server only at the beginning of the system. It is contained within the `questiongenerator` subfolder. + * The configuration for the proxy container is found within the `proxy_conf` subfolder. === Infrastructure Level 2 @@ -33,14 +36,17 @@ Mapping of Building Blocks to Infrastructure:: This component is self-contained and does not require much explanation. ==== API/Backend - +[plantuml,"API Deployment diagram",png] +---- +include::../diagrams/deployment/DeploymentDiagramLevel2.puml[] +---- ===== Server -Our main idea is that the server will be a self-contained .jar file with all the dependencies required within. It will communicate with the database and periodically query Wikidata to generate questions until a certain number has been obtained once per minute to fill up the database and improve speed. +Our main idea is that the server will be a self-contained .jar file with all the dependencies required within. It will communicate with the database to retrieve the questions. ===== Database -The database will contain the data used by the system. Therefore, it will contain user data, as well as the data related to the questions and their answers. The databases to store the questions (and therefore the answers) and the user data might be different, though. +The database will contain the data used by the system. Therefore, it will contain user data, as well as the data related to the questions and their answers. ===== Question Generator The question generator will be run only at the beginning of the application. It will connect with Wikidata using SPARQL to generate questions and answers and store them in the database. This question generation will generate all the questions used by the application at once. It could be run again to generate new questions if they are added. From aa14f3c660b903538464991e05c7a2ed6c8454bc Mon Sep 17 00:00:00 2001 From: Dario Date: Sat, 27 Apr 2024 17:21:15 +0200 Subject: [PATCH 11/11] docs: doc 8 --- docs/diagrams/uml/ConceptsDomainModel.puml | 95 ++++++++++++++++++++++ docs/src/08_concepts.adoc | 85 +++---------------- 2 files changed, 105 insertions(+), 75 deletions(-) create mode 100644 docs/diagrams/uml/ConceptsDomainModel.puml diff --git a/docs/diagrams/uml/ConceptsDomainModel.puml b/docs/diagrams/uml/ConceptsDomainModel.puml new file mode 100644 index 00000000..63449912 --- /dev/null +++ b/docs/diagrams/uml/ConceptsDomainModel.puml @@ -0,0 +1,95 @@ +@startuml +enum QuestionCategory { + GEOGRAPHY + SPORTS + MUSIC + ART + VIDEOGAMES +} + +enum AnswerCategory { + CAPITAL_CITY + COUNTRY + SONG + STADIUM + BALLON_DOR + GAMES_PUBLISHER + PAINTING + WTPOKEMON + GAMES_COUNTRY + GAMES_GENRE + BASKETBALL_VENUE + COUNTRY_FLAG +} + +enum QuestionType { + TEXT + IMAGE +} + +enum GameMode { + KIWI_QUEST + FOOTBALL_SHOWDOWN + GEO_GENIUS + VIDEOGAME_ADVENTURE + ANCIENT_ODYSSEY + RANDOM + CUSTOM +} + +class Question { + content: String + answers: List + correctAnswer: Answer + questionCategory: QuestionCategory + type: QuestionType + games: List +} + +class User { + username: String + email: String + password: String + role: String + games: List + statistics: Statistics +} + +class Statistics { + correct: Long + wrong: Long + total: Long + user: User +} + +class Answer { + text: String + category: AnswerCategory + language: String +} + +class Game { + rounds: long + actualRound: long + user: User + questions: List + correctlyAnsweredQuestions: int + language: String + roundStartTime: LocalDateTime + roundDuration: Integer + currentQuestionAnswered: boolean + isGameOver: boolean + gamemode: GameMode + questionCategoriesForCustom: List +} + + +User "1"--"1" Statistics +Game "n"--"n" Question +Game "n" -- "1" User +Question "n" -- "n" Answer +GameMode -- Game +Question -- QuestionCategory +Answer -- AnswerCategory +Question -- QuestionType +@enduml \ No newline at end of file diff --git a/docs/src/08_concepts.adoc b/docs/src/08_concepts.adoc index 4d2e9248..7ccdd2e3 100644 --- a/docs/src/08_concepts.adoc +++ b/docs/src/08_concepts.adoc @@ -4,90 +4,25 @@ ifndef::imagesdir[:imagesdir: ../images] == Cross-cutting Concepts .Domain Model -This is the first version of the diagram, it will be updated if needed. +This is the diagram that includes the domain model of the backend. -[plantuml,"ConceptsDomainModel1",png] +[plantuml,"Concept Domain Model",png] ---- -@startuml -enum QuestionCategory { - GEOGRAPHY - SPORTS - MUSIC -} - -enum AnswerCategory { - CAPITAL_CITY - COUNTRY - SONG - STADIUM - BALLON_DOR -} - -enum QuestionType{ - TEXT - IMAGE - AUDIO -} - -class Question{ - content: String - answers: List - correctAnswer: Answer - questionCategory: QuestionCategory - type: QuestionType - games: List -} - -class User{ - username: String - email: String - password: String - role: String - games: List -} - -class Statistics{ - correct: Long - wrong: Long - total: Long - user: User -} - -class Answer { - text: String - category: AnswerCategory - language: String -} - -class Game { - user: User - questions: List - rounds: int - actualRound: int - correctlyAnsweredQuestions: int - language: String - roundStartTime: LocalDateTime - roundDuration: Integer - currentQuestionAnswered: boolean - isGameOver: boolean -} - - -User "1"--"1" Statistics -Game "n"--"n" Question -Game "n" -- "1" User -Question "n" -- "n" Answer - -@enduml +include::../diagrams/uml/ConceptsDomainModel.puml[] ---- |=== -| Class | Explanation -| Question | The model of the questions, has a type to specify if it is text, image or audio. Stores both right and wrong answers +| *Class* | *Explanation* +| Question | The model of the questions, has a type to specify if it is text or image. Stores both right and wrong answers | User | The people using the application, they have statistics and take part in a ranking to compete | Answer | Models each possible answer, created to reuse answers that are common to different questions, as well as distractors | Game | It is created when the user starts a game and includes the rounds that the user has to answer | Statistics | Stores information about the amount of correct and wrong answers that each user has answered +| *Enum* | *Explanation* +| QuestionCategory | Category for the question +| QuestionType | Type of the question (if it shows a text or an image etc) +| AnswerCategory | Category of the answer (used also for getting distractors) +| GameMode | Game mode for the game |=== .Question Generator