Merge branch 'develop' into feat/webapp/fix-error-messages

docs/diagrams/BusinessContextDiagram.puml

@@ -3,16 +3,22 @@
 !include <c4/C4_Context.puml>
 
 title Context Diagram for the WIQ System
-LAYOUT_WITH_LEGEND()
+AddElementTag("Person", $bgColor="#salmon", $fontColor="#white")
+AddElementTag("Internal system", $bgColor="#darksalmon", $fontColor="#white")
+AddElementTag("External system", $bgColor="#peachpuff", $fontColor="#963b17")
+
+AddRelTag("backup", $textColor="orange", $lineColor="orange", $lineStyle = DashedLine())
+
 
 'Containers
-Person(player, Player,"An authenticated player that wants to play WIQ games")
+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")
+Container(wiq, "WIQ Application","", "Application that allows the users to play WIQ games", $tags="Internal system")
 
-System_Ext(wikidata,"WikiData API","Contains the information used for the question generation")
+System_Ext(wikidata,"WikiData API","Contains the information used for the question generation", $tags="External system")
 
 'RELATIONS
 Rel(player,wiq,"Plays games")
 Rel(wiq,wikidata,"Asks for data for question generation")
+SHOW_LEGEND()
 @enduml

docs/diagrams/DeploymentDiagram.puml → docs/diagrams/deployment/DeploymentDiagram.puml

@@ -18,6 +18,9 @@ node "Server Hosting WIQ" #PeachPuff {
   node "PostgreSQL Docker" {
     database "WIQ Database"
   }
+  node "Question generator" {
+    component "Question_Generator.jar"
+  }
 }
 node "User Computer" #DarkSalmon{
   frame "Web Client"
@@ -29,4 +32,5 @@ node "WikiData Server" #DarkSalmon {
 "WIQ React Application" ..> "WIQ_API.jar" : "HTTPS"
 "WIQ_API.jar" ..> "WIQ Database" : "JPA"
 "WIQ API" ..> "WikiData REST API" : "HTTPS, SPARQL"
+"Question_Generator.jar" ..> "WIQ Database" : "JPA
 @enduml

docs/diagrams/sequence/SequenceDiagramGame.puml

@@ -0,0 +1,46 @@
+@startuml Game's life cycle
+title Game Sequence Diagram
+actor Client #darksalmon
+participant API #darksalmon
+database DB #salmon
+
+skinparam Style strictuml
+skinparam SequenceMessageAlignment center
+
+Client -> API : start game
+activate API #darksalmon
+API -> DB : store game info
+activate DB #salmon
+DB --> API : game info stored
+deactivate DB
+API --> Client : return game info
+deactivate API
+loop #PeachPuff Round
+  Client -> API : start round
+  activate API #darksalmon
+  API -> DB : ask for question
+  activate DB  #salmon
+  DB --> API : return question
+  deactivate DB
+  API --> Client : return question with all answers
+  deactivate API
+  Client -> API  : send chosen answer
+  activate API #darksalmon
+  API -> API    : check answer is correct
+  API -> DB     : update game info
+  activate DB #salmon
+  DB --> API    : game info updated
+ deactivate DB
+  API --> Client : inform user if guessed right
+
+
+end loop One question
+
+API -> DB : [if last round] update ranking
+activate DB #salmon
+DB --> API : ranking updated
+deactivate DB
+API --> Client : inform user if guessed right
+deactivate API
+
+@enduml

docs/diagrams/sequence/SequenceDiagramLogIn.puml

@@ -0,0 +1,33 @@
+@startuml login
+title Login Sequence Diagram
+actor Client #darksalmon
+participant API #darksalmon
+database DB #salmon
+skinparam Style strictuml
+skinparam SequenceMessageAlignment center
+
+Client -> API : enters credentials
+activate API #darksalmon
+API -> DB    : check credentials correct
+alt #PeachPuff credentials correct
+    activate DB #salmon
+    DB --> API     : returns result
+    deactivate DB
+    API -> API : generate jwt and refresh tokens
+    API -> DB    : save tokens
+    activate DB #salmon
+    DB --> API     : saves tokens
+    deactivate DB
+    API --> Client : return jwt dto
+    deactivate API
+else credentials incorrect
+    activate DB #salmon
+    DB --> API     : returns error
+    deactivate DB
+    activate API #darksalmon
+    API --> Client : return 403 error
+    deactivate API
+end
+
+
+@enduml

docs/diagrams/sequence/SequenceDiagramQuestionGeneration.puml

@@ -0,0 +1,24 @@
+@startuml question generator
+title Question Generator Sequence Diagram
+participant QuestionGenerator #darksalmon
+participant WikiDataQS #darksalmon
+database DB #salmon
+skinparam Style strictuml
+skinparam SequenceMessageAlignment center
+
+loop #PeachPuff Generate question templates
+activate QuestionGenerator #darksalmon
+QuestionGenerator -> WikiDataQS  : request query template
+activate WikiDataQS #darksalmon
+QuestionGenerator <-- WikiDataQS  : returns query answer
+deactivate WikiDataQS
+QuestionGenerator -> QuestionGenerator  : process query answer
+QuestionGenerator -> DB  : store answers
+activate DB #salmon
+QuestionGenerator -> DB  : store questions
+DB --> QuestionGenerator  :  info saved
+deactivate DB
+end loop
+
+deactivate QuestionGenerator
+@enduml

docs/diagrams/sequence/SequenceDiagramSignUp.puml

