Documentation update

Arquisoft · Apr 6, 2024 · a0312ab · a0312ab
1 parent dd89602
commit a0312ab
Show file tree

Hide file tree

Showing 6 changed files with 66 additions and 71 deletions.
diff --git a/docs/src/01_introduction_and_goals.adoc b/docs/src/01_introduction_and_goals.adoc
@@ -42,44 +42,44 @@ Keep these excerpts as short as possible. Balance readability of this document w
 See https://docs.arc42.org/section-1/[Introduction and Goals] in the arc42 documentation.
 
 ****
-The functional requirements have been grouped into the different microservices the web application will have.
+
+The functional requirements are the following:
+* The application must be accesible through the web
+* Users must be able to register into the system
+* Users must be able to see data about their past games (score, correct/wrong answers, number of questions answered...)
+* Questions must be automatically generated from Wikidata.
+* Questions must be answered before some specific time.
+* Each question must have one right answer and several incorrect ones or distractors. Both the right answer and the distractors should be automatically generated.
+* The system must give access to the information about the users through an API.
+* The system must give access to information about the generated questions through an API.
+
+
+The functional requirements have been grouped into the different microservices the web application will have:
 
 ==== User and Authorization Services
 [decimal]
 . The User service allows the user to
 [arabic]
-.. Register.
-.. Delete the account.
-.. Update the account.
-.. Recover the password.
+.. Register
 . The authorization service allows the user to 
 [arabic]
-.. Log in.
-.. Log out.
-. A user can retrieve the following information from the User service
+.. Log in
+
+==== Ranking Service
+. A user can retrieve the following information from the Ranking service
 [arabic]
-.. Name.
-.. Email.
-.. Profile picture.
-.. Questions answered.
-. The system must be able to manage the user's access to the system.
+.. Points scored
+.. Number of questions answered
+.. Correct answers
+.. Incorrect answers
+. The system must be able to manage the user's access to the system
 
 ==== Question Service
 [decimal, start=5]
-. The Question service retrieves questions generated from wikidata.
-. A user can retrieve the following information from the Question service
-[arabic]
-.. Select a category.
-.. Select a difficulty.
-.. Select a question.
-.. Select an answer.
-. Questions must be stored in a database.
-. The database used is MongoDB.
-. Questions are classified by
+. The question service provides the following functionallities
 [arabic]
-.. Category.
-.. Difficulty.
-. The questions should be selected randomly.
+.. Generate a random question from a given category with 4 options
+.. Validate the answer and update the score accordingly
 
 === Quality Goals
 

diff --git a/docs/src/02_architecture_constraints.adoc b/docs/src/02_architecture_constraints.adoc
@@ -31,40 +31,28 @@ Architects need a clear understanding of the areas where they have creative free
 |===
 | Constraints | Explanation
 
-| *Privacy (by SOLID)*
-| The web application must be able to save in a secure and persistence way.
-
 | *GitHub*
 | It will be used to coordinate the projects work, tracks changes and manage workflow.
 
-| *Time*
-| The web application will be developed along this course, that means our time is limited and we require an efficient time management.
-
 
 | *Documentation*
-| In order to keep it clean, efficient and simple it will follow Arc42 method.
+| In order to keep it clean, efficient and simple, it will follow Arc42 method and be deployed to be able to look at it at any time.
 
 
-| *Time*
-| Since the project will be done in this semester our time is limited, and we need to stick to the deadlines and manage our time in an efficient way.
+| *Deployment*
+| The project has to be deployed when a release is made
 
 
-| *Code*
-| The code requires a small description of what it does. In addition, we must build it in a clean way and that is easy to expand and can adapt to changes in an easy way.
-
-
-| *Test*
-| The test has to be correctly tested in order to accomplish the desired behavior.
+| *Time*
+| Since the project will be done in this semester our time is limited, and we need to stick to the deadlines and manage our time in an efficient way.
 
 
-| Node.js
-| Open-source, cross-platform JavaScript runtime environment and library for running web applications outside the client’s browser.
+| *Testing*
+| We need to have a good coverage of unitary testing (80%+) and some acceptance testing covering all the webapp functionallity
 
-| *Ruby*
-| Dynamic, open source programming language with a focus on simplicity and productivity.
 
-| *JavaScript*
-| Programming language that allows you to implement complex features on web page.
+| *Wikidata*
+| It has to be used for the question generation.
 |===
 
 
diff --git a/docs/src/03_system_scope_and_context.adoc b/docs/src/03_system_scope_and_context.adoc
@@ -48,18 +48,23 @@ The title of the table is the name of your system, the three columns contain the
 
 ****
 
+The player is the only actor in the main system, which is the one that makes use of the different APIs that will be described later.
+The player can initially interact with the authentication system to either register or login and then, by playing the game, the question
+service will be triggered for either generating the questions or validating the player's answer. The player can also access data about 
+the past games of all users in a ranking.
+
 [plantuml,"Context Diagram",png]
 ----
 actor Player
 [Wikidata] <<external>>
 
 [WIQ Game] <<system>>
 [UsersAPI] <<internal>>
