From 63fdcade99a74393a48c865049ce7cefc47e3a9f Mon Sep 17 00:00:00 2001 From: Gonzalo Alonso Fernandez Date: Sat, 24 Feb 2024 13:57:41 +0100 Subject: [PATCH 1/2] chore: fixing some tables, plantuml diagrams and writing a title for the documentation --- docs/index.adoc | 2 +- docs/src/01_introduction_and_goals.adoc | 27 ++++++++++----------- docs/src/03_system_scope_and_context.adoc | 1 - docs/src/04_solution_strategy.adoc | 3 ++- docs/src/05_building_block_view.adoc | 4 ++-- docs/src/09_architecture_decisions.adoc | 4 ++-- docs/src/10_quality_requirements.adoc | 29 +++++++++++++++++++++-- docs/src/11_technical_risks.adoc | 6 ++--- 8 files changed, 49 insertions(+), 27 deletions(-) diff --git a/docs/index.adoc b/docs/index.adoc index 29cb7d6a..185b5ddc 100644 --- a/docs/index.adoc +++ b/docs/index.adoc @@ -6,7 +6,7 @@ // configure EN settings for asciidoc include::src/config.adoc[] -= image:arc42-logo.png[arc42] Template += image:arc42-logo.png[arc42] WIQ_en2b :revnumber: 8.2 EN :revdate: January 2023 :revremark: (based upon AsciiDoc version) diff --git a/docs/src/01_introduction_and_goals.adoc b/docs/src/01_introduction_and_goals.adoc index 7b59875b..2bb8bfc1 100644 --- a/docs/src/01_introduction_and_goals.adoc +++ b/docs/src/01_introduction_and_goals.adoc @@ -26,22 +26,21 @@ See the complete functional requirements in the xref:#section-annex[Annex] of th |=== |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. +| Reliability | The system should be reliable in generating questions from Wikidata, ensuring that questions are accurate and diverse. The system shall handle user registrations, logins, and game data storage without errors. +| Availability | The system shall be available 99.99% of the time a user tries to access it. +| Maintainability | The system shall be designed and implemented in a way that facilitates easy maintenance and updates. +| Performance efficiency | The system shall deliver optimal performance, ensuring responsive interactions for users. The automatic generation of questions from Wikidata and the real-time gameplay shall be efficient. The system shall handle N concurrent users. +| Security | The system shall prioritize user data security. It shall implement robust authentication mechanisms for user registration and login. The API access points for user information and generated questions shall be secured with proper authorization. +| Usability | The system shall 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 shall 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. |=== === Stakeholders -[options="header",cols="1,1,2"] +[options="header",cols="1,2"] |=== -|Role/Name|Contact|Expectations -| RTVE | rtve@email.com | To have a new experimental version of the Saber y Ganar quiz show. -| HappySw | happysw@email.com | 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 | wikid@email.com | Being able to offer service allowing people to use the data through the API. +|Role/Name|Expectations +| RTVE | To have a new experimental version of the Saber y Ganar quiz show. +| HappySw | Develop a good application that fullfills the requirements expected by the client. +| Registered user | To play with an entertaining and easy-to-use application. An application with which the user learn about different topics. +| Wikidata | Being able to offer service allowing people to use the data through the API. |=== diff --git a/docs/src/03_system_scope_and_context.adoc b/docs/src/03_system_scope_and_context.adoc index 4ba4c3ec..4144bdae 100644 --- a/docs/src/03_system_scope_and_context.adoc +++ b/docs/src/03_system_scope_and_context.adoc @@ -2,7 +2,6 @@ ifndef::imagesdir[:imagesdir: ../images] [[section-system-scope-and-context]] == System Scope and Context === Business Context -**** image::BusinessContext.png[align="center",title="Business Context",link="BusinessContext.png] diff --git a/docs/src/04_solution_strategy.adoc b/docs/src/04_solution_strategy.adoc index cfc818d4..cb800080 100644 --- a/docs/src/04_solution_strategy.adoc +++ b/docs/src/04_solution_strategy.adoc @@ -25,8 +25,9 @@ We also have a Whatsapp community for the team, and a Notion wiki. === Important quality-related decisions +[options="header",cols="1,2"] |=== -|*Quality attribute pursued*|*Solution chosen* +|Quality attribute pursued|Solution chosen |Privacy|All stored password will be hashed, both client-side and server-side, to avoid password disclosure. The client-side password is also intended to prevent password discoverage in case it is a repeated one. |Robustness|Currently, all validations will take place server-side to avoid not being properly taken care of due to JavaScript desactivation, such as when using the NoScript plug-in |Availability|Since Wikidata has a 1 minute limit related to the API, the backend will start querying it upon start and fill the database with questions to increase speed and thus improve user experience| diff --git a/docs/src/05_building_block_view.adoc b/docs/src/05_building_block_view.adoc index a58bcc73..b32a758d 100644 --- a/docs/src/05_building_block_view.adoc +++ b/docs/src/05_building_block_view.adoc @@ -15,7 +15,7 @@ This is the overall view of the application. The diagram is composed of 3 elemen _**Overview Diagram**_ -image::BusinessContext.png["Overall view of the business context"] +image::BusinessContext.png[align="center", title="Overall view of the business context"] Motivation:: This will be the general sketch of the elements interacting inside the application, including the external elements that will include the application. @@ -42,7 +42,7 @@ Here is an specification of the inner structure of the WIQ Application. ==== White Box _WIQ Application_ -image::ContainerDiagram.png["Container for the WIQ System"] +image::ContainerDiagram.png[align="center", title="Container for the WIQ System"] [role="arc42help"] **** diff --git a/docs/src/09_architecture_decisions.adoc b/docs/src/09_architecture_decisions.adoc index 9bf87c3b..0454c52f 100644 --- a/docs/src/09_architecture_decisions.adoc +++ b/docs/src/09_architecture_decisions.adoc @@ -6,9 +6,9 @@ ifndef::imagesdir[:imagesdir: ../images] During the application development process, decisions had to be made as issues emerged. The most interesting design decisions are reflected in this architectural records: +[options="header",cols="1,4"] |=== -|*Decision* |*Explanation* - +|Decision|Explanation |React |Offers a powerful combination of performance, flexibility, and developer experience, making it a popular choice for building modern web applications. One of the members of the group has already worked with it in the past. It allows us to build a good user interface for the application. diff --git a/docs/src/10_quality_requirements.adoc b/docs/src/10_quality_requirements.adoc index 33d49327..b47f7d8c 100644 --- a/docs/src/10_quality_requirements.adoc +++ b/docs/src/10_quality_requirements.adoc @@ -5,7 +5,32 @@ ifndef::imagesdir[:imagesdir: ../images] === 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. -image:10_Quality_Tree.png[] +[plantuml,"Quality Tree",png] +---- +@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 +---- === Quality Scenarios 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. @@ -15,11 +40,11 @@ To obtain a measurable system response to stimulus corresponding to the various |=== |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 +| 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. | Medium, High | 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 diff --git a/docs/src/11_technical_risks.adoc b/docs/src/11_technical_risks.adoc index 0b9cbec2..4b7987dd 100644 --- a/docs/src/11_technical_risks.adoc +++ b/docs/src/11_technical_risks.adoc @@ -2,11 +2,9 @@ ifndef::imagesdir[:imagesdir: ../images] [[section-technical-risks]] == Risks and Technical Debts - - +[options="header",cols="1,2,2"] |=== -|*Risk* |*Explanation* | *Mitigation proposed* - +|Risk|Explanation|Mitigation proposed |Little knowledge of the technologies to be used |For most of the members of the team, is the first time working with technologies as React or Wikidata |Explore technologies documentation to familiarize ourselves with the technology, and seek examples of use. From 2f8ecdbda3485350ff18cc91e85df11d58efbfd5 Mon Sep 17 00:00:00 2001 From: Gonzalo Alonso Fernandez Date: Sun, 3 Mar 2024 11:47:16 +0100 Subject: [PATCH 2/2] fix: changing availabilty from 99.99% to 99%. --- docs/src/01_introduction_and_goals.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/01_introduction_and_goals.adoc b/docs/src/01_introduction_and_goals.adoc index 2bb8bfc1..61e69a83 100644 --- a/docs/src/01_introduction_and_goals.adoc +++ b/docs/src/01_introduction_and_goals.adoc @@ -27,7 +27,7 @@ See the complete functional requirements in the xref:#section-annex[Annex] of th |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. | Reliability | The system should be reliable in generating questions from Wikidata, ensuring that questions are accurate and diverse. The system shall handle user registrations, logins, and game data storage without errors. -| Availability | The system shall be available 99.99% of the time a user tries to access it. +| Availability | The system shall be available 99% of the time a user tries to access it. | Maintainability | The system shall be designed and implemented in a way that facilitates easy maintenance and updates. | Performance efficiency | The system shall deliver optimal performance, ensuring responsive interactions for users. The automatic generation of questions from Wikidata and the real-time gameplay shall be efficient. The system shall handle N concurrent users. | Security | The system shall prioritize user data security. It shall implement robust authentication mechanisms for user registration and login. The API access points for user information and generated questions shall be secured with proper authorization.