Documentation abel

docs/src/01_introduction_and_goals.adoc

@@ -77,10 +77,10 @@ A table with quality goals and concrete scenarios, ordered by priorities
 [options="header",cols="1,3"]
 |===
 |Quality Goal|Description
+| _Learnability_ | _Any user must be able to use the app with ease. The interface must remind the user to the one in  Saber y Ganar quiz show._
 | _Satisfaction_ | _Users will not get repeated questions in at least a hundred questions._
 | _Modularity_ | _The application will be divided in modules so that a change on one component has minimal impact on other components._
 | _Testability_ | _The application should be able to go through different test and complete them successfully._
-| _Learnability_ | _Any user must be able to use the app with ease. The interface must remind the user to the one in  Saber y Ganar quiz show._
 | _Time behaviour_ | _Users will not have to wait more than 500ms to get a new question._
 |===
 

docs/src/02_architecture_constraints.adoc

@@ -33,7 +33,7 @@ See https://docs.arc42.org/section-2/[Architecture Constraints] in the arc42 doc
 |*OS/Browser Independence*        |The project must be available to the maximum amount of users feasible. That includes support for mainstream OSs (_Windows_, _Linux_, _MacOS_) and browsers. (_Chrome_, _Safari_, _Firefox_, _Edge_)
 |*Usage of _REACT_*      |The _REACT JS_ framework will be used to develop the front-end of the project.
 |*Docker*     | The application will operate within a Docker environment.
-|*Version Control*      |In order of the project to be graded adequately, it must use _GitHub_ as its version control system. The contributions of each team member and agreements reached must be easily traceable.
+|*Version Control*      |In order for the project to be graded adequately, it must use _GitHub_ as its version control system. The contributions of each team member and agreements reached must be easily traceable.
 |*Wikidata* | To generate questions, WikiData would be used as a knowledge base. Wikidata is a free and open knowledge base that can be read and edited by both humans and machines. Wikidata acts as central storage for the structured data of its sister Wikimedia projects, including Wikipedia, Wikivoyage, Wiktionary, Wikisource and others. 
 |*Continuous integration and delivery*      |The development must progress through frequent integration of small changes into the main branch. New features must be automatically deployed with ease. (In our case, using _Docker_)
 |===

docs/src/03_system_scope_and_context.adoc

@@ -45,7 +45,7 @@ The title of the table is the name of your system, the three columns contain the
 
 ****
 
-[cols=3 options="header"]
+[cols="1,2,2" options="header"]
 |===
 |Entity           |Input        |Output
 |*User*      | App usage and experience. | The user will introduce and send its credentials every time it creates a new account or logs into an existing one.
@@ -69,5 +69,21 @@ together with a mapping table showing the relationships between channels and inp
 
 ****
 
-image::03_Technical_Context.png[]
+[plantuml,"Technical_Context Diagram",png]
+----
+!pragma layout smetana
+
+actor "User"
+node "\t\t\tApp\t\t\t\t"{
+    rectangle "Web App"
+    rectangle "REST API"
+}
+rectangle "Wikidata" #lightblue
+database "\nMongoDB\n" as MongoDB #white
+
+User -right- "Web App" : "HTTPS\t"
+"Web App" -right- "REST API" : HTTPS (REST)
+"REST API" -right-- "MongoDB" : "\tHTTPS"
+"Web App" -down- "Wikidata" : " HTTPS (REST)"
+----
 

docs/src/04_solution_strategy.adoc

@@ -8,7 +8,6 @@ ifndef::imagesdir[:imagesdir: ../images]
 In order to develop the application and adhere to the constraints, we selected the following technologies:
 
 - ReactJS: JavaScript library that streamlines the development of graphical interfaces for web applications.
-- TypeScript: Extension of JavaScript, bolstering it with type support for improved development.
 - GitHub: Platform offering remote repository services for project development, task management, and version control.
 - MongoDB: A non-linear database selected to oversee storage of diverse application contents, with each microservice possessing its dedicated database.
 - NodeJS: Facilitates efficient management of asynchronous events, notably beneficial for scalable network applications and database administration.
@@ -22,13 +21,13 @@ We will use PlantUML and UMLet for creating the documentation's diagrams.
 
 === Approaches to Achieve Top Quality Goals
 
