Merge pull request #36 from Arquisoft/chore/gonzaloA/docu

Chore/gonzalo a/docu

.gitignore

@@ -1,3 +1,5 @@
 node_modules
 coverage
-docs/build
+docs/build
+.vscode
+.DS_Store

docs/diagrams/10_Quality_Tree.puml

@@ -0,0 +1,23 @@
+@startuml 
+title Quality attributes
+agent Quality
+agent Security
+agent Reliability
+agent Transferability
+agent Usability
+agent "Performance Efficiency"
+agent Maintainability
+agent Availability
+agent Compatibility
+agent "Functional Suitability"
+
+Quality --- Security
+Quality --- Reliability
+Quality --- Transferability
+Quality --- Usability
+Quality --- "Performance Efficiency"
+Quality --- Maintainability
+Quality --- Availability
+Quality --- Compatibility
+Quality --- "Functional Suitability"
+@enduml

docs/index.adoc

@@ -96,4 +96,6 @@ include::src/11_technical_risks.adoc[]
 // 12. Glossary
 include::src/12_glossary.adoc[]
 
-
+<<<<
+// 13. Annex
+include::src/13_annex.adoc[]

docs/src/01_introduction_and_goals.adoc

@@ -2,92 +2,46 @@ ifndef::imagesdir[:imagesdir: ../images]
 
 [[section-introduction-and-goals]]
 == Introduction and Goals
-
-[role="arc42help"]
-****
-Describes the relevant requirements and the driving forces that software architects and development team must consider. 
-These include
-
-* underlying business goals, 
-* essential features, 
-* essential functional requirements, 
-* quality goals for the architecture and
-* relevant stakeholders and their expectations
-****
+RTVE has hired the company HappySw, composed of students from the Oviedo School of Software Engineering, to develop a new experimental version of the quiz show Saber y Ganar. This application will be called WIQ, where users will be able to register and log in to play. The application will consist of answering questions of different types generated with Wikidata. For each question answered correctly, points will be obtained.
 
 === Requirements Overview
-
-[role="arc42help"]
-****
-.Contents
-Short description of the functional requirements, driving forces, extract (or abstract)
-of requirements. Link to (hopefully existing) requirements documents
-(with version number and information where to find it).
-
-.Motivation
-From the point of view of the end users a system is created or modified to
-improve support of a business activity and/or improve the quality.
-
-.Form
-Short textual description, probably in tabular use-case format.
-If requirements documents exist this overview should refer to these documents.
-
-Keep these excerpts as short as possible. Balance readability of this document with potential redundancy w.r.t to requirements documents.
+* The system shall provide non-registered users with the option to sign up.
+* The system shall provide unidentified users with the option to log in.
+* The system shall only be used by registered users.
+* The system shall have a game mode with 9 rounds.
+* In each round, the system shall generate a question.
+* In each round, the system shall generate four answers, with only one being correct.
+* The system shall offer registered users access to the number of games they have played.
+* The system shall offer registered users access the number of questions they have answered correctly.
+* The system shall offer registered users access the number of questions they have answered incorrectly.
+* The system shall offer registered users access the time they have spent within the system.
+* The system shall offer registered users access the ranking of the game.
+* The system shall set a time limit for registered users to respond to each question.
+
+See the complete functional requirements in the xref:#section-annex[Annex] of the documentation.
 
 
-.Further Information
-
-See https://docs.arc42.org/section-1/[Introduction and Goals] in the arc42 documentation.
-
-****
-
 === Quality Goals
