Skip to content

Commit

Permalink
Merge pull request #37 from Arquisoft/doc05_builiding_block_view
Browse files Browse the repository at this point in the history 
Doc05 builiding block view
  • Loading branch information
@uo289097
uo289097 authored Feb 18, 2024
2 parents 68fb4ca + 146b257 commit f453af2
Showing 1 changed file with 96 additions and 158 deletions.
254 changes: 96 additions & 158 deletions docs/src/05_building_block_view.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,211 +2,149 @@ ifndef::imagesdir[:imagesdir: ../images]

[[section-building-block-view]]


== Building Block View

[role="arc42help"]
****
.Content
The building block view shows the static decomposition of the system into building blocks (modules, components, subsystems, classes, interfaces, packages, libraries, frameworks, layers, partitions, tiers, functions, macros, operations, data structures, ...) as well as their dependencies (relationships, associations, ...)
This view is mandatory for every architecture documentation.
In analogy to a house this is the _floor plan_.
.Motivation
Maintain an overview of your source code by making its structure understandable through
abstraction.
This allows you to communicate with your stakeholder on an abstract level without disclosing implementation details.
.Form
The building block view is a hierarchical collection of black boxes and white boxes
(see figure below) and their descriptions.
image::05_building_blocks-EN.png["Hierarchy of building blocks"]
*Level 1* is the white box description of the overall system together with black
box descriptions of all contained building blocks.
*Level 2* zooms into some building blocks of level 1.
Thus it contains the white box description of selected building blocks of level 1, together with black box descriptions of their internal building blocks.
*Level 3* zooms into selected building blocks of level 2, and so on.
.Further Information
See https://docs.arc42.org/section-5/[Building Block View] in the arc42 documentation.
****

=== Whitebox Overall System

[role="arc42help"]
****
Here you describe the decomposition of the overall system using the following white box template. It contains
* an overview diagram
* a motivation for the decomposition
* black box descriptions of the contained building blocks. For these we offer you alternatives:
** use _one_ table for a short and pragmatic overview of all contained building blocks and their interfaces
** use a list of black box descriptions of the building blocks according to the black box template (see below).
Depending on your choice of tool this list could be sub-chapters (in text files), sub-pages (in a Wiki) or nested elements (in a modeling tool).
* (optional:) important interfaces, that are not explained in the black box templates of a building block, but are very important for understanding the white box.
Since there are so many ways to specify interfaces why do not provide a specific template for them.
In the worst case you have to specify and describe syntax, semantics, protocols, error handling,
restrictions, versions, qualities, necessary compatibilities and many things more.
In the best case you will get away with examples or simple signatures.
****

_**<Overview Diagram>**_

Motivation::

_<text explanation>_
=== Level 1: Whitebox of the Overall System

[plantuml, "level1", png]

Contained Building Blocks::
_<Description of contained building block (black boxes)>_
----
Important Interfaces::
_<Description of important interfaces>_
Actor User
Component WIQ
Component Wikidata
User -right-> WIQ: interacts with
WIQ -right-> Wikidata: receives data
Wikidata -right..> WIQ
[role="arc42help"]
****
Insert your explanations of black boxes from level 1:
----

If you use tabular form you will only describe your black boxes with name and
responsibility according to the following schema:
==== Motivation

[cols="1,2" options="header"]
|===
| **Name** | **Responsibility**
| _<black box 1>_ | _<Text>_
| _<black box 2>_ | _<Text>_
|===
*_WIQ_* application is the general structure of a system in which users will have the possibility to play a game like _Saber y Ganar_ and compare their results with their friends.

==== Contained building blocks

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

If you use a list of black box descriptions then you fill in a separate black box template for every important building block .
Its headline is the name of the black box.
****
| Name | Description

| *_User_*
| Client of the application which will interact with it.

==== <Name black box 1>
| *_WIQ_*
| System developed to be used by the users.

[role="arc42help"]
****
Here you describe <black box 1>
according the the following black box template:
| *_WIKIDATA_*
| Aplication to generate the questions and answers.