-[cols="1,2,3"]
+[cols="1,2,3" options="header"]
 |===
 | Quality Goal | Scenario | Solution Approach
 
-| Privacy
-| Users seek reassurance in the safety and privacy of their data within our app.
-| Ensuring user data security and privacy within the application.
+| Scalability
+| The application's design must accommodate changes effortlessly throughout its lifecycle.
+| Employing a microservices approach to minimize code repetition and enhance understanding of application distribution, ensuring future scalability.
 
 | Usability
 | Seamless execution of all application functions is crucial for user satisfaction.
@@ -38,9 +37,6 @@ We will use PlantUML and UMLet for creating the documentation's diagrams.
 | Application architecture must facilitate seamless addition or modification of functionalities with minimal code changes.
 | Implementing design patterns and adhering to code conventions to ensure clean and maintainable code. Additionally, prioritizing testing during development for long-term maintainability.
 
-| Scalability
-| The application's design must accommodate changes effortlessly throughout its lifecycle.
-| Employing a microservices approach to minimize code repetition and enhance understanding of application distribution, ensuring future scalability.
 
 |===
 

docs/src/05_building_block_view.adoc

@@ -45,8 +45,13 @@ In the best case you will get away with examples or simple signatures.
 
 === Level 1: Overall System's whitebox
 
-image::05_level1Diagram.png[Level 1 Diagram]
+[plantuml,"Level 1 Diagram",png]
+----
+!pragma layout smetana
 
+:User: -> [WIQ App] : "Interacts with"
+[WIQ App] <.> [WikiData] : "Gets data"
+----
 
 ==== Motivation
 
@@ -71,7 +76,7 @@ Its headline is the name of the black box.
 ****
 
 [options="header"]
-[cols="1,2"]
+[cols="1,4"]
 |===
 |Name |Description
 |User
@@ -110,57 +115,140 @@ according the the following black box template:
 ****
 
 
-image::05_level2Diagram.png[Level 2 Diagram]
-
+[plantuml,"Level 2 Diagram",png]
+----
+!pragma layout smetana
+
+:User:
+package "WIQ App" {
+:User: -> [WebApp] : " Interacts    "
+[WebApp] <-> [Gateway Service] : Redirects Requests
+[Gateway Service] <--down-> [Game Service] : Plays
+[Gateway Service] <-- [Question Historic Service] : Loads data
+[Gateway Service] <-- [User Statistics Service] : Loads data
+[Gateway Service] <-> [UserAuth Service] : Logs in / Registers
+[Game Service] -> [User Statistics Service] : Stores data
+[Game Service] <-left-> [Questions Service] : Gets questions
+[Questions Service] -up-> [Question Historic Service] : Stores data
+}
+[Questions Service] <.left.> [WikiData] : "  Gets data  "
+----
 
 ==== Motivation
 
 *_WiQ_* application is the general structure of a system in which users will have the possibility to play a video game implementation of the popular RTVE programme, "Saber y Ganar". 
 
 ==== Contained Building Blocks
 
-[options="header"]
-[cols="1,2"]
+[cols="1,4" options="header"]
 |===
 |Name |Description
-|Web App
-|Layer in which the user will interact directly and which will connect with the different services.
-|Questions Service
-|Microservice to generate the questions used by the application from WikiData
-|Game Service
-|Microservice that implements the quiz game
-|Question Historic Service
-|Microservice that stores the generated questions for later consultation
-|User Statistics Service
-|Microservice that stores the statistics of the games played by the user.
-|Authentification Service
-|Authentication microservice that allows the user to register and log in.
+|Web App |Layer in which the user will interact directly and which will connect with the different services.
+|Gateway Service |Microservice that redirects the requests from the WebApp to its corresponding microservices
+|Questions Service |Microservice to generate the questions used by the application from WikiData
+|Game Service |Microservice that implements the quiz game
+|Question Historic Service |Microservice that stores the generated questions for later consultation
+|User Statistics Service |Microservice that stores the statistics of the games played by the user.
+|UserAuth Service |Authentication microservices that allows the user to register and log in.
 |===
 
 === Level 3
 