-
-[role="arc42help"]
-****
-.Contents
-The top three (max five) quality goals for the architecture whose fulfillment is of highest importance to the major stakeholders. 
-We really mean quality goals for the architecture. Don't confuse them with project goals.
-They are not necessarily identical.
-
-Consider this overview of potential topics (based upon the ISO 25010 standard):
-
-image::01_2_iso-25010-topics-EN.drawio.png["Categories of Quality Requirements"]
-
-.Motivation
-You should know the quality goals of your most important stakeholders, since they will influence fundamental architectural decisions. 
-Make sure to be very concrete about these qualities, avoid buzzwords.
-If you as an architect do not know how the quality of your work will be judged...
-
-.Form
-A table with quality goals and concrete scenarios, ordered by priorities
-****
+[options="header",cols="1,3"]
+|===
+|Goal|Description
+| Functional suitability | The system shall fulfill its intended purpose effectively and efficiently, allowing users to register, log in, play the quiz, and access their user statistics.
+| Security | The system must prioritize user data security. It must implement robust authentication mechanisms for user registration and login. The API access points for user information and generated questions must be secured with proper authorization. 
+| Reliability | The system should be reliable in generating questions from Wikidata, ensuring that questions are accurate and diverse. The system must handle user registrations, logins, and game data storage without errors.
+| Availability | The system must be available 99.99% of the time a user tries to access it.
+| Maintainability | The system must be designed and implemented in a way that facilitates easy maintenance and updates.
+| Performance efficiency | The system must deliver optimal performance, ensuring responsive interactions for users. The automatic generation of questions from Wikidata and the real-time gameplay must be efficient. The system must handle N concurrent users.
+| Usability | The system must provide a user-friendly interface, making it easy for users to register, log in, and play the game. The system learning time for a user should be less than 4 hours.
+| Compatibility | The system must be compatible with various web browsers and devices, ensuring a seamless experience for users regardless of their choice of platform. It has to be well-optimized for different screen sizes and functionalities.
+| Transferability | The system must allow for easy transfer of user data and game-related information through its APIs.
+|===
 
 === Stakeholders
-
-[role="arc42help"]
-****
-.Contents
-Explicit overview of stakeholders of the system, i.e. all person, roles or organizations that
-
-* should know the architecture
-* have to be convinced of the architecture
-* have to work with the architecture or with code
-* need the documentation of the architecture for their work
-* have to come up with decisions about the system or its development
-
-.Motivation
-You should know all parties involved in development of the system or affected by the system.
-Otherwise, you may get nasty surprises later in the development process.
-These stakeholders determine the extent and the level of detail of your work and its results.
-
-.Form
-Table with role names, person names, and their expectations with respect to the architecture and its documentation.
-****
-
-[options="header",cols="1,2,2"]
+[options="header",cols="1,1,2"]
 |===
 |Role/Name|Contact|Expectations
-| _<Role-1>_ | _<Contact-1>_ | _<Expectation-1>_
-| _<Role-2>_ | _<Contact-2>_ | _<Expectation-2>_
+| RTVE  | [email protected] | To have a new experimental version of the Saber y Ganar quiz show.
+| HappySw | [email protected] | Develop a good application that fullfills the requirements expected by the client.
+| Registered user | Unknown | To play with an entertaining and easy-to-use application. An application with which the user learn about different topics.
+| Wikidata | [email protected] | Being able to offer service allowing people to use the data through the API.
 |===

docs/src/10_quality_requirements.adoc

@@ -2,72 +2,32 @@ ifndef::imagesdir[:imagesdir: ../images]
 
 [[section-quality-scenarios]]
 == Quality Requirements
-
-
-[role="arc42help"]
-****
-
-.Content
-This section contains all quality requirements as quality tree with scenarios. The most important ones have already been described in section 1.2. (quality goals)
-
-Here you can also capture quality requirements with lesser priority,
-which will not create high risks when they are not fully achieved.
-
-.Motivation
-Since quality requirements will have a lot of influence on architectural
-decisions you should know for every stakeholder what is really important to them,
-concrete and measurable.
-
-
-.Further Information
-
-See https://docs.arc42.org/section-10/[Quality Requirements] in the arc42 documentation.
-
-****
-
 === Quality Tree
+This quality tree is a high-level overview of the quality goals and requirements. The Quality tree uses "quality" as a root while the rest of the quality categories will be displayed as branches.
 
