Merge pull request #65 from Arquisoft/documentation

Reviewed Deliverable I Documentation
Arquisoft · Feb 22, 2024 · 44f7ac8 · 44f7ac8
2 parents 8d6fc29 + 8543468
commit 44f7ac8
Show file tree

Hide file tree

Showing 26 changed files with 169 additions and 67 deletions.
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.png b/docs/images/05_level2.png
diff --git a/docs/images/05_level2_usersManagement.png b/docs/images/05_level2_usersManagement.png
diff --git a/docs/images/05_scope_and_context.png b/docs/images/05_scope_and_context.png
diff --git a/docs/images/05_scope_context.png b/docs/images/05_scope_context.png
diff --git a/docs/images/08_domain_model.png b/docs/images/08_domain_model.png
diff --git a/docs/images/DeploymentView.png b/docs/images/DeploymentView.png
diff --git a/docs/src/01_introduction_and_goals.adoc b/docs/src/01_introduction_and_goals.adoc
@@ -1,12 +1,12 @@
 ifndef::imagesdir[:imagesdir: ../images]
 
 [[section-introduction-and-goals]]
-== Introduction and Goals (wiq_es04a)
+== Introduction and Goals
 
 [role="arc42help"]
 ****
 Describes the relevant requirements and the driving forces that software architects and development team must consider. 
-These include
+These include 
 
 * underlying business goals, 
 * essential features, 
@@ -121,9 +121,12 @@ Table with role names, person names, and their expectations with respect to the
 [options="header",cols="1,2,2"]
 |===
 |Role/Name|Contact|Expectations
-| 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.
+| Happy Software (Dev Team) |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.
+| Happy Software (Investors)|Owner and the investors.| They expect the application to work correctly and produce benefits for the company.
 | 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.
+| RTVE | Radio y Televisión Española | They expect it to be a competent application since they are the ones who invested in the project and want to promote it on their different platforms.
+| WikiData | Wikimedia Foundation | They hope, thanks to the impact of our application, to gain more relevance and visibility in order to attract more users and expand their ways of working. Additionally, their structured data and semantic web also gain relevance.
 |===
 
 
diff --git a/docs/src/03_system_scope_and_context.adoc b/docs/src/03_system_scope_and_context.adoc
@@ -72,14 +72,10 @@ together with a mapping table showing the relationships between channels and inp
 ==== System Scope
 image:03_Technical_1.png["Diagram 3.2: Techincal Context"]
 
+Other elements of the system which can be looked up in point https://arquisoft.github.io/wiq_es04a/#section-building-block-view[Point 5: Building Block View] are:
 
 - **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"]
-
-
+- **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.
 - **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
@@ -45,14 +45,14 @@ However, JavaScript was the language that adapted better to our requirements due
  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
+=== 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.
+=== Decisions on how to achieve key quality goals
+
+Quality goals are explained in detail in point 10.
 
 [options="header",cols="1,2"]
 |===

diff --git a/docs/src/05_building_block_view.adoc b/docs/src/05_building_block_view.adoc
@@ -65,7 +65,7 @@ In the best case you will get away with examples or simple signatures.
 
 ****
 
-image:05_scope_context.png["Main Build Block"]
+image:05_scope_and_context.png["Diagram 05.1: Scope And Context"]
 
 Motivation::
 
@@ -86,7 +86,7 @@ according the the following black box template:
 ****
 
 Contained Building Blocks::
-* **WIQ**: It is the main application, represented as a blackbox that will be detailed in the following decompositions. 
+* **Wikidata Infinite Quest**: It is the main application, represented as a blackbox that will be detailed in the following decompositions. 
 * **Wikidata API**: It is the external API that the system uses to generate questions and answers.
 
 === Level 1
@@ -106,19 +106,17 @@ Leave out normal, simple, boring or standardized parts of your system
 ****
 ...describes the internal structure of _building block WIQ_.
 ****
-_**Overview Diagram**_
 
-image:05_level1.png["White Box WIQ"]
+image:05_level1.png["Diagram 05.2: Level1"]
 
 Motivation::
 
 First decomposition of the system. It shows the webapp, users managament and question generator modules as blackboxes. Also displays the docs module which contains the documentation of the project.
 
 Contained Building Blocks::
