Documentation marcos

docs/src/02_architecture_constraints.adoc

@@ -33,7 +33,8 @@ See https://docs.arc42.org/section-2/[Architecture Constraints] in the arc42 doc
 |*OS/Browser Independence*        |The project must be available to the maximum amount of users feasible. That includes support for mainstream OSs (_Windows_, _Linux_, _MacOS_) and browsers. (_Chrome_, _Safari_, _Firefox_, _Edge_)
 |*Usage of _REACT_*      |The _REACT JS_ framework will be used to develop the front-end of the project.
 |*Docker*     | The application will operate within a Docker environment.
-|*Version Control*      |In order of the project to be graded adequately, it must use _GitHub_ as its version control software. The contributions of each team member and agreements reached must be easily traceable.
+|*Version Control*      |In order of the project to be graded adequately, it must use _GitHub_ as its version control system. The contributions of each team member and agreements reached must be easily traceable.
+|*Wikidata* | To generate questions, WikiData would be used as a knowledge base. Wikidata is a free and open knowledge base that can be read and edited by both humans and machines. Wikidata acts as central storage for the structured data of its sister Wikimedia projects, including Wikipedia, Wikivoyage, Wiktionary, Wikisource and others. 
 |*Continuous integration and delivery*      |The development must progress through frequent integration of small changes into the main branch. New features must be automatically deployed with ease. (In our case, using _Docker_)
 |===
 

docs/src/05_building_block_view.adoc

@@ -1,212 +1,154 @@
 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
+== Building block view
+
 
 [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>**_
+=== Level 1: Overall System's whitebox
 
-Motivation::
+[plantuml,"Level 1: Overall System's whitebox",png]
+----
+:user: -> [WIQ App] : Interacts with
+[WIQ App] <.> [WikiData] : Gets Data
+----
 
-_<text explanation>_
+==== Motivation
 
 
-Contained Building Blocks::
-_<Description of contained building block (black boxes)>_
+This level shows how the application will work internally in generaly. The client, WebApp, access to the different services provided by the microservices which make up the program.
 
-Important Interfaces::
-_<Description of important interfaces>_
+==== Contained Building Blocks
 
 [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:
-
 [cols="1,2" options="header"]
 |===
 | **Name** | **Responsibility**
-| _<black box 1>_ | _<Text>_
-| _<black box 2>_ | _<Text>_
+| _<black box 1>_ | _<Text>_
+| _<black box 2>_ | _<Text>_
 |===
-
-
-
 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 black box 1>
-
-[role="arc42help"]
-****
-Here you describe <black box 1>
-according the the following black box template:
-
-* 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
-
-****
-
-_<Purpose/Responsibility>_
-
-_<Interface(s)>_
-
-_<(Optional) Quality/Performance Characteristics>_
-
-_<(Optional) Directory/File Location>_
-
-_<(Optional) Fulfilled Requirements>_
-
-_<(optional) Open Issues/Problems/Risks>_
-
-
-
-
-==== <Name black box 2>
-
-_<black box template>_
-
-==== <Name black box n>
-
-_<black box template>_
-
-
-==== <Name interface 1>
-
-...
-
-==== <Name interface m>
-
-
-
-=== Level 2
+[options="header"]
+[cols="1,2"]
+|===
+|Name |Description
+|User
+|Client of the application which will interact with it.
+|WIQ App
+|System developed to be used by the users. The games will be based on the information obtanined from WikiData
+|WikiData
+|Service external to the application from which the application questions will be obtained. Wikidata is a collaboratively edited multilingual knowledge graph hosted by the Wikimedia Foundation.
+|===
 
 [role="arc42help"]
 ****
 Here you can specify the inner structure of (some) building blocks from level 1 as white boxes.
-
 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
 ****
 
-==== White Box _<building block 1>_
-
 [role="arc42help"]
 ****
 ...describes the internal structure of _building block 1_.
 ****
 
-_<white box template>_
-
-==== White Box _<building block 2>_
-
-
-_<white box template>_
-
-...
-
-==== White Box _<building block m>_
-
-
-_<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_>
+=== Level 2
 
 [role="arc42help"]
 ****
-Specifies the internal structure of _building block x.1_.
+Here you describe <black box 1>
+according the the following black box template:
+* 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
 ****
 
+[plantuml,"Level 2:general structure of a system",png]
+----
+:usuario:
+package "WIQ App" {
+:usuario: -> [WebApp] : interacts
+[WebApp] <---> [Questions Service] : Get data
+[WebApp] <---> [Game Service] : Plays
+[WebApp] <--> [Question Historic Service] : Store/load data
+[WebApp] <--> [User Statistics Service] : Store/load data
+[WebApp] <-> [Authentification Service] : logs in / Register
+}
 
-_<white box template>_
-
+[Questions Service] <..> [WikiData] : Get data
+----
 
-==== White Box <_building block x.2_>
+==== Motivation
 
-_<white box template>_
+*_WiQ_* application is the general structure of a system in which users will have the possibility to play a video game implementation of the popular RTVE programme, "Saber y Ganar". 
 
+==== Contained Building Blocks
 
+[options="header"]
+[cols="1,2"]
+|===
+|Name |Description
+|Web App
+|Layer in which the user will interact directly and which will connect with the different services.
+|Questions Service
+|Microservice to generate the questions used by the application from WikiData
+|Game Service
+|Microservice that implements the quiz game
+|Question Historic Service
+|Microservice that stores the generated questions for later consultation
+|User Statistics Service
+|Microservice that stores the statistics of the games played by the user.
+|Authentification Service
+|Authentication microservice that allows the user to register and log in.
+|===
 
-==== White Box <_building block y.1_>
 
-_<white box template>_