-[role="arc42help"]
-****
-.Content
-The quality tree (as defined in ATAM – Architecture Tradeoff Analysis Method) with quality/evaluation scenarios as leafs.
-
-.Motivation
-The tree structure with priorities provides an overview for a sometimes large number of quality requirements.
-
-.Form
-The quality tree is a high-level overview of the quality goals and requirements:
-
-* tree-like refinement of the term "quality". Use "quality" or "usefulness" as a root
-* a mind map with quality categories as main branches
-
-In any case the tree should include links to the scenarios of the following section.
-
-
-****
+image:10_Quality_Tree.png[]
 
 === Quality Scenarios
-
-[role="arc42help"]
-****
-.Contents
-Concretization of (sometimes vague or implicit) quality requirements using (quality) scenarios.
-
-These scenarios describe what should happen when a stimulus arrives at the system.
-
-For architects, two kinds of scenarios are important:
-
-* Usage scenarios (also called application scenarios or use case scenarios) describe the system’s runtime reaction to a certain stimulus. This also includes scenarios that describe the system’s efficiency or performance. Example: The system reacts to a user’s request within one second.
-* Change scenarios describe a modification of the system or of its immediate environment. Example: Additional functionality is implemented or requirements for a quality attribute change.
-
-.Motivation
-Scenarios make quality requirements concrete and allow to
-more easily measure or decide whether they are fulfilled.
-
-Especially when you want to assess your architecture using methods like
-ATAM you need to describe your quality goals (from section 1.2)
-more precisely down to a level of scenarios that can be discussed and evaluated.
-
-.Form
-Tabular or free form text.
-****
+To obtain a measurable system response to stimulus corresponding to the various quality branches outlined in the mindmap, we will use quality scenarios. Scenarios make quality requirements concrete and allow to more easily measure or decide whether they are fulfilled.
+
+==== Usage Scenarios
+[options="header",cols="1,3,1"]
+|===
+|Quality attribute|Scenario|Priority
+| Functional suitability | Users shall be able to register, log in, play the quiz, and access historical data without encountering errors or glitches. | High, Medium
+| Security | User data shall be securely handled. Robust authentication mechanisms shall be in place for user registration and login. API access points for user information and generated questions shall be secured with proper authorization. | High, High 
+| Reliability | The system shall reliably generate accurate and diverse questions from Wikidata. User registrations, logins, and game data storage shall be handled without errors. | High, Medium
+| Availability | The system shall be available 99.99% of the time when a user attempts to access it. | High, High
+| Performance efficiency | The system shall deliver optimal performance, ensuring responsive interactions for users. It shall efficiently generate questions from Wikidata and handle real-time gameplay with up to N concurrent users. | High, High
+| Usability | The system shall provide a user-friendly interface, allowing users to register, log in, and play the game with a learning time of less than 4 hours. | High, Medium
+| Compatibility | The system shall be compatible with various web browsers and devices, providing a seamless experience for users regardless of their choice of platform. It shall be well-optimized for different screen sizes and functionalities. | High, Medium
+| Transferability | The system shall allow for easy transfer of user data and game-related information through its APIs. | Medium, High
+| Testability | The unit tests shall have at least 75% coverage. | High, Medium
+|===
+==== Change Scenarios
+[options="header",cols="1,3,1"]
+|===
+|Quality attribute|Scenario|Priority
+| Maintainability | The system shall be designed and implemented in a way that allows for easy maintenance and updates. | High, Medium
+| Maintainability | The code of the system shall be well-documented, and modular, allowing for efficient troubleshooting and modifications. | High, Medium
+|===

docs/src/13_annex.adoc