-* **WebApp**: It is the main module of the application. 
-* **UsersManagement**: Handles user management.
-* **QuestionGenerationSystem**: It is responsible for the automatic generation of questions and answers using the Wikidata API.
-* **Docs**: It is the module of the project devoted to provide all the documentation of the application. It won't be decomposed any further.
+* **Web App**: It is the main module of the application. 
+* **User Management**: Handles user management.
+* **Question Generation Service**: It is responsible for the automatic generation of questions and answers using the Wikidata API.
 
 === Level 2
 
@@ -129,17 +127,14 @@ Here you can specify the inner structure of (some) building blocks from level 1
 When you need more detailed levels of your architecture please copy this
 part of arc42 for additional levels.
 ****
-
-
 ==== White Box Users Management
 
 [role="arc42help"]
 ****
 Specifies the internal structure of _building block Users Management_.
 ****
-_**Overview Diagram**_
 
-image:05_level2_usersManagement.png["White Box Users Management"]
+image:05_level2.png["Diagram 05.2: Level2"]
 
 Motivation::
 
@@ -149,7 +144,7 @@ Contained Building Blocks::
 * **Gateway Service**: Express service that is exposed to the public and serves as a proxy to the two next ones.
 * **Authentication Service**: Express service that handles the authentication of users.
 * **User Service**: Express service that handles the insertion of new users in the system.
-* **Data Base**: Pending to decide.
+* **Data Base**: MongoDB.
 
 **PENDING TO COMPLETE...**
 

diff --git a/docs/src/07_deployment_view.adoc b/docs/src/07_deployment_view.adoc
@@ -45,11 +45,13 @@ See https://docs.arc42.org/section-7/[Deployment View] in the arc42 documentatio
 We have several services deployed in a single containter using Docker Compose, this eases the deployment.
 This are the different container and their relations:
 
-- WebApp: Gets data from Gateway Service.
-- Gateway Service: Data access interface for services.
-- User Services: Manages authentication and login systems.
-- Database: Persistance system for the application.
+- WebApp: The web page. Gets data from Gateway Service.
+- Gateway Service: data access interface for services.
+- AuthService and UserService: manages authentication and login systems.
+- MongoDB: persistance system used in the application.
+- Grafana and Prometeus: code monitoring systems.
+- QuestionGenerationSystem: generates questions to use in the game.
 
 We are going to use an Azure VM to deploy all this services.
 
-image::deploymentViewMermaid.png["Deployment View"]
+image::DeploymentView.png["Deployment View"]
diff --git a/docs/src/09_architecture_decisions.adoc b/docs/src/09_architecture_decisions.adoc
@@ -39,6 +39,10 @@ The architectural decisions are completely documented in our https://github.com/
 === Team Working Methodology
 - https://github.com/Arquisoft/wiq_es04a/wiki/ADR-01-‐-Usage-of-A-Succesful-Branching-Model[ADR 01] - Usage of A Succesful Branching Model
 
-_TBD when more architecture decisions are taken_
+=== Technology
+- https://github.com/Arquisoft/wiq_es04a/wiki/ADR-02-‐-Microservices-Architecture[ADR 02] - Microservices Architecture
+- https://github.com/Arquisoft/wiq_es04a/wiki/ADR-03-‐-Frontend-in-React[ADR 03] - Front-end in React
+
+_TBC when more architecture decisions are taken_
 
 
diff --git a/docs/src/11_technical_risks.adoc b/docs/src/11_technical_risks.adoc
@@ -23,11 +23,11 @@ List of risks and/or technical debts, probably including suggested measures to m
 See https://docs.arc42.org/section-11/[Risks and Technical Debt] in the arc42 documentation.
 
 ****
-=== Technical risks 
-To assess the relevance level of the following technical risks, we will use number 1 to indicate low relevance, 2 for medium relevance, and 3 for high relevance.
+=== Risks 
+To assess the relevance level of the following risks, we will use number 1 to indicate low relevance, 2 for medium relevance, and 3 for high relevance.
 [cols="1,1,3", options="header"]
 |===
-| Technical Risk | Relevance |  Considerations
+| Risk | Relevance |  Considerations
 | Limited knowledge of certain tools or languages | 2 | A solution could be to use the tools and languages that are most well-known to the team members. Also, each member should try to learn those aspects they know less about.
 | The team has not worked together before | 1 | A suggestion could be to mantain a good communication and inform about any aspect that could affect others.
 | Being a big group | 1 | Being  many members can difficult the communication. However, if the previous suggestions are followed there should not be any problem.

