Skip to content

Commit

Permalink
Updating documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@UO289930
UO289930 committed Apr 29, 2024
1 parent d00556e commit d77c873
Show file tree
Hide file tree
Showing 8 changed files with 118 additions and 110 deletions.
12 changes: 8 additions & 4 deletions docs/src/01_introduction_and_goals.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,10 @@ See https://docs.arc42.org/section-1/[Introduction and Goals] in the arc42 docum
| Reliability | Ensure consistent and accurate question generation and user data management.
| Performance | Optimize system response times and capacity to handle multiple user interactions simultaneously.
| Security | Implement robust security measures to protect user data and prevent unauthorized access.
| Usability | Provide an intuitive and user-friendly interface to enhance user experience.
| Portability | Enable seamless deployment and operation across different environments and platforms.
| Testability | Facilitate comprehensive testing to ensure software correctness and identify potential issues early.
| Availability | Ensure system uptime and accessibility to meet user demands and minimize downtime.
|===


Expand Down Expand Up @@ -109,15 +113,15 @@ These stakeholders determine the extent and the level of detail of your work and
Table with role names, person names, and their expectations with respect to the architecture and its documentation.
****

[options="header",cols="1,2,2"]
[options="header",cols="1,3,2"]


|===
| Role/Name | Contact | Expectations
| Users | N/A | Intuitive and enjoyable quiz experience
| Professors | Pablo Gonzalez, Jose Labra | The well-designed web application that fulfills the requirements
| RTVE | Project Manager | Reliable and engaging platform for users
| HappySw Team | Development Team | Clear documentation and reliable system performance
| Professors | Pablo González (gonzalezgpablo@uniovi.es), Jose Emilio Labra (labra@uniovi.es) | The well-designed web application that fulfills the requirements
| RTVE | www.rtve.es | Reliable and engaging platform for users
| Development | Sergio Truébano Robles (uo289930@uniovi.es), Pedro Limeres Granado (uo282763@uniovi.es), Alberto Guerra Rodas (uo282421@uniovi.es), Ángel Macías Rodríguez (uo289362@uniovi.es), Rita Fernández-Catuxo Ortiz (uo284185@uniovi.es), Vira Terletska (uo305097@uniovi.es), Sergio Llenderrozos Piñera (uo283367@uniovi.es) | Clear documentation and reliable, performant and available system
|===


Expand Down
6 changes: 6 additions & 0 deletions docs/src/02_architecture_constraints.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@ ifndef::imagesdir[:imagesdir: ../images]
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.

=== Technical constraints

[options="header"]
|===
|Constraint|Explanation
| WikiData | Our application must generate questions automatically getting data from WikiData
Expand All @@ -15,6 +17,8 @@ When designing the WIQ application, there are several constraints that must be t
|===

=== Organizational constraints

[options="header"]
|===
|Constraint|Explanation
| Team | The project will be done in a team composed of 7 students, so work must be assigned accordingly.
Expand All @@ -24,6 +28,8 @@ When designing the WIQ application, there are several constraints that must be t
|===

=== Political constraints

[options="header"]
|===
|Constraint|Explanation
| Documentation | We are going to use AsciiDoc and follow the Arc42 template.
Expand Down
6 changes: 3 additions & 3 deletions docs/src/03_system_scope_and_context.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ The title of the table is the name of your system, the three columns contain the

image::03_business_context.png["Business Context Diagram"]