@@ -0,0 +1,32 @@
+@startuml sign up
+title Sign Up Sequence Diagram
+actor Client #darksalmon
+participant API #darksalmon
+database DB #salmon
+skinparam Style strictuml
+skinparam SequenceMessageAlignment center
+
+Client -> API : account details
+activate API #darksalmon
+API -> API : validate details
+API -> DB  : check email is unused
+alt #PeachPuff email is unused
+    activate DB #salmon
+    DB --> API  : email is unused
+    deactivate DB
+
+    API -> DB  : register user
+    activate DB #salmon
+    DB --> API  : user registered
+    deactivate DB
+    API --> Client  : return confirmation
+    deactivate API
+else email is used
+    activate DB #salmon
+    DB --> API  : email is used
+    deactivate DB
+    activate API #darksalmon
+    API --> Client  : 400 error
+    deactivate API
+end
+@enduml

docs/src/03_system_scope_and_context.adoc

@@ -3,7 +3,10 @@ ifndef::imagesdir[:imagesdir: ../images]
 == System Scope and Context
 === Business Context
 
-image::BusinessContext.png[align="center",title="Business Context",link="BusinessContext.png]
+[plantuml,"Business context diagram",png, align="center", title="Overall view of the business context"]
+----
+include::../diagrams/BusinessContextDiagram.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.
 

docs/src/05_building_block_view.adoc

@@ -9,8 +9,10 @@ ifndef::imagesdir[:imagesdir: ../images]
 === Whitebox Overall System
 
 _**Overview Diagram**_
-
-image::BusinessContext.png[align="center", title="Overall view of the business context"]
+[plantuml,"Business context diagram",png, align="center", title="Overall view of the business context"]
+----
+include::../diagrams/BusinessContextDiagram.puml[]
+----
 
 Motivation::
 This will be the general sketch of the elements interacting inside the application, including the external elements that will include the application.

docs/src/06_runtime_view.adoc

@@ -4,93 +4,29 @@ ifndef::imagesdir[:imagesdir: ../images]
 == Runtime View
 Here we can see what the main workflow of main parts of the project.
 
-=== General Game's life cycle
-* This diagram shows how should the application behave for an expected normal case scenario.
-
-[plantuml,"Game's life cycle diagram",png]
-----
-@startuml Game's life cycle
-
-actor Client
-
-skinparam Style strictuml
-skinparam SequenceMessageAlignment center
-
-Client --> API : start game
-loop One question
-  API --> QuestionRetriever         : ask for question
-  QuestionRetriever --> QuestionDB  : querying question
-
-  QuestionDB --> QuestionRetriever  : return first question and all answers
-  QuestionRetriever --> API         : return first question and all answers
-
-  API --> Client : return first question and all answers
-  Client -> API  : send chosen answer
-  API --> API    : check answer is correct
-  API --> Client : inform user guessed right
-end loop One question
-
-
-API --> Client : inform user guessed right last question
-API --> API    : update ranking
-API --> Client : show ranking
-
-@enduml
-----
-
 === Sign Up
 [plantuml,"Sign up diagram",png]
 ----
-@startuml sign up
-
-actor Client
-
-skinparam Style strictuml
-skinparam SequenceMessageAlignment center
-
-Client --> API : enters credentials
-API --> BD     : check credentials unused
-API --> BD     : register user
-BD --> Client  : return user token
-
-@enduml
+include::../diagrams/sequence/SequenceDiagramSignUp.puml[]
 ----
 
 === Login
 [plantuml,"Login diagram",png]
 ----
-@startuml login
-
-actor Client
-skinparam Style strictuml
-skinparam SequenceMessageAlignment center
+include::../diagrams/sequence/SequenceDiagramLogIn.puml[]
+----
 
-Client --> API : enters credentials
-API --> BD     : check credentials correct
-BD --> API     : return user token
-API --> BD     : save SWT
-API --> Client : return user token
+=== General Game's life cycle
+* This diagram shows how should the application behave for an expected normal case scenario.
 
-@enduml
+[plantuml,"Game's sequence diagram",png]
+----
+include::../diagrams/sequence/SequenceDiagramGame.puml[]
 ----
 
 === Question Generation
 [plantuml,"Question generation diagram",png]
 ----
-@startuml question generator
-skinparam Style strictuml
-skinparam SequenceMessageAlignment center
-
-QuestionGenerator --> WikiDataQS  : querying correct answer
-QuestionGenerator <-- WikiDataQS  : return correct answer
-
-QuestionGenerator --> WikiDataQS  : querying wrong answers
-QuestionGenerator <-- WikiDataQS  : return wrong answers
-
-QuestionGenerator --> QuestionDB  : store question
-QuestionGenerator --> QuestionDB  : store correct answer
-QuestionGenerator --> QuestionDB  : store wrong answers
-
-@enduml
+include::../diagrams/sequence/SequenceDiagramQuestionGeneration.puml[]
 ----
 

docs/src/07_deployment_view.adoc

@@ -3,8 +3,10 @@ ifndef::imagesdir[:imagesdir: ../images]
 [[section-deployment-view]]
 
 == Deployment View
-
-image::DeploymentDiagram.png[align="center",title="Deployment Diagram",link="DeploymentDiagram.png]
+[plantuml,"Deployment diagram",png]
+----
+include::../diagrams/deployment/DeploymentDiagram.puml[]
+----
 
 === Infrastructure Level 1
 
@@ -22,6 +24,7 @@ Mapping of Building Blocks to Infrastructure::
  * The API/backend is contained within the `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 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.
 
 === Infrastructure Level 2
 
@@ -38,3 +41,6 @@ Our main idea is that the server will be a self-contained .jar file with all the
 ===== 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.
+
+===== 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.