Merge pull request #30 from Arquisoft/documentation_jonathan

Documentation jonathan

docs/src/03_system_scope_and_context.adoc

@@ -69,6 +69,5 @@ together with a mapping table showing the relationships between channels and inp
 
 ****
 
-The following diagram represents the general structure of the project, as well as the communication channels between various system components. It shows communication to external sources, as well as communications between the various microsystems.
+image::03_Technical_Context.png[]
 
-image::03-deployment-diagram-EN.png[]

docs/src/05_building_block_view.adoc

@@ -151,4 +151,30 @@ package "WIQ App" {
 |Authentication microservice that allows the user to register and log in.
 |===
 
+=== Level 3
 
+image::05_Level_3_Diagram.png[]
+
+==== Motivation
+
+To display the inner architecture of the different microservices, as well as how do their components interact with themselves and with other components from other microsystems. All microservices follow the MVC architectural pattern, to the exception of the questions generator service. (since it has no UI to handle)
+
+==== Contained Building Blocks
+
+[options="header"]
+[cols="1,2"]
+|===
+|Name |Description
+|Questions Generator
+|Contains the required templates and proceedings to construct questions. In order to do so, it delegates the Wikidata querying to the Wikidata extractor. When the data is returned, the question is formulated through templates. 
+|Wikidata Extractor
+|Handles extraction and formatting of Wikidata’s output. It’s queries must cover all necessary information in order to construct the question(s), including not only the correct response, but also believable and coherent “decoy responses”.
+|Questions Historic Controller
+|Receives the generated questions, and sends them to the database. Besides, it also handles recovering them from the database and sending them where they are needed. (e.g: as response from an API call, or to the UI)
+|User Statistics Controller
+|Receives various information about the player’s performance in the match. There, some processing may occur before storing it in the database. Also handles retrieving the information and sending it where it’s needed (e.g: as response from an API call, or to the UI).
+|Game Controller
+|Handles all the game’s logic; where the user input’s processing takes place. It can request questions to the Questions Microservice, and also gather user statistics, to later be set to the User Statistics Controller.
+|UI for the game and statistics
+|Handles appeareance and presentation. Actions taken by the user are communicated to their respective controllers, that may respond accordingly.
+|===

docs/src/06_runtime_view.adoc

@@ -37,67 +37,115 @@ See https://docs.arc42.org/section-6/[Runtime View] in the arc42 documentation.
 
 ****
 
-=== Usage diagram
-[plantuml,"Scenario diagram",png]
+=== User plays a match. Only one question batch is needed.
+
+[plantuml,"Question generation 1",png]
 ----
-actor User
-entity APP
-entity QandA
-Activate User
-Activate APP
-User -> APP : Start Game
-Activate QandA
-APP -> QandA : Request
-QandA -> QandA : Generate QandA
-QandA --> APP : Return QandA
-deactivate QandA
-APP --> User : Game Prepared
-loop 
-   User -> APP: User Plays
-   APP -> User :Game Responds
+
+@startuml
+!theme vibrant
+autonumber
+
+actor "User" as user
+
+user -> "Game Service": Begins game
+"Game Service" -> "Question Service" : Requests n questions
+"Question Service" -> "Wikidata REST API" : Requests information to create questions
+"Wikidata REST API" -> "Question Service" : Returns information
+"Question Service" -> "Question Service" : Creates questions
+"Question Service" -> "Game Service" : Returns questions
+
+loop n times
+    "Game Service" -> user : Shows question
+    …
+    user -> "Game Service" : Responds question
 end
-APP --> User: Game Ends
-deactivate APP
-deactivate User
+
+"Game Service" -> "Question Historic Service" : Sends the shown questions
+"Game Service" -> "Player Statistics Service" : Sends the  user's match data
+@enduml 
+
 ----
 
+In circumstances in which few questions are needed for the game, it may be possible to extract all of them in a batch without affecting performance and response times. Besides, extracting them this way opens up the possibility of using multiple threads to gather the data, greatly increasing performance. However, if the querying times are too high, this strategy may cause great delays while loading the game. A possible alternative is explained below:
 
-=== <Runtime Scenario 1>
+=== User plays a match. An example of dynamic question generation.
 
+[plantuml,"Question generation 2",png]
+----
 
-* _<insert runtime diagram or textual description of the scenario>_
-* _<insert description of the notable aspects of the interactions between the
-building block instances depicted in this diagram.>_
+@startuml
+!theme vibrant
+autonumber
+
+actor "User" as user
+
+user -> "Game Service": Begins game
+"Game Service" -> "Question Service" : Requests n questions
+"Question Service" -> "Wikidata REST API" : Requests information to create questions
+"Wikidata REST API" -> "Question Service" : Returns information
+"Question Service" -> "Game Service" : Returns questions
+
+loop Until the game ends
+    loop n-k times
+        "Game Service" -> user : Shows question
+        ...
+        user -> "Game Service" : Responds question
+    end
+
+    "Game Service" -> "Question Service" : Requests n questions
+    "Question Service" -> "Wikidata REST API" : Requests information to create questions
+    "Wikidata REST API" -> "Question Service" : Returns information
+    "Question Service" -> "Question Service" : Creates questions
+    "Question Service" -> "Game Service" : Returns questions
+
+    loop k times
+        "Game Service" -> user : Shows question
+        ...
+        user -> "Game Service" : Responds question
+    end
+end
 
-It is possible to use a sequence diagram:
+"Game Service" -> "Question Historic Service" : Sends the shown questions
+"Game Service" -> "Player Statistics Service" : Sends the  user's match data
+@enduml 
 
-[plantuml,"Sequence diagram",png]
 ----
-actor Alice
-actor Bob
-database Pod as "Bob's Pod"
-Alice -> Bob: Authentication Request
-Bob --> Alice: Authentication Response
-Alice  --> Pod: Store route
-Alice -> Bob: Another authentication Request
-Alice <-- Bob: another authentication Response
+
+In cases where a lot of questions are needed, or wikidata querying has a great impact on performance, this alternative may prove to be convenient. By distributing the data fetching along the entire match, bottlenecks on performance will be reduced. Depending on the system load (or, optionally client device's specifications!) batch sizes may vary, adapting to maintain responsiveness.
+
+=== User consults its game statistics.
+
+[plantuml,"Consult Statistics",png]
 ----
 
-=== <Runtime Scenario 2>
+@startuml
+!theme vibrant
+autonumber
+
+actor "User" as user
 
-=== ...
+user -> "Player Statistics Service" : Requests user data
+"Player Statistics Service" -> "MongoDB Server" : Makes petition through REST API
+"MongoDB Server" -> "Player Statistics Service" : Returns information
+"Player Statistics Service" -> user : Shows data
+@enduml 
 
-=== <Runtime Scenario n>
+----
+
+=== User consults questions used in games.
+
+[plantuml,"Consult questions",png]
+----
+@startuml
+!theme vibrant
+autonumber
 
-=== Wikidata questions requests
+actor "User" as user
 
-[plantuml,"Sequence diagram WikidataApi",png]
+user -> "Question Historic Service" : Requests user data
+"Question Historic Service" -> "MongoDB Server" : Makes petition through REST API
+"MongoDB Server" -> "Question Historic Service" : Returns information
+"Question Historic Service" -> user : Shows data
+@enduml 
 ----
-actor User
-entity App
-entity WikidataApi
-User -> App: Starts a game
-App -> WikidataApi: Request data
-App <-- WikidataApi: Returns data
-User <-- App: Displays data in question-answer format
-----

docs/src/12_glossary.adoc

@@ -37,4 +37,7 @@ See https://docs.arc42.org/section-12/[Glossary] in the arc42 documentation.
 |MongoDB        |NoSQL database system that, instead of storing data in tables as a relational database does, stores data in JSON-like documents with a flexible schema. 
 |REACT          |Open source JavaScript library developed by Facebook to build interactive and responsive user interfaces (UI). It is one of the most popular tools for modern web application development.
 |Usability      |Ease with which users can interact with a product, system or application to achieve their objectives effectively, efficiently and satisfactorily. 
+|Dynamic question generation      | There may be circumstances where pre-generating the questions isn't feasible. So instead, questions can be generated while the user is playing the game and answering questions. 
+|Decoy answer          | For questions that offer multiple options to select the correct answer from, it will be necessary to generate believable incorrect answers, that match the topic and theme of the question. For example, when asking about the longest river in Egypt, along with the correct answer (The Nile) some other river names of the country could be chosen for alternatives.
+|Question template     | General structure of a question, which can or cannot transcend topics. For example, valid templates for questions could be: "What's the tallest mountain in <country>?" "What is <concept>?" "Who invented <x>?"
 |===