diff --git a/docs/src/12_glossary.adoc b/docs/src/12_glossary.adoc
@@ -49,10 +49,6 @@ See https://docs.arc42.org/section-12/[Glossary] in the arc42 documentation.
 |Continuous Integration & Continuous Delivery
 |CI refers to the practice of automatically and frequently integrating code changes into a shared source code repository; CD is a 2 part process that refers to the integration, testing, and delivery of code changes. Continuous delivery stops short of automatic production deployment, while continuous deployment automatically releases the updates into the production environment.
 
-|PR
-|Pull Request
-|Proposal to merge a set of changes from one branch into another. In a pull request, collaborators can review and discuss the proposed set of changes before they integrate the changes into the main codebase.
-
 |WIQ
 |https://github.com/Arquisoft/wiq_es04a/discussions/19[Wikidata Infinite Quest]
 |Web application's name, where the users can register and login themselves to play different type of rounds.
@@ -79,6 +75,10 @@ See https://docs.arc42.org/section-12/[Glossary] in the arc42 documentation.
 |Popular Spanish television program that combines quiz shows with educational entertainment aired daily on La 2 of Televisión Española. The show is known for its unique format, which includes a variety of challenges and tests where contestants demonstrate their knowledge in different areas such as history, geography, science, popular culture, literature, art, among other subjects. 
 |"Saber Y Ganar"
 
+|User
+|Player who can register and then login into the app to play some of the different quizes explained around this explanation.
+|Usuario
+
 |Warm question
 |Test in which contestants' aim is to answer questions rapidly and accurately, requiring quick thinking, as questions are presented rapidly without pauses between them. Contestants strive to provide correct answers to accumulate points, but they must also carefully assess the risk of answering incorrectly, which could lead to losing points.
 |Pregunta caliente
@@ -106,10 +106,6 @@ See https://docs.arc42.org/section-12/[Glossary] in the arc42 documentation.
 |Lightweight, portable, and self-contained unit that packages together all the necessary software components, such as code, runtime, libraries, and dependencies, needed to run an application. Containers provide a consistent environment for running applications across different computing environments.
 |Contenedor
 
-|Docker
-|Docker is a popular platform used for developing, shipping, and running applications within containers providing a way to automate the deployment of those applications using a client-server architecture.
-|_N/A_
-
 |Frontend
 |Part of a software application or website that users interact with directly. It encompasses the user interface (UI) and user experience (UX) components that users see and interact with in their web browsers or on their devices. This includes elements such as buttons, forms, menus, and any visual or interactive elements users interact with to use the application.
 |_N/A_
@@ -118,22 +114,10 @@ See https://docs.arc42.org/section-12/[Glossary] in the arc42 documentation.
 |Free and open-source version control system used for tracking changes in source code during software development. It allows multiple developers to collaborate on projects simultaneously and efficiently manage changes to the codebase.
 |_N/A_
 
-|Github
-|Online software development platform built around Git used for storing, tracking, and collaborating on software projects. It makes it easy for developers to share code files and collaborate with fellow developers on open-source projects.
-|_N/A_
-
-|Internationalization
-|Process of designing and developing a software application in such a way that it can easily adapt to different languages, cultures, and regions of the world. This involves for example the application's ability to handle different sets of characters, date and time formats, units of measurement, and other cultural and linguistic aspects.
-|Internacionalización
-
 |Microservice
 |Software architectural style that structures an application as a collection of loosely coupled services; each service is designed to perform a specific and narrowly defined function within the application. These services are typically small, independently deployable, and can be developed, tested, and deployed separately from the rest of the application.
 |Microservicio
 
-|User
-|Typically refers to an individual or entity that interacts with the system or software to perform tasks, access resources, or obtain information. Users can interact with computer systems through various means, such as graphical user interfaces, command-line interfaces, or the mentioned APIs.
-|Usuario
-
 |Wikidata
 |Free and open knowledge base that acts as a central storage repository for structured data from Wikimedia projects and beyond. It provides a common platform for collecting and sharing structured data about various topics, including but not limited to, people, places, events, concepts, and objects.
 |_N/A_