-[GeneratedQuestionsAPI] <<internal>>
+[questionsAPI] <<internal>>
 Player ..> (WIQ Game) : register/login
-[GeneratedQuestionsAPI] ..> Wikidata
+[questionsAPI] ..> Wikidata
 [WIQ Game] ..> UsersAPI
-[WIQ Game] ..> GeneratedQuestionsAPI
+[WIQ Game] ..> questionsAPI
 ----
 
 [cols="e,2e" options="header"]
@@ -81,6 +86,6 @@ Player ..> (WIQ Game) : register/login
 |Users Info API
 |Manages data of users, both registration/login data and their past scores
 
-|Generated Questions API
+|questions API
 |Manages generation of questions from Wikidata
 |===
diff --git a/docs/src/05_building_block_view.adoc b/docs/src/05_building_block_view.adoc
@@ -40,6 +40,9 @@ See https://docs.arc42.org/section-5/[Building Block View] in the arc42 document
 
 ****
 
+The system is based on having a player interact with a GUI which makes use of different APIs that hold most of the 
+important functionallity
+
 === Whitebox Overall System
 
 [role="arc42help"]
@@ -71,11 +74,11 @@ actor Player
 rectangle "WIQ Game (Level 1)"{
 [WIQ Game GUI]
 [UsersAPI]
-[GeneratedQuestionsAPI] #BurlyWood
+[questionsAPI] #BurlyWood
 Player ..> (WIQ Game GUI)
-[GeneratedQuestionsAPI] ..> Wikidata
+[questionsAPI] ..> Wikidata
 [WIQ Game GUI] ..> UsersAPI
-[WIQ Game GUI] ..> GeneratedQuestionsAPI
+[WIQ Game GUI] ..> questionsAPI
 }
 ----
 
@@ -92,8 +95,8 @@ Contained Black boxes::
 |WIQ Game GUI
 |Main window in which questions are shown and can be answered by the player. The latter can also see past scores.
 
-|Generated Questions API
-|In charge of generating the questions
+|questions API
+|In charge of generating the questions and validating the answer
 
 |UsersAPI
 |In charge of keeping track of the data of the users (registration and scores)
@@ -150,25 +153,29 @@ Please prefer relevance over completeness. Specify important, surprising, risky,
 Leave out normal, simple, boring or standardized parts of your system
 ****
 
-==== Generated Questions API (White Box)
+==== questions API (White Box)
+
+This is the Component that holds the functionallity for the main purpose of the webapp: Allowing players to see questions and 
+answer them, getting a consequent score update.
 
 [role="arc42help"]
 ****
 ...describes the internal structure of _building block 1_.
 ****
 
-[plantuml,"Generated Questions API (WhiteBox)",png]
+[plantuml,"questions API (WhiteBox)",png]
 ----
 [Wikidata]
 [wikibase-sdk] <<library>>
 [WIQ Game GUI]
 database MongoDB
 
-rectangle "GenedQuestsAPI (Level 2)"{
-[GenQuestsService] ..> [wikibase-sdk]
-[GenQuestsService] ..> [Wikidata]
-[GenQuestsService] <--> MongoDB
-[WIQ Game GUI] ..> [GenQuestsService] : new Question
+rectangle "questionsAPI (Level 2)"{
+[question-service] ..> [wikibase-sdk]
+[question-service] ..> [Wikidata]
+[question-service] <--> MongoDB
+[WIQ Game GUI] ..> [question-service] : new question
+[WIQ Game GUI] ..> [question-service] : validate answer
 }
 ----
 
@@ -182,8 +189,8 @@ Contained Black boxes::
 |===
 |Name |Responsibility
 
-|GenQuestsService
-|Receives different petitions regarding the generation of questions and responds accordingly.
+|question-service
+|Receives different petitions regarding the generation of questions and validation of answers and responds accordingly.
 
 |wikibase-sdk
 |External library that facilitates and simplifies the use of wikidata for the generation of questions.

diff --git a/docs/src/08_concepts.adoc b/docs/src/08_concepts.adoc
@@ -55,11 +55,6 @@ image::08-Crosscutting-Concepts-Structure-EN.png["Possible topics for crosscutti
 See https://docs.arc42.org/section-8/[Concepts] in the arc42 documentation.
 ****
 
-=== _Domain model and terminology_
-
-
-
-
 === _Microservice based system_
 
 Different business functionallities will be developed in different independent services.

diff --git a/docs/src/11_technical_risks.adoc b/docs/src/11_technical_risks.adoc
@@ -26,7 +26,7 @@ See https://docs.arc42.org/section-11/[Risks and Technical Debt] in the arc42 do
 
 [options="header", cols="1,1,1,1"]
 |===
-|Risk |Why it exists |Severity - Explanation |Possible solutions
+|Risk/Technical debt |Why it exists |Severity - Explanation |Possible solutions
 
 |Use of wikibase-sdk version 8 (not final)
 |It is the last version that supports 'require', which is needed to use express in the same module