Review Doc

docs/deploymentGuide.md

@@ -11,50 +11,34 @@ In our case we are going to use Azure as our cloud provider. The following steps
    - Check the public IP of the virtual machine at Azure and save it in `DEPLOY_HOST`.
 6. Once the virtual machine is created and the repository is configured, we have to create some rules for the virtual machine:
    - Open port 8000 for the gateway.
-   - Open port 80 for the webapp.
+   - Open port 443 for the webapp.
+   - Open port 9091 if you want to be able to access monitoring information.
 7. Configure the virtual machine by connecting through SSH:
-   - Use a tool for connecting to the server using SSH (example... PuTTY, MobaXterm…​).
+   - Use a tool for connecting to the server using SSH (PuTTY, MobaXterm, Bitvise,...​).
    - Use the public IP address and the file .pem for making the connection.
    - Execute the following commands for preparing the virtual machine:
 
-    ``
+    ```
     sudo apt update
-   ``
 
-   ``
     sudo apt install apt-transport-https ca-certificates curl software-properties-common
-   ``
 
-   ``
     curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
-   ``
 
-   ``
     sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu focal stable"
-   ``
 
-   ``
     sudo apt update
-   ``
 
-   ``
     sudo apt install docker-ce
-   ``
 
-   ``
     sudo usermod -aG docker ${USER}
-   ``
 
-   ``
     sudo curl -L "https://github.com/docker/compose/releases/download/1.28.5/docker-compose-$(uname -s)-$(uname -m)"
    -o /usr/local/bin/docker-compose
-   ``
-
-   ``
     sudo chmod +x /usr/local/bin/docker-compose
-    ``
+    ```
 
-9. Make a release in GitHub:
+8. Make a release in GitHub:
    - On the right-hand side of the main Code section of our repository, there is a section called Releases. It will be needed to add a new version following the version naming convention.
    - Once the release is made, some GitHub actions will be triggered, and the containers will be tested and running once everything finishes.
    - If some test fails during the process, deployment will be automatically aborted.

docs/index.adoc

@@ -34,16 +34,6 @@ include::src/about-arc42.adoc[]
 // horizontal line
 ***
 
-[role="arc42help"]
-****
-[NOTE]
-====
-This version of the template contains some help and explanations.
-It is used for familiarization with arc42 and the understanding of the concepts.
-For documentation of your own system you use better the _plain_ version.
-====
-****
-
 
 // numbering from here on
 :numbered:

docs/src/03_system_scope_and_context.adoc

@@ -57,7 +57,7 @@ image::03_business_context.png["Business Context"]
 |Communication partner|Inputs|Outputs
 | User | Interacts with WebApp by putting user credentials and answering to questions. | Receives question status (correct/incorrect) and history information about past games.
 | WebApp | User interaction by means of a graphical interface. This includes accepting the answers of questions. | Provides user information and question data including text, options and the correct answer.
-| Question Service | Accepts queries for generating questions based on size and language. | Generates the question data (text, options, images and correct answer).
+| Question Service | Accepts queries for generating questions based on size, type and language. | Generates the question data (text, options, images and correct answer).
 | Wikidata | Receives queries from the Question Service in order to generate the data of the question. | Responds to the queries with all the data of the generated question.
 |===
 
@@ -82,7 +82,7 @@ image::03_technical_context.png["Technical Context"]
 |===
 | Component | Description
 | WebApp | Accessible via the internet, allowing users to interact with the KaW application. 
-| Services | Provides access to user information and generated questions, enabling integration with external systems. Also, provides an API intreface for consulting certain information.
+| Services | Provide access to user information and generated questions, enabling integration with external systems. Also, provides an API intreface for consulting certain information.
 | Database | Stores and retrieves user data, including registration information and participation history. Also, questions can be stored for caching purposes. 
 | Wikidata | Accepts SPARQL queries and returns the requested data about questions. 
 |===

docs/src/04_solution_strategy.adoc

@@ -33,9 +33,9 @@ See https://docs.arc42.org/section-4/[Solution Strategy] in the arc42 documentat
 
 === Technologies
 
-- *React* : React will simplify the task build reusable and modular UI elements for our application thanks to its component-based structure. It'll also allow mobile app development with React Native.
+- *React* : React will simplify the task build reusable and modular UI elements for our application thanks to its component-based structure. It also allows us to use JSX, which is a syntax extension for JavaScript that allows us to write HTML elements inside our JavaScript code. This will make our code more readable and easier to debug.
 - *Express* : Web application framework for Node.js which will simplify development on the server side. There is also available a wide range of third-party middlewares that we could include on our application.
-- *TypeScript* : Since we will be using JavaScript and are more familiar with statically typed languages we will use TypeScript. This will also reduce the likelihood of some unexpected error at runtime.
+- *TypeScript* : Since we will be using JavaScript and are more familiar with statically typed languages we will use TypeScript for the services of our application. This will also reduce the likelihood of some unexpected errors at runtime.
 - *MongoDB* : We chose MongoDB since we consider we could take advantage of it's flexible schema. Its native support for JSON and its simple query language also influenced our decision. We also consider this a valauable oportunity to learn and work with a document database.
 - *Docker*: To deploy our project, Docker was chosen due to its handy portability and its perfect integration with microservices applications. 
 
@@ -50,14 +50,14 @@ each other and have its own database.
 
 - *RESTful APIs*:
 The main architecture for our Services to function as an API. Clients can communicate through
