From a0312ab4eced64d7ff8da923f1c3578f273e2810 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Fern=C3=A1ndez=20Noriega?= Date: Sat, 6 Apr 2024 20:51:17 +0200 Subject: [PATCH 1/2] Documentation update --- docs/src/01_introduction_and_goals.adoc | 52 +++++++++++------------ docs/src/02_architecture_constraints.adoc | 30 ++++--------- docs/src/03_system_scope_and_context.adoc | 13 ++++-- docs/src/05_building_block_view.adoc | 35 +++++++++------ docs/src/08_concepts.adoc | 5 --- docs/src/11_technical_risks.adoc | 2 +- 6 files changed, 66 insertions(+), 71 deletions(-) diff --git a/docs/src/01_introduction_and_goals.adoc b/docs/src/01_introduction_and_goals.adoc index 767ee49..7717116 100644 --- 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 index 2908f75..7f94006 100644 --- 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 index 3f24776..c74e0fe 100644 --- a/docs/src/03_system_scope_and_context.adoc +++ b/docs/src/03_system_scope_and_context.adoc @@ -48,6 +48,11 @@ 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 @@ -55,11 +60,11 @@ actor Player [WIQ Game] <> [UsersAPI] <> -[GeneratedQuestionsAPI] <> +[questionsAPI] <> 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 |=== \ No newline at end of file diff --git a/docs/src/05_building_block_view.adoc b/docs/src/05_building_block_view.adoc index 4f0573c..8c804f4 100644 --- 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] <> [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 index 5ea68b2..09a5d54 100644 --- 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 index 6297197..725b865 100644 --- 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 From 55870af263e5bca7c98987bd398841d6da7f723e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Fern=C3=A1ndez=20Noriega?= Date: Sat, 6 Apr 2024 20:56:35 +0200 Subject: [PATCH 2/2] Missing one modification --- docs/src/09_architecture_decisions.adoc | 42 +++++++------------------ 1 file changed, 12 insertions(+), 30 deletions(-) diff --git a/docs/src/09_architecture_decisions.adoc b/docs/src/09_architecture_decisions.adoc index 9ffe83d..de8391d 100644 --- a/docs/src/09_architecture_decisions.adoc +++ b/docs/src/09_architecture_decisions.adoc @@ -33,35 +33,17 @@ See https://docs.arc42.org/section-9/[Architecture Decisions] in the arc42 docum There you will find links and examples about ADR. **** -|=== -| Constraints | Explanation -| Title -| Web Server Platform: A Comprehensive Overview -| Context -| Choosing the right web server platform involves balancing technical requirements, stakeholder preferences, user considerations, and project constraints. It's a critical decision that impacts performance, security, user experience, and project success. Achieving alignment across these factors is essential for making an informed choice. -| Decision -| Oracle Cloud -| Status -| Proposed -| Consequences -| We need to suppoort the web application with the leasr cost possible -|=== - - - - - -|=== -| Constraints | Explanation -| Title -| FrontEnd: What users see -| Context -| Choosing the right web server platform involves balancing technical requirements, stakeholder preferences, user considerations, and project constraints. It's a critical decision that impacts performance, security, user experience, and project success. Achieving alignment across these factors is essential for making an informed choice. -| Decision -| JavaScript and React -| Status -| Proposed -| Consequences -| It is important that the developers are used or can get used to the proposed lenguage with ease so its easier to mantain the code and for future developers to understand it. +[options="header", cols="1,1,1,1"] |=== +| What we have to decide | Options/Proposals - Reasoning | Status | Decision - Reasoning +| Which cloud service provider to use for deploying the webapp +| *Oracle Cloud* - We have access to a VM with this provider with 24/7 free activity +| Decided +| *Oracle Cloud* - All advantages + +| Which technologies are we going to use for developing the front end +| React - It is a modern framework which is easy to learn and provides usefull predefined components that save time +| Decided +| React - We have a reference already implemented and its capabilities are what we need +|=== \ No newline at end of file