Merge pull request #48 from Arquisoft/documentation

Deliverable I: Documentation
Arquisoft · Feb 19, 2024 · 6c35380 · 6c35380
2 parents 26d3012 + 00af70f
commit 6c35380
Show file tree

Hide file tree

Showing 34 changed files with 454 additions and 187 deletions.
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -0,0 +1 @@
+{}
diff --git a/README.md b/README.md
@@ -1,3 +1,16 @@
+## 👨‍💻 Contributors:
+
+| Contributor | Contact |
+| ------------- | ------------- |
+| Méndez Fernández, Hugo  | <a href="https://github.com/uo288543"><img src="https://img.shields.io/badge/uo288543-Hugo Méndez-red"></a>  |
+| Barrero Cruz, Pablo   | <a href="https://github.com/PBC003"><img src="https://img.shields.io/badge/PBC003-Pablo Barrero-orange"></a>  |
+| Lago Conde, Alberto  | <a href="https://github.com/uo288245"><img src="https://img.shields.io/badge/uo288245-Alberto Lago-yellow"></a>  |
+| García-Ovies Pérez, Pablo  | <a href="https://github.com/PabloGOP"><img src="https://img.shields.io/badge/PabloGOP-Pablo García Ovies-green"></a>  |
+| Bustamante Larriet, Samuel  | <a href="https://github.com/uo289689"><img src="https://img.shields.io/badge/uo289689-Samuel Bustamante-cyan"></a>  |
+| González García, María Teresa  | <a href="https://github.com/uo288347"><img src="https://img.shields.io/badge/uo288347-María Teresa González-blue"></a>  |
+| Andina Pailos, Daniel  | <a href="https://github.com/and1na"><img src="https://img.shields.io/badge/and1na-Daniel Andina-violet"></a>  |
+
+
 # wiq_es04a
 
 [![Deploy on release](https://github.com/Arquisoft/wiq_es04a/actions/workflows/release.yml/badge.svg)](https://github.com/Arquisoft/wiq_es04a/actions/workflows/release.yml)

diff --git a/docs/README.md b/docs/README.md
@@ -32,4 +32,4 @@ The documentation will be generated under the `docs/build` directory.
 ### Documentation deployment
 If we want to deploy it to GitHub pages, so it is accessible via [https://arquisoft.github.io/wiq_es04a/](https://arquisoft.github.io/wiq_es04a/), we need to execute `npm run deploy`.
 
-If you check the `package.json` in this directory you can see how deploying is as easy as executing `gh-pages -d build`, which can be directly executed using `npm run deploy` in the docs directory. The `gh-pages` package is in charge of pushing the documentation generated directory (basically some htmls) to a special github branch called gh-pages. Everything pushed to this branch is accessible on the repository page. Note that we only want to push there the documentation. Also is important that the documentation build is not pushed to the other branches of the project.
+If you check the `package.json` in this directory you can see how deploying is as easy as executing `gh-pages -d build`, which can be directly executed using `npm run deploy` in the docs directory. The `gh-pages` package is in charge of pushing the documentation generated directory (basically some htmls) to a special github branch called gh-pages. Everything pushed to this branch is accessible on the repository page. Note that we only want to push there the documentation. Also is important that the documentation build is not pushed to the other branches of the project.
diff --git a/docs/images/03_Business_1.png b/docs/images/03_Business_1.png
diff --git a/docs/images/03_Technical_1.png b/docs/images/03_Technical_1.png
diff --git a/docs/images/03_Technical_2.png b/docs/images/03_Technical_2.png
diff --git a/docs/images/05_level1.png b/docs/images/05_level1.png
diff --git a/docs/images/05_level2_usersManagement.png b/docs/images/05_level2_usersManagement.png
diff --git a/docs/images/05_scope_context.png b/docs/images/05_scope_context.png
diff --git a/docs/images/06_login_sequence.png b/docs/images/06_login_sequence.png
diff --git a/docs/images/06_register_sequence.png b/docs/images/06_register_sequence.png
diff --git a/docs/images/08_domain_model.png b/docs/images/08_domain_model.png
diff --git a/docs/images/08_mindmap_concepts.png b/docs/images/08_mindmap_concepts.png
diff --git a/docs/images/DeploymentView.png b/docs/images/DeploymentView.png
diff --git a/docs/images/Quality_Tree.png b/docs/images/Quality_Tree.png
diff --git a/docs/images/deploymentViewMermaid.png b/docs/images/deploymentViewMermaid.png
diff --git 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] Wikidata Infinite Quest
 :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
@@ -15,6 +15,19 @@ These include
 * relevant stakeholders and their expectations
 ****
 
+The aim of this project is to create a version of the famous quiz show "Saber y Ganar". In the quiz you have to 
+answer different questions about various topics (chosing topic will be possible), winning a reward for each correct answer. 
+One of the most relevant requirement is that the questions are generated from WikiData so there will always be different questions.
+
+To do the game we are going to develop a web application that will be available to enter from any device with internet connection.
+
+Regarding quality requirements, the goal is to achieve an optimal level, especially in terms of usability,
+ maintainability, efficiency, security, and testability.
+
+The main stakeholders in the project are several. Firstly, Professor José Emilio Labra, who teaches the 
+subject. Also, the students and members of the HappySoftware development team. Lastly, potential users of 
+the application will show interest in the project, as their user experience depends on it.
+
 === Requirements Overview
 
 [role="arc42help"]
@@ -41,6 +54,17 @@ See https://docs.arc42.org/section-1/[Introduction and Goals] in the arc42 docum
 
 ****
 
+An enumeration of the requirements that the project must meet in terms of functionality can be elaborated:
+
+The application must be accessed through a web frontend.
+A record of users and their game history will be maintained.
+Both questions and answers will be generated using data collected from Wikidata, with only one of the 
+four answer options being correct.
+There will be a countdown to answer each question.
+Two APIs will exist to access information about both users and generated questions.
+Reference to the requirements source:
+https://docs.google.com/document/d/1pahOfYFY--Wi7_9bbxiKOGevB_9tOSyRm78blncgBKg/[Reference to the requirements source]
+
 === Quality Goals
 
 [role="arc42help"]
@@ -63,6 +87,15 @@ If you as an architect do not know how the quality of your work will be judged..
 A table with quality goals and concrete scenarios, ordered by priorities
 ****
 
+[options="header",cols="1,2"]
+|===
+|Quality goal|Concrete scenario
+|Usability|It must be easy to use the app, thus everybody could use it
+|Availability|The system should be available the most time possible
+|Security|The user's data must remain confidential.
+|Performance|Using the system must be as smooth as possible. Especially, the question generation must be fast.
+|===
+
 === Stakeholders
 
 [role="arc42help"]
@@ -88,6 +121,9 @@ Table with role names, person names, and their expectations with respect to the
 [options="header",cols="1,2,2"]
 |===
 |Role/Name|Contact|Expectations
-| _<Role-1>_ | _<Contact-1>_ | _<Expectation-1>_
-| _<Role-2>_ | _<Contact-2>_ | _<Expectation-2>_
+| Happy Software |Hugo Méndez Fernández, Pablo Barrero Cruz, Alberto Lago Conde, Pablo García-Ovies Pérez, Samuel Bustamante Larriet, María Teresa González García, Daniel  Andina Pailos| Students are the developers of the app. They need to do a great project to obtain a good mark.
+| Teachers | José Emilio Labra | They will qualify the proyect.
+| Users | Users of the game | They want to have fun answering questions. It must be intuitive and easy to use.
 |===
+
+
diff --git a/docs/src/02_architecture_constraints.adoc b/docs/src/02_architecture_constraints.adoc
@@ -3,7 +3,6 @@ ifndef::imagesdir[:imagesdir: ../images]
 [[section-architecture-constraints]]
 == Architecture Constraints
 
-
 [role="arc42help"]
 ****
 .Contents
@@ -19,9 +18,52 @@ If needed you can subdivide them into
 technical constraints, organizational and political constraints and
 conventions (e.g. programming or versioning guidelines, documentation or naming conventions)
 
-
 .Further Information
 
 See https://docs.arc42.org/section-2/[Architecture Constraints] in the arc42 documentation.
 
 ****
+There are various architectural constraints that affect this application. They have been divided into the following sections.
+
+=== Naming Conventions
+[options="header"]
+|===
+| Constraint | Description
+| Application name | The name of the developed application will be WIQ. We have discussed the https://github.com/Arquisoft/wiq_es04a/discussions/19[meaning of these acronyms] 
+|===
+
+=== Application Requirements
+[options="header"]
+|===
+| Constraint | Description
+| Theme | Online question and answer application. It is similar to the "Saber y Ganar" game show.
+| Question generation | Both questions and answers will be automatically generated from Wikidata.
+| Question structure | Each question will have one correct answer and multiple incorrect or distracting answers. There will be a time limit to answer each question.
+| Frontend | The system will have at least one Web frontend deployed. Access will be through the Web.
+| User management | Users can register and log in to play. Registered users can also check their participation history in the system (number of games, correct/incorrect answers, times, etc.).
+| API usage | APIs will be used to access users and generated questions information.
+| Docker | Docker will be used to deploy the application locally and remotely.
+|===
+
+=== Documentation
+[options="header"]
+|===
+| Constraint | Description
+| Use of Arc42 | The project will follow the Arc42 documentation standard.
+|===
+
+=== Organizational and Versioning Constraints
+[options="header"]
+|===
+| Constraint | Description
+| Project organization | The project is distributed in three established deliveries. Therefore, each module of the project will evolve in several versions, marked by the deliveries. At the end of these deliveries a final presentation will take place. Then, the team will explain the application.
+| Git and Github | The use of Git as a version control system and the Github platform is mandatory. The public repository will be hosted on this platform.
+|===
+
+=== Development Team Constraints
+[options="header"]
+|===
+| Constraint | Description
+| Technical and theoretical knowledge | We are not professional developers and have limited experience. Therefore, we will use tools and languages minimally known by some team members.
+| Budget | We will use free tools or services for which the University has a license.
+|===
diff --git a/docs/src/03_system_scope_and_context.adoc b/docs/src/03_system_scope_and_context.adoc
@@ -48,9 +48,10 @@ The title of the table is the name of your system, the three columns contain the
 
 ****
 
-**<Diagram or Table>**
+image:03_Business_1.png["Diagram 3.1: Business Context"]
 
-**<optionally: Explanation of external domain interfaces>**
+- **WIQ:** Overview of the whole system. Essentialy, a web application in which users will be able to register/log in, play "Saber y Ganar" and display statistics of their games.
+- **Wikidata:** Free and open knowledge base that acts as a central storage repository for structured data. Its API will be used to obtain information used in questions and answers of the application.
 
 === Technical Context
 
@@ -68,8 +69,17 @@ together with a mapping table showing the relationships between channels and inp
 
 ****
 
-**<Diagram or Table>**
+==== System Scope
+image:03_Technical_1.png["Diagram 3.2: Techincal Context"]
 
-**<optionally: Explanation of technical interfaces>**
 
-**<Mapping Input/Output to Channels>**
+- **WIQ Webapp:** Module that supports user interaction via UI _i.e._, the front-end of the whole system.
+- **Gateway Service:** Express service that is exposed to the public and serves as a proxy to the users management allowing sign up and log in.
+- **Question Generation Service**: Service that will be used internally to manage information retrival from Wikidata.
+
+==== Gateway Service System
+image:03_Technical_2.png["Diagram 3.3: Communication"]
+
+
+- **User service:** Express service that handles the insertion of new users in the system.
+- **Auth service:** Express service that handles the authentication of users.
diff --git a/docs/src/04_solution_strategy.adoc b/docs/src/04_solution_strategy.adoc
@@ -3,7 +3,6 @@ ifndef::imagesdir[:imagesdir: ../images]
 [[section-solution-strategy]]
 == Solution Strategy
 
-
 [role="arc42help"]
 ****
 .Contents
@@ -30,3 +29,46 @@ Refer to details in the following sections.
 See https://docs.arc42.org/section-4/[Solution Strategy] in the arc42 documentation.
 
 ****
+
+=== Technology decisions
+
+To develop the app we will use the following technologies:
+
+* JavaScript will be the main programming language
+* ReactJS to build the user interface
+* Docker Compose to deploy all the microservices
+* GitHub for version control
+* WikiData API to obtain question and answer information
+
+We have considered the trade-offs that belong to each technology, such as SpringBoot or PHP for the backend of the app. 
+However, JavaScript was the language that adapted better to our requirements due to the simplicity of the language and its
+ focus on agile development that can lead to faster development cycles. 
+One of the main disadvantages is that we had to learn it, because our main language is Java. 
+
+Decisions about the top-level decomposition of the system
+
+We decided to use a microservices arquitecture, having different modules for each functionality. 
+For example, we will use a microservice to generate the questions.
+
+ === Decisions on how to achieve key quality goals
+
+ Quality goals are explained in detail in point 10.
+
+[options="header",cols="1,2"]
+|===
+|Quality goal| Decisions to achieve it.
+|Usability| We are going to use real users to test the app interface and improve it according to their feedback.
+|Availability| Docker Compose will be helpful to avoid problems with the deploy of the app. In addition we will use web hosting to expose it to the internet.
+|Security| A login system with encrypted password storage will be used to protect the user data.
+|Performance| We will use the minimum required calls to the APIs to mantain the minimum time response, for example, with bulk requests.
+|===
+
+=== Relevant organizational decisions
+
+Our framework will be based on working every week with two weekly meetings, one will be held during lab time in order to assign tasks and make minor decisions.
+On the other hand, the weekend meeting will be intended for more thorough reviews as well as more significant decisions.
+
+Each assigned task will be created as an Issue in GitHub to track the progress done. In addition, we are going to use GitHub Projects to organize the workflow of the team.
+To merge the code to the develop branch we are going to use Pull Requests in order to be approved by every person of the team.
+
+