-image::05_Level_3_Diagram.png[Level 3 Diagram]
+[plantuml,"Level 3 Diagram",png]
+----
+!pragma layout smetana
+
+actor "User"
+rectangle "Wikidata"
+
+package "WIQ App"{
+
+    component "WebApp"
+    component "Gateway Service" as GatewayS
+
+    package "Game Service" {
+        component "Game Controller"
+    }
+
+    package "User Statistics Service" as USS {
+        component "Statistics Controller"
+        database "Database" as USDB
+    }
+
+    package "Questions Historic Service" as QHS{
+        component "Question Historic Controller" as QHController
+        database "Database" as QhDB
+    }
+    package "Questions Service"{
+        component "Wikidata Extractor"
+        component "Questions Generator"
+        database "Database" as QSDB
+    }
+    package "UserAuth Service" {
+        component "Auth Service"
+        component "User Service"
+        database "Database" as UADB
+    }
+}
+
+User -right-> WebApp : Uses
+WebApp <-right-> GatewayS: Redirects requests
+
+GatewayS <--up--> "UserAuth Service" : "Handles user\nlogin/registry"
+GatewayS <-down-> "Game Service" : "Handles user current game\n"
+GatewayS <--up-- "QHS" : "\nReceives generated\nquestions"
+GatewayS <--- "USS" : "Receives\t\t\t\nuser statistics\t\t\t"
+
+"Game Service" <---> "Questions Service" : "Receives question petitions,\nsends questions\n\n"
+"Game Service" ---> "USS" : "Sends user\t\nstatistics\t\t"
+"Questions Service" -up-> "QHS" : "Sends\ngenerated\nquestions"
+
+"Wikidata" .up.> "Wikidata Extractor" : "Returns data"
+"Wikidata" <.up. "Wikidata Extractor" : "Queries"
+"Wikidata Extractor" --> QSDB
+"Questions Generator" <-- QSDB
+"Questions Generator" --> QSDB
+
+"QHController" --> QhDB
+"QHController" <-- QhDB
+
+"Statistics Controller" --> USDB
+"Statistics Controller" <-- USDB
+
+"Auth Service" --> UADB
+"Auth Service" <-- UADB
+"User Service" --> UADB
+"User Service" <-- UADB
+----
 
 ==== 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)
+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 those who have no UI to handle.
 
 ==== Contained Building Blocks
 
-[options="header"]
-[cols="1,2"]
+[cols="1,4" options="header"]
 |===
 |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”.
+
+|User Service
+|It retrieves the data from new users and registers them in the database.
+
+|Auth Service
+|It retrieves the data from returning users and checks if they are in the database.
+
+|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 sent to the User Statistics Controller.
+
 |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.
+
+|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. It gets the data through the database so 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”. It stores the data retrieved on the database.
 |===

docs/src/06_runtime_view.adoc

@@ -41,9 +41,6 @@ See https://docs.arc42.org/section-6/[Runtime View] in the arc42 documentation.
 
 [plantuml,"Question generation 1",png]
 ----
-
-@startuml
-!theme vibrant
 autonumber
 
 actor "User" as user
@@ -63,8 +60,6 @@ end
 
 "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:
@@ -73,9 +68,6 @@ In circumstances in which few questions are needed for the game, it may be possi
 
 [plantuml,"Question generation 2",png]
 ----
-
-@startuml
-!theme vibrant
 autonumber
 
 actor "User" as user
@@ -108,8 +100,6 @@ end
 
 "Game Service" -> "Question Historic Service" : Sends the shown questions
 "Game Service" -> "Player Statistics Service" : Sends the  user's match data
-@enduml 
-
 ----
 
 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.
@@ -118,9 +108,6 @@ In cases where a lot of questions are needed, or wikidata querying has a great i
 
 [plantuml,"Consult Statistics",png]
 ----
-
-@startuml
-!theme vibrant
 autonumber
 
 actor "User" as user
@@ -129,16 +116,12 @@ 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 
-
 ----
 
 === User consults questions used in games.
 
 [plantuml,"Consult questions",png]
 ----
-@startuml
-!theme vibrant
 autonumber
 
 actor "User" as user
@@ -147,5 +130,4 @@ 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 
 ----