@@ -0,0 +1,79 @@
+ifndef::imagesdir[:imagesdir: ../images]
+
+[[section-annex]]
+== Annex
+=== Functional Requirements
+==== Users Sign up.
+[none or no-bullet]
+* FR-USU 1. The system shall allow an unregistered user to register in the application.
+* FR-USU 2. The system shall request the necessary data to register the new user.
+[none or no-bullet]
+** FR-USU 2.1. The system shall request the following mandatory data to register the new user:
+[none or no-bullet]
+*** FR-USU 2.1.1. Username.
+*** FR-USU 2.1.2. Email address.
+*** FR-USU 2.1.3. Password.
+* FR-USU 3. The system shall not allow the user to be registered when any value entered by the new user is invalid.
+* FR-USU 4. When all the values entered by the new user are valid, the system shall check if the user is already registered in the persistence system.
+[none or no-bullet]
+** FR-USU 4.1. When a user with the same data is already found in the persistence system, the user shall not be able to create a new account since it already exists.
+** FR-USU 4.2. When no user matching the data is found in the persistence system.
+[none or no-bullet]
+*** FR-USU 4.2.1. The new user shall be registered in the system.
+
+==== Users Log in.
+[none or no-bullet]
+* FR-ULI 1. The system must allow an unidentified user to log in.
+[none or no-bullet]
+** FR-ULI 1.1. The system shall request the email address as the user identifier.
+[none or no-bullet]
+*** FR-ULI 1.1.1. The system must check that its format is valid.
+*** FR-ULI 1.1.2. It is a mandatory field.
+** FR-ULI 1.2. The system shall request the user's password.
+[none or no-bullet]
+*** FR-ULI 1.2.1. It is a mandatory field.
+** FR-ULI 1.3. The system shall automatically validate the entered data to verify when it corresponds to a registered user account.
+[none or no-bullet]
+*** FR-ULI 1.3.1. When the user is not stored in the persistence system, an error message shall be displayed.
+*** FR-ULI 1.3.2. When the user exists in the persistence system, but the passwords do not match, a message shall be displayed to the user notifying them of the error.
+*** FR-ULI 1.3.3. When the user is stored in the persistence system and the passwords match, the user shall be logged in.
+* FR-ULI 2. The system must allow users who are logged in to log out.
+
+==== Data management by the user.
+[none or no-bullet]
+* FR-DMU 1. The system shall allow all registered users to access their historical data from their participation.
+[none or no-bullet]
+** FR-DMU 1.1. Registered users shall be able to access the number of games they have played.
+** FR-DMU 1.2. Registered users shall be able to access the number of questions they have answered correctly.
+** FR-DMU 1.3. Registered users shall be able to access the number of questions they have answered incorrectly.
+** FR-DMU 1.4. Registered users shall be able to access the time they have spent within the system.
+** FR-DMU 1.5. Registered users shall be able to access the ranking of the game.
+
+==== Play to WIQ.
+[none or no-bullet]
+* FR-PWIQ 1. The system shall only allow registered users to play the WIQ game.
+* FR-PWIQ 2. The game consists of nine rounds.
+[none or no-bullet]
+** FR-PWIQ 2.1. In each round, the system shall automatically generate a question to the registered user.
+** FR-PWIQ 2.2. In each round, the system shall provide the registered user with four automatically generated possible answers.
+** FR-PWIQ 2.3. In each round, there shall always be only one correct answer.
+** FR-PWIQ 2.4. The system shall automatically end the game after completing the ninth round.
+* FR-PWIQ 3. The registered user must respond to the question before the specified time expires.
+[none or no-bullet]
+** FR-PWIQ 3.1. When the specified time has not ended, and the registered user has provided an answer:
+[none or no-bullet]
+*** FR-PWIQ 3.1.1. The system shall check if the answer is correct.
+[none or no-bullet]
+**** FR-PWIQ 3.1.1.1. When the answer is correct:
+[none or no-bullet]
+***** FR-PWIQ 3.1.1.1.1. The registered user shall earn 10 points.
+***** FR-PWIQ 3.1.1.1.2. When the registered user is in the ninth round, the system shall end the game.
+***** FR-PWIQ 3.1.1.1.3. When the registered user is not in the ninth round, the system shall move to the next round.
+**** FR-PWIQ 3.1.1.2. When the answer is incorrect:
+[none or no-bullet]
+***** FR-PWIQ 3.1.1.2.1. When the registered user is in the ninth round, the system shall end the game.
+***** FR-PWIQ 3.1.1.2.2. When the registered user is not in the ninth round, the system shall move to the next round.
+** FR-PWIQ 3.2. When the specified time has ended:
+[none or no-bullet]
+*** FR-PWIQ 3.2.1. When the registered user is in the ninth round, the system shall end the game.
+*** FR-PWIQ 3.2.2. When the registered user is not in the ninth round, the system shall move to the next round.