Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Primera versión de los puntos 7 y 8 de la documentación #43

Merged
merged 2 commits into from
Feb 19, 2024
Merged

Primera versión de los puntos 7 y 8 de la documentación #43

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f72958e
Update 07_deployment_view.adoc
AlbertoFAz Feb 19, 2024
bc7957b
Update 08_concepts.adoc
AlbertoFAz Feb 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 14 additions & 68 deletions docs/src/07_deployment_view.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,88 +7,34 @@ ifndef::imagesdir[:imagesdir: ../images]

[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):

* distribution of a system to multiple locations, environments, computers, processors, .., as well as physical connections between them
* important justifications or motivations for this deployment structure
* quality and/or performance features of this infrastructure
* 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>**_
image::Diag_Comp.jpg[align="center",title="Deployment Diagram",link="Diag_Comp.jpg]

Motivation::

_<explanation in text form>_
The system is based in microservices architecture with three independent services, each responsible for a specific aspect of the functionality. One service is the Graphic interface, this service handles the presentation layer of a web application. Another service is tasked with managing user-related functionalities. MongoDB, a NoSQL database, is used to store and manage user data efficiently. The third service utilizes Wikidata, a free open base, to automatically generate questions.

Quality and/or Performance Features::

_<explanation in text form>_
The main reason we have chosen a microservices architecture is to achieve a fast and efficient application.. The availability and efficiency of the application will be affected by Wikidata's availability, but just in the question generation moment.

Mapping of Building Blocks to Infrastructure::
_<description of the mapping>_


=== Infrastructure Level 2

[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>_

_<diagram + explanation>_

==== _<Infrastructure Element 2>_

_<diagram + explanation>_
[cols="1,2" options="header"]
|===
| **Element** | **Description**
| _Browser_ | _The browser on the user's device where they can access to the application._
| _WebApp_ | _The graphical interface through which users can interact._
| _API Gateway_ | _The API that comunicates the rest of the microservices with the graphical interface._
| _Question_Generator_ | _The microservice responsible for generating questions through Wikidata._
| _Wikidata_ | _The Wikidata API that allows us to access its information._
| _Users_ | _The microservice responsible for managing users._
| _MongoDB_ | _A NoSQL based database where we can save the user's data._
|===

...

==== _<Infrastructure Element n>_

_<diagram + explanation>_
58 changes: 6 additions & 52 deletions docs/src/08_concepts.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,65 +6,19 @@ ifndef::imagesdir[:imagesdir: ../images]

[role="arc42help"]
****
.Content
This section describes overall, principal regulations and solution ideas that are relevant in multiple parts (= cross-cutting) of your system.
Such concepts are often related to multiple building blocks.
They can include many different topics, such as

* models, especially domain models
* architecture or design patterns
* rules for using specific technology
* principal, often technical decisions of an overarching (= cross-cutting) nature
* implementation rules


.Motivation
Concepts form the basis for _conceptual integrity_ (consistency, homogeneity) of the architecture.
Thus, they are an important contribution to achieve inner qualities of your system.

Some of these concepts cannot be assigned to individual building blocks, e.g. security or safety.


.Form
The form can be varied:

* concept papers with any kind of structure
* cross-cutting model excerpts or scenarios using notations of the architecture views
* sample implementations, especially for technical concepts
* reference to typical usage of standard frameworks (e.g. using Hibernate for object/relational mapping)

.Structure
A potential (but not mandatory) structure for this section could be:

* Domain concepts
* User Experience concepts (UX)
* Safety and security concepts
* Architecture and design patterns
* "Under-the-hood"
* development concepts
* operational concepts

Note: it might be difficult to assign individual concepts to one specific topic
on this list.

image::08-Crosscutting-Concepts-Structure-EN.png["Possible topics for crosscutting concepts"]


.Further Information

See https://docs.arc42.org/section-8/[Concepts] in the arc42 documentation.
****

=== _Domain Model_

=== _<Concept 1>_

_<explanation>_
_TBD_

=== _Security_

_The communication between the application's APIs will be through the secure mode of HTTP._

=== _<Concept 2>_
=== _Privacy_

_<explanation>_
_The user's data will be stored in a MongoDb database. That implies that the information is stored securely._

...

Expand Down