* Purpose/Responsibility
* Interface(s), when they are not extracted as separate paragraphs. This interfaces may include qualities and performance characteristics.
* (Optional) Quality-/Performance characteristics of the black box, e.g.availability, run time behavior, ....
* (Optional) directory/file location
* (Optional) Fulfilled requirements (if you need traceability to requirements).
* (Optional) Open issues/problems/risks
|===

****
=== Level 2
[plantuml, "level2", png]
----
Actor User
Component WIQ {
Component ui as "User Interface"
Component ms as "MicroService"
Database db as "MongoDB"
}
_<Purpose/Responsibility>_
Component wd as "WikiData"
_<Interface(s)>_
User -> ui: Interacts
ui -> ms: Sends requests
ms <-> db: Reads
wd -> ms: Gives data
----
==== Motivation

_<(Optional) Quality/Performance Characteristics>_
Shows how the application will work internally. The user, through the user interface, will use microservices to access the different modules with the help of the database.

_<(Optional) Directory/File Location>_
==== Contained building blocks

_<(Optional) Fulfilled Requirements>_
[options="header",cols="1,2"]
|===

_<(optional) Open Issues/Problems/Risks>_
| Name | Description

| *_User Interface_*
| The user will interact with the UI.

| *_Microservices_*
| It is the backend of the UI, formed by different modules.

| *_DataBase_*
| MongoDB is the chosen NoSQL database management system. It stores all the information necessary for the proper functioning of the application.

==== <Name black box 2>
|===

_<black box template>_
=== Level 3
[plantuml, "level3", png]
----
Component WIQ {
==== <Name black box n>
Component ms as "MicroServices" {
Component users as "Users Service"
Component question as "Question Service"
Component game as "Game Service"
Component ranking as "ranking"
Component history as "History"
Database db as "MongoDB"
}
_<black box template>_
Component ui as "User Interface"
==== <Name interface 1>
ui --> users
ui --> game
ui --> history
ui --> ranking
...
==== <Name interface m>
users <-down-> db
game <-down-> db
ranking <-down-> db
history <-down-> db
}
Component wd as "Wikidata"
=== Level 2
game --> question: generates question
question <-> wd: ask and answer the question
----
==== Motivation

[role="arc42help"]
****
Here you can specify the inner structure of (some) building blocks from level 1 as white boxes.
Detailed structure of the system. Focused on the components of the _User Interface_ and _Data Access_.

You have to decide which building blocks of your system are important enough to justify such a detailed description.
Please prefer relevance over completeness. Specify important, surprising, risky, complex or volatile building blocks.
Leave out normal, simple, boring or standardized parts of your system
****
==== Contained Building Blocks

==== White Box _<building block 1>_
[options="header",cols="1,5"]
|===

[role="arc42help"]
****
...describes the internal structure of _building block 1_.
****
| Name | Description

_<white box template>_
| *_Game_*
| Game screen where the user can play the game.

==== White Box _<building block 2>_
| *_Ranking_*
| It contains the best scores recorded in the game, including the user's highest score and the scores of other users belonging to their group.

| *_History_*
| Contains all user participations with the number of games played, correct/incorrect answers, and times.

_<white box template>_
| *_About_*
| Contains important information about the project, like the development method, the developers and how to contact them.

...
| *_Users Service_*
| Allows the client to create a new account for the application, log in and log out.

==== White Box _<building block m>_
| *_Question service_*
| Allows to ask him questions and receive the answers of them.


_<white box template>_



=== Level 3
|===

[role="arc42help"]
****
Here you can specify the inner structure of (some) building blocks from level 2 as white boxes.
When you need more detailed levels of your architecture please copy this
part of arc42 for additional levels.
****


==== White Box <_building block x.1_>

[role="arc42help"]
****
Specifies the internal structure of _building block x.1_.
****


_<white box template>_


==== White Box <_building block x.2_>

_<white box template>_



==== White Box <_building block y.1_>

_<white box template>_

0 comments on commit f453af2

Please sign in to comment.