Documentation appendix

Documentation appendix

README.md

@@ -31,10 +31,11 @@ This is a base repo for the [Software Architecture course](http://arquisoft.gith
 
 ➡This repo is a basic application composed of several components.
 
-- **Gateway service**. Express service that is exposed to the public and serves as a proxy to the two previous ones.
-- **User service**. Express service that handles the insertion of new users in the system.
-- **Auth service**. Express service that handles the authentication of users.
 - **Webapp**. React web application that uses the gateway service to allow basic login and new user features.
+- **Wikidata service**.Express service for the question generation.
+- **User service**. Express service that is responsible for managing all user-related operations
+- **Gateway service**. Express service that is exposed to the public and serves as a proxy to the two previous ones.
+
 
 Both the user and auth service share a Mongo database that is accessed with mongoose.
 

docs/index.adoc

@@ -6,10 +6,11 @@
 // configure EN settings for asciidoc
 include::src/config.adoc[]
 
-= image:arc42-logo.png[arc42] Template
+= image:penguin.ico[arc42] STAP Project Documentation
 :revnumber: 8.2 EN
-:revdate: January 2023
+:revdate: April 2024
 :revremark: (based upon AsciiDoc version)
+:toc: left 
 // toc-title definition MUST follow document title without blank line!
 :toc-title: Table of Contents
 
@@ -29,22 +30,6 @@ ifdef::backend-html5[]
 endif::backend-html5[]
 
 
-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:
 
@@ -96,4 +81,7 @@ include::src/11_technical_risks.adoc[]
 // 12. Glossary
 include::src/12_glossary.adoc[]
 
+<<<<
+// 13. Appendix I
+include::src/13_appendix1.adoc[]
 

docs/src/01_introduction_and_goals.adoc

@@ -3,7 +3,7 @@ ifndef::imagesdir[:imagesdir: ../images]
 [[section-introduction-and-goals]]
 == Introduction and Goals
 
-The STAP (are you Smarter Than A Penguin) web application is developed for RTVE to create an experimental version of the 'Saber y Ganar' quiz show. 
+The STAP (Smarter Than A Penguin) web application is developed for RTVE to create an experimental version of the 'Saber y Ganar' quiz show. 
 The primary goal of STAP is to provide users with an engaging platform where they can participate in quiz games,
 answer questions generated from Wikidata, and win prizes.
 

docs/src/02_architecture_constraints.adoc

@@ -3,15 +3,15 @@ ifndef::imagesdir[:imagesdir: ../images]
 [[section-architecture-constraints]]
 == Architecture Constraints
 
-When designing the WIQ application, there are several constraints that must be taken into consideration, as they will have a significant impact on the overall design of the application and the architectural decisions. These constraints must be considered in order to ensure that the final product meets the needs and expectations of the users and stakeholders. The following table summarizes these constraints and provides a brief explanation for each one divided into technical, organizational and political constraints.
+When designing the STAP application, there are several constraints that must be taken into consideration, as they will have a significant impact on the overall design of the application and the architectural decisions. These constraints must be considered in order to ensure that the final product meets the needs and expectations of the users and stakeholders. The following table summarizes these constraints and provides a brief explanation for each one divided into technical, organizational and political constraints.
 
 === Technical constraints
 
 [options="header"]
 |===
 |Constraint|Explanation
 | WikiData | Our application must generate questions automatically getting data from WikiData 
-| Version control and monitoring (GitHub) | For the WIQ application, GitHub is a useful tool for version control and collaboration among the team members working on the project. It allows easier coordination and organization of the development process, as well as keeping track of changes and contributions made by each team member. 
+| Version control and monitoring (GitHub) | For the STAP application, GitHub is a useful tool for version control and collaboration among the team members working on the project. It allows easier coordination and organization of the development process, as well as keeping track of changes and contributions made by each team member. 
 | User Experience | The design of the application must make its use friendly and easy 
 | Test coverage | Code must meet a good test quality and coverage to ensure the expected outcome.
 |===

docs/src/03_system_scope_and_context.adoc

@@ -46,19 +46,30 @@ All kinds of diagrams that show the system as a black box and specify the domain
 Alternatively (or additionally) you can use a table.
 The title of the table is the name of your system, the three columns contain the name of the communication partner, the inputs, and the outputs.
 
+
+
+
 ****
 
-image::03_business_context.png["Business Context Diagram"]
 
-[cols="1,1,1", options="header"]
-|===
-| **Partner** | **Input** | **Output**
-| User  | The user interacts with the WIQ web application using the front-end of the application. | The display of a page of the application with the questions and statistics.
-| Database | Stores relevant information of the application (users, number of games, questions passed/failed, times…). | Retrieves the information that the application requires.
-| Question generation | Questions generated from Wikidata. | These generated questions are sent to the application.
-| Wikidata API | Receives a query linked to the question to be asked. | Returns the necessary information to formulate the question.
-|===
 
+[plantuml, format=png]
+....
+title Business Context
+left to right direction
+
+
+actor user as "Player"
+rectangle STAP as "STAP System"  
+cloud Wikidata as "Wikidata API"
+
+user -- STAP
+STAP -- Wikidata
+....
+
+* *Player* (user): The user interacts with the STAP web application using the front-end of the application.
+* *STAP System* (core system): System that allows the players to play question games based on information from the wikidata api
+* *Wikidata API* (external system): Api which exposes the information stored in wikidata database
 
 === Technical Context
 
@@ -81,29 +92,55 @@ together with a mapping table showing the relationships between channels and inp
 |===
 | **Component** | **Technologies Used**
 | Front-end      | HTML, CSS (Tailwind), JavaScript (React)
-| Back-end       | node.js (Express), Wikidata's API
+| Backend       | node.js (Express), Wikidata's API
 | Database  | MongoDB
 | Arquitechture | Microservices
 | Deployment and Maintenance | Docker
 |===
 
 
 .Diagram of the Technical Context
-image::3_2-Technical-Context-Diagram-EN.png["Technical Context"]
+[plantuml, format="png"]
+----
+@startuml
+title Technical Context
+left to right direction
+
+
+' Define components as rectangles without default stereotypes
+actor "User" as User
+rectangle "WebApp" as WebApp
+rectangle "Gateway" as Gateway
+rectangle "User Service" as Users
+database "Database" as Db
+rectangle "Wikidata Service" as WikidataService
+cloud "Wikidata" as Wikidata
+
+
+' Define connections
+User --> WebApp :http
+WebApp --> Gateway
+Gateway --> Users :axios
+Users --> Db :mongoose
+Gateway --> WikidataService :axios
+WikidataService --> Wikidata
+
+@enduml
+----
 
 
 .Mapping Input/Output to Channels
 [cols="2,2", options="header"]
 |===
 | **Component** | **Functionality**
 | Front-end | User interaction and results display.
-| Back-end | Logical processing, communication with external API and database.
+| Backend | Logical processing, communication with external API and database.
 | Database | Data storage.
 | External API | Data query from Wikidata.
 |===
 
 In this flow:
 - The user interacts with the user interface (front-end) through clicks and responses.
-- The back-end processes the requests, consults the Wikidata API, and updates the screen.
+- The Backend processes the requests, consults the Wikidata API, and updates the screen.
 - The channels are the HTTP connections between the components.
 - The mapping evaluates the user’s responses in real time to provide an appropriate response. 

docs/src/04_solution_strategy.adoc

@@ -34,7 +34,7 @@ See https://docs.arc42.org/section-4/[Solution Strategy] in the arc42 documentat
 === Technologies
 * *React*: JavaScript library for web and native user interfaces. It allows developers to create interactive web applications by breaking down the UI into reusable components. React uses a declarative approach to efficiently update and render components, resulting in faster and more maintainable code. It's widely adopted in the industry due to its simplicity, performance, and robustness.
 * *Node.js*: JavaScript runtime that enables running JavaScript code outside of web browsers. It's renowned for its event-driven architecture and extensive collection of packages, making it ideal for building scalable server-side applications.
-    + *Express.js*: Express.js, often simply called Express, is a minimalist web application framework for Node.js. It simplifies the process of building web applications by providing a robust set of features, including middleware support, routing, and templating engines. Express is known for its flexibility, simplicity, and performance, making it a popular choice for developing web applications and APIs in Node.js.
+    ** *Express.js*: Express.js, often simply called Express, is a minimalist web application framework for Node.js. It simplifies the process of building web applications by providing a robust set of features, including middleware support, routing, and templating engines. Express is known for its flexibility, simplicity, and performance, making it a popular choice for developing web applications and APIs in Node.js.
 * *Wikidata*: Wikidata provides a REST API for retrieving information related to any topic. It helps us to dynamically generate questions for our game using it from any programming language. 
 * *MongoDB*: popular NoSQL database known for its flexibility and scalability. It stores data in flexible JSON-like documents and is widely used in modern web development for its simplicity and ability to handle large volumes of data.
 * *SonarCloud*: Cloud-based service provided by SonarSource, which offers continuous code quality analysis and automated code reviews for software development projects. It helps developers identify and fix bugs, security vulnerabilities, and code smells in their codebase to improve overall software quality.
@@ -45,6 +45,9 @@ See https://docs.arc42.org/section-4/[Solution Strategy] in the arc42 documentat
 * *Gatling*: Load test tool that allows us to record some user interaction from our application and simulate it as if various differnet users were accessing the application.
 * *Prometheus*: monitoring and alerting toolkit designed for reliability and scalability. It collects metrics from configured targets at specified intervals, stores them efficiently, and provides a powerful query language for analyzing and alerting on these metrics. It's particularly well-suited for dynamic environments like cloud-native applications and microservices architectures.
 * *Grafana*: open-source platform for monitoring and observability, providing customizable dashboards and visualization tools for analyzing metrics, logs, and other data sources. It allows users to create dynamic, interactive dashboards to monitor the health and performance of their systems and applications.
+* *Azure*: Cloud computing service used for creating virtual machines and running Docker containers. Azure provides a scalable and flexible infrastructure for hosting our microservices-based application, ensuring high availability and reliability.
+* *GitHub*: Version control and project management platform used for managing our game project. GitHub provides features for collaboration, issue tracking, and code review, facilitating efficient development workflows and team communication.
+* *Tailwind CSS*: Utility-first CSS framework for creating custom designs without having to write CSS from scratch. Tailwind CSS offers a set of pre-defined utility classes that can be applied directly in HTML markup, enabling rapid development and consistent styling across the application.
 
 === Technological decisions
 
@@ -53,12 +56,31 @@ As part of continuous integration, the application was attempted to be deployed
 Therefore, the team decided to migrate the whole API to Node.js using javascript and express framework.
 As a conclusion, it was worth spending time making the migration for reducing the number of potential issues at deployment time.
 
+=== Solution strategy in context with quality attributes
+
+[cols="1,2,2,1" options="header"]
+|===
+| **Quality goal** | **Scenario** | **Solution approach** | **Link to Details**
+| Reliability | Ensure system stability even under high loads or failure scenarios | Perform load test and asses the system reliability as well as providing the user with correct and consistent error messages when needed | Development concepts section inside <<section-concepts>>
+| Performance | Maintain fast response times even under heavy usage | Retrieve wikidata information before hand for giving quick response times and perform load test and asses the system reliability | <<>>
+| Security | Protect sensitive data and prevent unauthorized access | Implementing encryption and a logging system | User's login inside <<section-runtime-view>>
+| Usability | Ensure the system is intuitive and easy to use | Conducting user testing, improving user interface design | Usability tests inside <<section-concepts>>
+| Portability | Enable the system to run across different platforms | Using docker containerization, adhering to standards | <<section-deployment-view>>
+| Testability | Facilitate thorough testing and validation of system functionality | Implementing automated testing frameworks, ensuring code coverage | Testing inside <<section-concepts>>
+| Availability | Ensure the system is accessible and operational when needed | Implementing monitoring, proactive maintenance, and disaster recovery plans | Monitoring with Grafana inside <<section-concepts>>
+|===
+
 === Architecture & Design
 
-* *Microservices*: is an architectural style that structures an application as a collection of loosely coupled services. Each service is independently deployable, scalable, and can be developed using different programming languages, frameworks, or databases.
-In a microservices architecture, each service typically represents a specific business function or capability and communicates with other services through well-defined APIs. This enables teams to work independently on different parts of the application, allowing us to divide the work into different teams avoiding bottlenecks during production.
-* *API Gateway*: centralized service that acts as an intermediary between clients and microservices. It serves as a single entry point for all client requests, providing various functionalities by means of routing and redirecting to the specific service in charge of that request They play a crucial role in building scalable and efficient distributed systems by abstracting away complexities and providing a unified interface for clients to interact with all available services.
-* *API*: using microservices architecture enforces us to isolate each of the microservices and create well-defined interfaces for accesing those microservices from common gateway, reducing dependencies between services and allowing them to evolve independently. Well-defined interfaces imply not only services' independance, but also team members independecance since nobody will need to wait for others for starting working themselves.  
+* *Microservices*: Our game is built using a microservices architecture, which structures the application as a collection of loosely coupled services. Each service encapsulates a specific functionality or business capability, allowing for independent development, deployment, and scaling. By adopting microservices, we promote modularity and flexibility, enabling rapid iteration and innovation.
+
+* *Containerization with Docker*: We leverage Docker containerization to package each microservice and its dependencies into lightweight, portable containers. Docker provides a consistent environment across different stages of the development lifecycle, ensuring seamless deployment and scalability. With Docker, we can easily spin up new instances of services, manage dependencies, and streamline our development and deployment workflows.
+
+* *API Gateway*: We employ an API gateway as a centralized entry point for all client requests to our microservices. The API gateway serves as a reverse proxy, routing incoming requests to the appropriate microservice based on predefined rules and policies. It provides a unified interface for clients to interact with our system, abstracting away the complexities of the underlying microservices architecture. By consolidating access through the API gateway, we enhance security, governance, and performance while simplifying client interactions.
+
+* *Scalability and Elasticity*: With our microservices architecture orchestrated with Docker, we achieve horizontal scalability and elasticity to handle fluctuations in traffic and workload. Docker's container-based approach enables us to dynamically scale individual services based on demand, ensuring optimal resource utilization and cost efficiency. Combined with automated scaling policies and monitoring, we maintain responsiveness and availability during peak usage periods.
+
+* *Observability and Monitoring*: We prioritize observability and monitoring in our architecture to gain insights into the performance, health, and behavior of our microservices. Leveraging tools such as Prometheus, Grafana, and ELK stack, we collect metrics, logs, and traces from across our infrastructure, allowing us to detect anomalies, troubleshoot issues, and optimize system performance. With comprehensive observability, we ensure reliability, maintainability, and continuous improvement of our game platform.
 
 
 === Team Organization