diff --git a/docs/src_mermaid/03_Business_1 b/docs/src_mermaid/03_Business_1
@@ -1,8 +1,6 @@
-flowchart TD
-    el1[User] -.->|Interacts with| sis1(WIQ Webapp)
-    subgraph WIQ
-    sis1 --> |Authenticate| sis2(Gateway Service)
-    sis1 --> |Create user| sis2
-    sis1 --> |Get questions| sis5(Question Generation Service)
+flowchart LR
+    el1[User] -.-> sis1(WIQ)
+    subgraph System
+    sis1
     end
-    sis5 -.-> D[Wikidata]
+    sis1 -.-> el2[Wikidata]
diff --git a/docs/src_mermaid/05_level1 b/docs/src_mermaid/05_level1
@@ -0,0 +1,8 @@
+flowchart TD
+    subgraph Whitebox Wikidata Infinite Quest
+    sis1(Web App) -.->|Get questions| sis2(Question Generation Service)
+    sis1 -.->|Authenticate| sis3(Users Management)
+    sis1 -.->|Create user| sis3
+    end
+    el1(User) -.->|Interacts with| sis1
+    sis2 -.-> sis4(Wikidata)
diff --git a/docs/src_mermaid/05_level2 b/docs/src_mermaid/05_level2
@@ -0,0 +1,8 @@
+flowchart TD
+    subgraph Whitebox Users Management
+    sis1(Gateway Service) -.->|Log in validation| sis2(Authentication Service)
+    sis1 -.->|Sing up user| sis3(User Service)
+    sis3 -.-> db1[(MongoDB)]
+    sis2 -.-> db1
+    end
+    sis4(Web App) -.-> sis1
diff --git a/docs/src_mermaid/05_scope_and_context b/docs/src_mermaid/05_scope_and_context
@@ -0,0 +1,5 @@
+flowchart TD
+    subgraph Scope And Context
+    el1(User) -.->|Interacts with| sis1(Wikidata Infinite Quest)
+    sis1 -.-> sis2(Wikidata)
+    end
diff --git a/docs/src_mermaid/06_login b/docs/src_mermaid/06_login
@@ -0,0 +1,13 @@
+sequenceDiagram
+    User ->>+ App: click login link
+    App -->>- User: show login view
+    User ->>+ App: click login button
+    App ->> Gateway Service: loginUser()
+    Gateway Service ->> User Service: post('/login')
+
+    User Service ->> Database: validateRequiredFields()
+    Database -->> User Service: 
+
+    User Service -->> Gateway Service: 
+    Gateway Service -->> App: 
+    App -->>- User: 
diff --git a/docs/src_mermaid/06_register b/docs/src_mermaid/06_register
@@ -0,0 +1,13 @@
+sequenceDiagram
+    User ->>+ App: click register link
+    App -->>- User: show register view
+    User ->>+ App: click add user button
+    App ->> Gateway Service: addUser()
+    Gateway Service ->> Auth Service: post('/addUser')
+
+    Auth Service ->> Database: validateRequiredFields()
+    Database -->> Auth Service: 
+
+    Auth Service -->> Gateway Service: 
+    Gateway Service -->> App: 
+    App -->>- User: 
diff --git a/docs/src_mermaid/07_Deployment_View_1 b/docs/src_mermaid/07_Deployment_View_1
@@ -0,0 +1,72 @@
+'''
+@startuml
+
+
+title Deployment Diagram
+
+!theme vibrant
+
+left to right direction
+node AzureServer{    
+
+
+    node DockerContainer1 {
+        component MongoDB
+    } 
+
+  node DockerContainer2 {
+        component AuthService
+    }   
+
+
+  node DockerContainer3{
+        component UserService
+    }   
+
+ node DockerContainer7{
+        component GatewayService
+    }
+
+ node DockerContainer4 {
+        component WebApp
+    }   
+
+node DockerContainer8{
+        component QuestionGenerationSystem
+    }
+
+
+
+
+
+ node DockerContainer5{
+        component Grafana
+    }   
+
+  node DockerContainer6{
+        component Prometheus
+    }   
+
+}
+
+node Wikidata{
+
+    }
+
+node UserDevice {
+    node WebBrowser {
+    }
+
+
+
+Actor User
+
+}
+
+User -l-> WebBrowser : "uses"
+
+
+WebApp -d-> WebBrowser : "shows on user device"
+QuestionGenerationSystem -d-> Wikidata : "Fetches data"
+@enduml
+'''