-over HTTP using standard methods such as GET to consult information like history data or
+over HTTPS using standard methods, such as GET to consult information like history data or
 generate questions using Wikidata. All these services are "masked" through a middleware so
 clients do not have to access different endpoints.
 
 - *Gateway*
 A middleware that acts as an API-frontend for clients to access various services within our system.
-This component can be also seen as a "Controller" since it receives petitions from outside, call the
-corresponding service that answers that petition and return its value.
+This component can be also seen as a "Controller" since it receives petitions from outside, calls the
+corresponding service that answers that petition and returns its value.
 
 === Decisions to Achieve Quality Goals 
 
@@ -70,9 +70,8 @@ corresponding service that answers that petition and return its value.
 
 | Performance 
 | Web-app should work smoothly and respond quickly.  
-|
-- Implementing caching mechanisms for Question generation.
-- Optimizing database queries through indexing and query optimization techniques.
+| Implementing caching mechanisms for Question generation.
+  Optimizing database queries through indexing and query optimization techniques.
 
 | Usability 
 | The application aims for user-friendly accessibility with an intuitive design. 

docs/src/07_deployment_view.adoc

@@ -132,7 +132,7 @@ flowchart TD
         end
     end
 
-    User-."Web browser : port 3000".->container1
+    User-."Web browser : port 443".->container1
     api-."REST request : port 8000".->container2
     container1-."send request : port 8000".->container2
 
@@ -171,7 +171,7 @@ Quality and/or Performance Features::
 
 Mapping of Building Blocks to Infrastructure::
 
-    The web app, gateway, and services are all contained within Docker containers, which are hosted on a server. The server is responsible for hosting the Docker containers and communicating with Wikidata to retrieve questions. The gateway is responsible for interfacing with the web app and the services, while the services are responsible for managing the user’s data and generating questions.
+    The Web App, gateway, and services are all contained within Docker containers, which are hosted on a server. The server is responsible for hosting the Docker containers and communicating with Wikidata to retrieve questions. The gateway is responsible for interfacing with the web app and the services, while the services are responsible for managing the user’s data and generating questions.
 
 [cols="2,7"]
 |===

docs/src/08_concepts.adoc

@@ -63,15 +63,15 @@ One of the things to increase accesibility is giving our application the
 capability of beign in various languages so people around the world can play
 our game. Obviously, internationalization is more than just changing the 
 language of the Application but due to time constraints we will just offer 
-Spanish, English and French languages ( although, our API can generate questions
+Spanish, English, Ukrainian and French languages ( although, our API can generate questions
 in other languages different from described, to see the whole list, refer to 
 our https://kawgame.xyz:8000/[API documentation] ).
 
 The library used for language translation in our KaW game is called 
 https://react.i18next.com/[*react-i18next*]. 
 For simplicity (and due to just only having three languages), all of the translations
 of messages are stored locally in properties files. Eventually, if the Application
-grows and we wanted to  have more than 3 languages the best approach is to
+grows and we wanted to  have more than 4 languages the best approach is to
 store those properties in a server and let the application to request
 those on the fly. Again, for simplicity the option of having all bundle
 together in the Frontend just fits.
@@ -93,7 +93,7 @@ and avoid getting suspended.
 
 Keeping a secure website for our users is one of our main quality
 goals. For that, all the passwords stored in MongoDB are simply
-hashes so attackers cannot decypher easily. The library used
+hashes so attackers cannot decypher them easily. The library used
 in the AuthService and UserService to store or compare passwords
 is called *bcrypt*. This library provides with an easy way
 to hash passwords and keep user's data secured.
@@ -311,7 +311,7 @@ erDiagram
 | Document | Description 
 | USER 
 | Holds all the data relationed to a user registered into our game. It
-has a relation with *ONE USER_HISTORY* and *ONE USER_PROFILe* document
+has a relation with *ONE USER_HISTORY* and *ONE USER_PROFILE* document
 | USER_HISTORY
 | Holds all the records/statistics of a single user through all played games.
 | USER_PROFILE

docs/src/09_architecture_decisions.adoc

@@ -43,7 +43,7 @@ quite fast. Also, the alternative to the gateway would be to have direct connect
 .Goals of this decision
 We have chosen the microservice architecture mainly for it's better maintainability since the different microservices
 are isolated. They also have more flexibility and scalability. The gateway allows us to handle errors more easily and
-it also allows clients to use the api as a whole.
+it also allows clients to use the API as a whole.
 
 === Creating a RESTful API
 .Alternatives considered

docs/src/10_quality_requirements.adoc

@@ -147,7 +147,7 @@ The documentation should also be clear for potential new team members.
 | High
 
 | Testability
-| When new features are added to the application, new test should be performed and they should be easy to add.
+| When new features are added to the application, new tests should be performed and they should be easy to add.
 The application must be designed to facilitate testing across new scenarios.
 | High
 

docs/src/11_technical_risks.adoc

@@ -56,7 +56,7 @@ to avoid the rate limit (1000 requests/hr)
 | Risk | Description | Mitigation
 
 | Reponse times
-| Having to wait for API responses can cause serious Bottlenecks on the WebApp. Users wpuld have to wait long time for each game they want to play.
+| Having to wait for API responses can cause serious Bottlenecks on the WebApp. Users would have to wait a long time for each game they want to play.
 | The usage of asynchronus calls can be very beneficial for this risk to be mitigated.  
 
 | Deadlines