[cols="1,1,1" options="header"]
[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.
Expand All @@ -77,7 +77,7 @@ together with a mapping table showing the relationships between channels and inp
****

.Table of the Technical Context
[cols="2,2"]
[cols="2,2", options="header"]
|===
| **Component** | **Technologies Used**
| Front-end | HTML, CSS (Tailwind), JavaScript (React)
Expand All @@ -93,7 +93,7 @@ image::3_2-Technical-Context-Diagram-EN.png["Technical Context"]


.Mapping Input/Output to Channels
[cols="2,2"]
[cols="2,2", options="header"]
|===
| **Component** | **Functionality**
| Front-end | User interaction and results display.
Expand Down
5 changes: 3 additions & 2 deletions docs/src/06_runtime_view.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -55,11 +55,12 @@ collections FrontEnd
collections WikidataService
database Wikidata
User -> FrontEnd: Start Game
FrontEnd -> WikidataService: "/GetQuestions"
WikidataService-> Wikidata: Sparql query
Wikidata-> WikidataService : entitites data
WikidataService-> WikidataService: createQuestions()
User -> FrontEnd: Start Game
FrontEnd -> WikidataService: "/GetQuestions"
WikidataService-> FrontEnd: Send 10 questions
FrontEnd -> User: Question 1
User-> FrontEnd: Answer 1
Expand Down
181 changes: 90 additions & 91 deletions docs/src/07_deployment_view.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,44 @@ ifndef::imagesdir[:imagesdir: ../images]

== Deployment View

[role="arc42help"]
****
.Content
The deployment view describes:
1. technical infrastructure used to execute your system, with infrastructure elements like geographical locations, environments, computers, processors, channels and net topologies as well as other infrastructure elements and
2. mapping of (software) building blocks to that infrastructure elements.
Often systems are executed in different environments, e.g. development environment, test environment, production environment. In such cases you should document all relevant environments.
Especially document a deployment view if your software is executed as distributed system with more than one computer, processor, server or container or when you design and construct your own hardware processors and chips.
From a software perspective it is sufficient to capture only those elements of an infrastructure that are needed to show a deployment of your building blocks. Hardware architects can go beyond that and describe an infrastructure to any level of detail they need to capture.
.Motivation
Software does not run without hardware.
This underlying infrastructure can and will influence a system and/or some
cross-cutting concepts. Therefore, there is a need to know the infrastructure.
.Form
Maybe a highest level deployment diagram is already contained in section 3.2. as
technical context with your own infrastructure as ONE black box. In this section one can
zoom into this black box using additional deployment diagrams:
* UML offers deployment diagrams to express that view. Use it, probably with nested diagrams,
when your infrastructure is more complex.
* When your (hardware) stakeholders prefer other kinds of diagrams rather than a deployment diagram, let them use any kind that is able to show nodes and channels of the infrastructure.
.Further Information
See https://docs.arc42.org/section-7/[Deployment View] in the arc42 documentation.
****


Our project is configurated using GitHub actions in such a way that every release that is made will trigger some unitary and end to end test, and an attempt to deploy the application over a server.
This will allow our team to achieve continuous deployment and delivery.

Expand Down Expand Up @@ -130,6 +168,10 @@ frame Azure {
}
}
cloud WikidataDB{
}
frame GitHub{
frame GitHubActions{
Expand All @@ -145,9 +187,10 @@ frame GitHub{
WebAPP -- APIGateway : port 8000
Wikidata -- WikidataAPI: port 8001
WikidataAPI -- WikidataDB: query.wikidata.org/sparql
Users -- UsersAPI : port 8003
UsersAPI -- UsersDatabase : MongoDB (port 27017)
client -- WebAPP : Web Browser (port 80)
client -- WebAPP : Web Browser (port 3000)
GitHubActions -- UbuntuServer : on release
Docker -- wiq_en3a
Expand All @@ -156,93 +199,6 @@ Docker -- wiq_en3a

=== Infrastructure Level 1 - Azure Ubuntu Server

The Ubuntu server allows us to have a isolated machine with the minimal required configuration and installations for running our services.
Having our server on Azure, allows us to minimize the costs of having that machine running, as well as to avoid taking care of some responsabilities such as security, availability or maintainance.


=== Infrastructure Level 2 - Docker

Instead of having a virtual machine for running the whole application by itself, the application is splitted into different services that can be completely isolated.
Docker allows us to create containers with the minimum amount of resources needed for running that specific service, such that resources are not wasted and services that could be more used do not collapse others. Each container contains the specific docker image for running the specific service.
Each implemented service will be isolated at deploy time, so there is no need of making the services at the same programming language or following the same architectural patterns, and responses will be responded through different independent endpoints.

The virtual machine will contain as many containers as services in the application.

For now, the project contains:
** Web application service running on port 3000
** Gateway (middleware) service running on port 8000
** Wikidata API running on port 8001
** Users API running on port 8003
** Mongo DB server running on port 27017
** Prometheus running on port 9090 for monitoring
** Grafana running on port 9091 for analytics and monitoring


=== Infrastructure Level 3 - GitHub actions

GitHub actions will provide us with continuous automatic delivery and integration, automating the deployment phase at each release.

=== Motivation

In the deployment view of our software architecture, we delineate the physical deployment of our system components across various environments.
At the core of our deployment strategy is the utilization of cloud-based infrastructure, specifically leveraging Azure for its robustness and scalability.
Our server components, including web applications, gateway, user services, and MongoDB servers, are encapsulated within Docker containers to ensure portability and consistency across deployments.
Additionally, we employ Azure's built-in services for auto-scaling, and traffic management to optimize performance and reliability.
Continuous integration and deployment pipelines are established using tools like Jenkins or Azure DevOps, facilitating seamless updates and releases of our system components.
Monitoring and logging solutions, such as Prometheus and Grafana, are integrated to provide insights into system health and performance.
Overall, our deployment view showcases a resilient, scalable, and automated deployment architecture tailored to meet the demands of our system's evolving requirements.

=== Mapping of Building Blocks into Infrastructure

[cols="1,2" options="header"]
|===
| **Name** | **Responsibility**
| Frontend | Web App container opened in port 80.
| User Management | User service container.
| Wikidata Service | Wikidata service container.
| Gateway | API Gateway service opened in port 8000.
|===


[role="arc42help"]
****
.Content
The deployment view describes:
1. technical infrastructure used to execute your system, with infrastructure elements like geographical locations, environments, computers, processors, channels and net topologies as well as other infrastructure elements and
2. mapping of (software) building blocks to that infrastructure elements.
Often systems are executed in different environments, e.g. development environment, test environment, production environment. In such cases you should document all relevant environments.
Especially document a deployment view if your software is executed as distributed system with more than one computer, processor, server or container or when you design and construct your own hardware processors and chips.
From a software perspective it is sufficient to capture only those elements of an infrastructure that are needed to show a deployment of your building blocks. Hardware architects can go beyond that and describe an infrastructure to any level of detail they need to capture.
.Motivation
Software does not run without hardware.
This underlying infrastructure can and will influence a system and/or some
cross-cutting concepts. Therefore, there is a need to know the infrastructure.
.Form
Maybe a highest level deployment diagram is already contained in section 3.2. as
technical context with your own infrastructure as ONE black box. In this section one can
zoom into this black box using additional deployment diagrams:
* UML offers deployment diagrams to express that view. Use it, probably with nested diagrams,
when your infrastructure is more complex.
* When your (hardware) stakeholders prefer other kinds of diagrams rather than a deployment diagram, let them use any kind that is able to show nodes and channels of the infrastructure.
.Further Information
See https://docs.arc42.org/section-7/[Deployment View] in the arc42 documentation.
****

=== Infrastructure Level 1

[role="arc42help"]
****
Describe (usually in a combination of diagrams, tables, and text):
Expand All @@ -253,7 +209,6 @@ Describe (usually in a combination of diagrams, tables, and text):
* mapping of software artifacts to elements of this infrastructure
For multiple environments or alternative deployments please copy and adapt this section of arc42 for all relevant environments.
****
_**<Overview Diagram>**_
Expand All @@ -267,16 +222,20 @@ _<explanation in text form>_
Mapping of Building Blocks to Infrastructure::
_<description of the mapping>_
****

The Ubuntu server allows us to have a isolated machine with the minimal required configuration and installations for running our services.
Having our server on Azure, allows us to minimize the costs of having that machine running, as well as to avoid taking care of some responsabilities such as security, availability or maintainance.

=== Infrastructure Level 2

=== Infrastructure Level 2 - Docker

[role="arc42help"]
****
Here you can include the internal structure of (some) infrastructure elements from level 1.
Please copy the structure from level 1 for each selected element.
****
==== _<Infrastructure Element 1>_
Expand All @@ -291,5 +250,45 @@ _<diagram + explanation>_
==== _<Infrastructure Element n>_
_<diagram + explanation>_
****

Instead of having a virtual machine for running the whole application by itself, the application is splitted into different services that can be completely isolated.
Docker allows us to create containers with the minimum amount of resources needed for running that specific service, such that resources are not wasted and services that could be more used do not collapse others. Each container contains the specific docker image for running the specific service.
Each implemented service will be isolated at deploy time, so there is no need of making the services at the same programming language or following the same architectural patterns, and responses will be responded through different independent endpoints.

The virtual machine will contain as many containers as services in the application.

For now, the project contains:
** Web application service running on port 3000
** Gateway (middleware) service running on port 8000
** Wikidata API running on port 8001
** Users API running on port 8003
** Mongo DB server running on port 27017
** Prometheus running on port 9090 for monitoring
** Grafana running on port 9091 for analytics and monitoring


=== Infrastructure Level 3 - GitHub actions

GitHub actions will provide us with continuous automatic delivery and integration, automating the deployment phase at each release.

=== Motivation

In the deployment view of our software architecture, we delineate the physical deployment of our system components across various environments.
At the core of our deployment strategy is the utilization of cloud-based infrastructure, specifically leveraging Azure for its robustness and scalability.
Our server components, including web applications, gateway, user services, and MongoDB servers, are encapsulated within Docker containers to ensure portability and consistency across deployments.
Additionally, we employ Azure's built-in services for auto-scaling, and traffic management to optimize performance and reliability.
Continuous integration and deployment pipelines are established using tools like Jenkins or Azure DevOps, facilitating seamless updates and releases of our system components.
Monitoring and logging solutions, such as Prometheus and Grafana, are integrated to provide insights into system health and performance.
Overall, our deployment view showcases a resilient, scalable, and automated deployment architecture tailored to meet the demands of our system's evolving requirements.

=== Mapping of Building Blocks into Infrastructure

[cols="1,2" options="header"]
|===
| **Name** | **Responsibility**
| Frontend | Web App container opened in port 3000.
| User Management | User service container.
| Wikidata Service | Wikidata service container.
| Gateway | API Gateway service opened in port 8000.
|===
8 changes: 5 additions & 3 deletions docs/src/08_concepts.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -86,7 +86,7 @@ In our app, the question is always represent as a data structure with the next f
We decided to use a color palette of 4 colors:


[cols="1,1"]
[cols="1,1", options="header"]
|===
| Name | Color
| Background | +++<span style="color: #191919; font-weight:bold">#191919</span>+++
Expand Down Expand Up @@ -123,6 +123,8 @@ The application is deployed using Docker.
The application will not have configurable features. An early idea was to include a "dark mode".
Through the development we decided to postpone these ideas in order to focus on a better application in general.


...
==== Data access
The development team has followed two different approaches for supporting data access from the running application for development and production.
While developing the application, teh development team decided to create a shared database located in the cloud which allowed us to work locally with the same data by means of a key string.
In order to move our application into production by means of deploying it into an Azure virtual machine running with Docker containers, the development team created a mongodb container with an associated volumen for making the data persistent.

1 change: 1 addition & 0 deletions docs/src/09_architecture_decisions.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ If you want a description about each of the technologies we have chosen, go to t
The following table contains the most interesting the design decisions that we have taken with their advantages and disadvantages:

.Architectural Records
[cols="1,1,2,2", options="header"]
|===
|Code|Decision|Advantages|Disadvantages
|ADR1| React.js | Quite easy to learn in comparison to other front-end libraries. Increasingly popular in the web.| Not all of us know about its usage
Expand Down
9 changes: 2 additions & 7 deletions docs/src/10_quality_requirements.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ Tabular or free form text.

*Usage scenarios*

[options="header", cols="1,1,1,1"]
[options="header", cols="1,2,2,2"]
|===
| Quality goal | Motivation | Usage scenario | Priority

Expand Down Expand Up @@ -120,17 +120,12 @@ Tabular or free form text.

*Change scenarios*

[options="header", cols="1,1,1,1"]
[options="header", cols="1,2,2,2"]
|===
| Quality goal | Motivation | Change scenario | Priority
| *Maintainability*
| An application should be maintainable to remain usable over the years and to be able to improve functionalities and to fix misfunctionalities.
| When developers must introduce a new feature to the web, they should be able to do it without changing the software architecture.
| High

| *Maintainability*
| An application should be maintainable to remain usable over the years and to be able to improve functionalities and to fix misfunctionalities.
| When fixing errors and bugs on the system, developers should be able to do it without major consequences on the system.
| High

|===

0 comments on commit d77c873

Please sign in to comment.