forked from Arquisoft/wiq_0
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
666598c
commit 61d0ab2
Showing
2 changed files
with
62 additions
and
241 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,212 +1,65 @@ | ||
| 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. | ||
| === Whitebox of the Overall System | ||
|
|
||
| .Further Information | ||
| [plantuml, "whitebox-overall-system", png] | ||
| ---- | ||
| actor user as "Usuario" | ||
| Component WIQ | ||
| Component Wikidata | ||
| 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>**_ | ||
| user -right-> WIQ: interactúa | ||
| WIQ <-right-> Wikidata: consulta | ||
| ---- | ||
|
|
||
| Motivation:: | ||
|
|
||
| _<text explanation>_ | ||
|
|
||
| WIQ es una aplicación Web en la que los usuarios puedan registrarse y entrar a jugar. | ||
| El juego consiste en responder una serie de preguntas de diferentes tipos y temáticas obteniendo un premio por cada pregunta acertada. | ||
| Un aspecto importante del sistema es que las preguntas serán generadas automáticamente a partir de los datos de Wikidata (https://www.wikidata.org/). | ||
|
|
||
| Contained Building Blocks:: | ||
| _<Description of contained building block (black boxes)>_ | ||
|
|
||
| Important Interfaces:: | ||
| _<Description of important interfaces>_ | ||
|
|
||
| [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>_ | ||
| | **Nombre** | **Responsabildad** | ||
| | Usuario | Interactúa con la aplicación. | ||
| | WIQ | Aplicación con la que interactúa el usuario. Se comunica con Wikidata para generar preguntas automáticamente. | ||
| | Wikidata | Base de datos colaborativa de conocimiento libre que almacena datos estructurados. | ||
| |=== | ||
|
|
||
| [plantuml, "level-1", png] | ||
|
|
||
| ---- | ||
| actor user as "Usuario" | ||
| 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> | ||
| Component web as "WebApp" { | ||
| Component front as "Frontend Web" | ||
| Component back as "Backend" | ||
| Database db as "MongoDB" | ||
| } | ||
| _<black box template>_ | ||
|
|
||
| ==== <Name black box n> | ||
|
|
||
| _<black box template>_ | ||
|
|
||
|
|
||
| ==== <Name interface 1> | ||
|
|
||
| ... | ||
|
|
||
| ==== <Name interface m> | ||
|
|
||
|
|
||
|
|
||
| === Level 2 | ||
|
|
||
| [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_> | ||
|
|
||
| [role="arc42help"] | ||
| **** | ||
| Specifies the internal structure of _building block x.1_. | ||
| **** | ||
|
|
||
|
|
||
| _<white box template>_ | ||
|
|
||
|
|
||
| ==== White Box <_building block x.2_> | ||
|
|
||
| _<white box template>_ | ||
| Component Wikidata | ||
| user <-right-> front: interactúa | ||
| front <-right-> back: interactúa | ||
| back <-right-> db: interactúa | ||
| back <-down-> Wikidata: interactúa | ||
| ---- | ||
|
|
||
| Motivation:: | ||
| Muestra los principales componentes de WIQ. | ||
|
|
||
| ==== White Box <_building block y.1_> | ||
| Contained Building Blocks:: | ||
|
|
||
| _<white box template>_ | ||
| [cols="1,2" options="header"] | ||
| |=== | ||
| | **Nombre** | **Responsabildad** | ||
| | Usuario | Interactúa con el frontend web de la aplicación. | ||
| | Frontend Web | Componente responsable de la interfaz de usuario del sistema. Proporciona acceso a las funcionalidades del sistema a través de un navegador web. | ||
| | Backend | Contiene la lógica de negocio y la gestión de datos del sistema. Expone endpoints para interactuar con los clientes a través de API. | ||
| | MongoDB | Sistema de gestión de bases de datos NoSQL, que utiliza un modelo de datos flexible basado en documentos JSON con esquemas dinámicos. | ||
| | Wikidata | Base de datos colaborativa de conocimiento libre que almacena datos estructurados. | ||
| |=== |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,65 +1,33 @@ | ||
| ifndef::imagesdir[:imagesdir: ../images] | ||
|
|
||
| [[section-runtime-view]] | ||
| == Runtime View | ||
|
|
||
| === Runtime Level 1 | ||
|
|
||
| [role="arc42help"] | ||
| **** | ||
| .Contents | ||
| The runtime view describes concrete behavior and interactions of the system’s building blocks in form of scenarios from the following areas: | ||
| * important use cases or features: how do building blocks execute them? | ||
| * interactions at critical external interfaces: how do building blocks cooperate with users and neighboring systems? | ||
| * operation and administration: launch, start-up, stop | ||
| * error and exception scenarios | ||
| Remark: The main criterion for the choice of possible scenarios (sequences, workflows) is their *architectural relevance*. It is *not* important to describe a large number of scenarios. You should rather document a representative selection. | ||
| .Motivation | ||
| You should understand how (instances of) building blocks of your system perform their job and communicate at runtime. | ||
| You will mainly capture scenarios in your documentation to communicate your architecture to stakeholders that are less willing or able to read and understand the static models (building block view, deployment view). | ||
| .Form | ||
| There are many notations for describing scenarios, e.g. | ||
| * numbered list of steps (in natural language) | ||
| * activity diagrams or flow charts | ||
| * sequence diagrams | ||
| * BPMN or EPCs (event process chains) | ||
| * state machines | ||
| * ... | ||
| ==== Registro de usuario | ||
|
|
||
| .Further Information | ||
| El registro de usuarios en la aplicación se gestiona a través del microservicio de usuario (userservice). | ||
| El usuario introduce un nombre y una contraseña y, si el usuario se crea correctamente, se muestra un mensaje de confirmación. | ||
| En caso contrario, se muestra un mensaje de error. | ||
|
|
||
| See https://docs.arc42.org/section-6/[Runtime View] in the arc42 documentation. | ||
| [plantuml, "runtime-6-1-1", svg] | ||
|
|
||
| **** | ||
|
|
||
| === <Runtime Scenario 1> | ||
| ---- | ||
| actor user as "Usuario" | ||
| participant wiq as "WIQ" | ||
| user -> wiq: Introducir usuario y contraseña | ||
| wiq --> user: Interacción visual | ||
| ---- | ||
|
|
||
| ==== Inicio de sesión | ||
|
|
||
| * _<insert runtime diagram or textual description of the scenario>_ | ||
| * _<insert description of the notable aspects of the interactions between the | ||
| building block instances depicted in this diagram.>_ | ||
| El inicio de sesión de la aplicación se gestiona a través del microservicio de autenticación (authservice). | ||
| El usuario introduce sus credenciales y, si los datos son verídicos, se muestra una vista de la aplicación con las opciones disponibles. | ||
|
|
||
| It is possible to use a sequence diagram: | ||
| [plantuml, "runtime-6-1-1", svg] | ||
|
|
||
| [plantuml,"Sequence diagram",png] | ||
| ---- | ||
| actor Alice | ||
| actor Bob | ||
| database Pod as "Bob's Pod" | ||
| Alice -> Bob: Authentication Request | ||
| Bob --> Alice: Authentication Response | ||
| Alice --> Pod: Store route | ||
| Alice -> Bob: Another authentication Request | ||
| Alice <-- Bob: another authentication Response | ||
| actor user as "Usuario" | ||
| participant wiq as "WIQ" | ||
| user -> wiq: Introducir credenciales | ||
| wiq --> user: Interacción visual | ||
| ---- | ||
|
|
||
| === <Runtime Scenario 2> | ||
|
|
||
| === ... | ||
|
|
||
| === <Runtime Scenario n> |