Merge pull request #41 from Arquisoft/dev

Dev

docs/src/05_building_block_view.adoc

@@ -44,169 +44,79 @@ See https://docs.arc42.org/section-5/[Building Block View] in the arc42 document
 
 [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.
+A continuación se muestra el diagrama que muestra una vista completa y genérica de lo que será la estructura de la aplicación en su entorno. Se divide en tres principales componentes que mediante interacciones detalladas en los siguientes apartados lograrán una ejecución correcta del sistema. It contains
 
 ****
 
-_**<Overview Diagram>**_
+_**Diagrama de vista general**_
 
-Motivation::
+image::05_bbv_scopecontext.jpg["Overview"]
 
-_<text explanation>_
+Motivación::
 
+La vista general de la aplicación y de su entorno es sencilla a la par que esquemática. Se observan tres componentes descriptivamente titulados: el individuo que hará uso de la aplicación (denominada "WIQ" en el diagrama) la cual a su vez recurrirá a un servicio externo, la API de WikiData, para llevar a buen puerto una serie de labores descritas en posteriores apartados. 
 
-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"]
+Bloques contenidos::
 |===
-| **Name** | **Responsibility**
-| _<black box 1>_ | _<Text>_
-| _<black box 2>_ | _<Text>_
+|Nombre|Responsabilidad
+|_WIQ_| Se trata del bloque genérico que contiene *todo* lo relativo a la aplicación que desarrollaremos.
 |===
 
 
-
-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>
+=== Level 2
+==== White Box _WIQ_
 
 [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
+En este apartado pasaré a describir en forma de "white box", bloque que en el diagrama de vista general hacía referencia a la aplicación al completo de manera genérica. En esta vista divisoria de la estructura de la aplicación ya comenzamos a distinguir componentes más concretos. 
 
+* "WebApp" es el componente con el que interactúa el usuario cuando entra en la aplicación y que trabaja con los demás componentes de este diagrama. "Users Management" se trata del microservicio encargado, como su nombre indica, del manejo de los usuarios, tanto los nuevos como los ya registrados en nuestro sistema. "Question Manager" se trata del conjunto de servicios encargado de la generación de preguntas.
 ****
 
-_<Purpose/Responsibility>_
-
-_<Interface(s)>_
+image::05_bbv_level02.jpg["Level2"]
 
-_<(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>
+|===
+|Nombre|Responsabilidad
+|Users Management|Se encarga de gestionar la autenticación de los usuarios que traten de loggearse con sus credenciales en la aplicación así como de llevar un registro de los usuarios que ya tengan sus credenciales guardadas en el sistema.
+|Question Manager|Su labor es interactuar con la API de WikiData para generar nuevas preguntas de manera dinámica así como de generar respuestas correctas e incorrectas para esas mismas cuestiones.
+|===
 
-...
 
-==== <Name interface m>
+=== Level 3
 
+image::05_bbv_level03.jpg["Level3"]
 
-
-=== Level 2
+==== White Box _Users Management_
 
 [role="arc42help"]
 ****
-Here you can specify the inner structure of (some) building blocks from level 1 as white boxes.
+Este esquema concreta la estructura interna del bloque "Users Management" que se encarga, descrito de manera rápida y locuaz, de gestionar las credenciales, fechas de registro y peticiones de login de los usuarios ya registrados y también de aquellos que traten de registrarse por primera vez en nuestra aplicación. 
 
-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
-****
+El diagrama se divide en cuatro principales componentes que interactuan de manera secuencial mediante dos principales "caminos" de ejecución teniendo siempre en común el uso de la base de datos para garantizar la persistencia de nuestro sistema.
 
-==== White Box _<building block 1>_
+|===
+|Nombre|Responsabilidad
+|Gateway Service|Servicio encargado de recibir la petición del usuario que entra en nuestra aplicación y redirigir la ejecución de la misma hacia el microservicio "user" o "authentication" según convenga.
+|User Service|Microservicio encargado de llevar el registro de los usuarios que se vayan creando durante el tiempo que la aplicación permanece desplegada así como de sus credenciales, fecha de registro...
+|Authentication Service|Microservicio encargado de la autenticación de usuarios que traten de loggearse en la aplicación basándose en las credenciales registradas en la base de datos.
+|Database|Se encarga de almacenar información de la aplicación para garantizar la persistencia de la misma (p.e: usuarios, contraseñas, registro histórico de puntuaciones...).
+|===
 
-[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
+==== White Box _Question Manager_
 
 [role="arc42help"]
 ****
-Here you can specify the inner structure of (some) building blocks from level 2 as white boxes.
+Este segundo esquema trata de describir con mayor hondura el funcionamiento interno del bloque "Question Manager". Esta funcionalidad se divide en dos microservicios y ambos interactúan directamente con la API de WikiData para extraer de este servicio externo la información trascendental y necesaria para producir nuevos interrogantes (preguntas) y nuevas respuestas a los mismos.
 
-When you need more detailed levels of your architecture please copy this
-part of arc42 for additional levels.
-****
-
-
-==== White Box <_building block x.1_>
+|===
+|Nombre|Responsabilidad
+|Create Service|Se encarga de, gracias a la interacción con la API de WikiData, generar las preguntas que vayan a presentarse al usuario durante el transcurso de la partida en curso.
+|Answer Service|Servicio encargado de, trabajando de igual manera que el servicio anterior, generar las respuestas (tanto la correcta como las incorrectas) a las preguntas planteadas por el anterior microservicio.
+|===
 
-[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>_

docs/src/10_quality_requirements.adoc

@@ -1,73 +1,65 @@
 ifndef::imagesdir[:imagesdir: ../images]
 
 [[section-quality-scenarios]]
-== Quality Requirements
+== Requisitos de Calidad
 
 
 [role="arc42help"]
 ****
 
-.Content
-This section contains all quality requirements as quality tree with scenarios. The most important ones have already been described in section 1.2. (quality goals)
+Los requisitos de calidad son la piedra angular del desarrollo de nuestro proyecto/aplicación. En ellos debemos basar nuestra implementación y es nuestra obligación a la hora de desarrollar un producto de calidad el haber garantizado el cumplimiento de la inmensa mayoría (por no decir, de todos). 
 
-Here you can also capture quality requirements with lesser priority,
-which will not create high risks when they are not fully achieved.
+* Tabla descriptiva: _(los requisitos marcados con * son aquellos dotados de mayor prioridad)_
 
-.Motivation
-Since quality requirements will have a lot of influence on architectural
-decisions you should know for every stakeholder what is really important to them,
-concrete and measurable.
-
-
-.Further Information
-
-See https://docs.arc42.org/section-10/[Quality Requirements] in the arc42 documentation.
+|===
+|Requisito de Calidad|Descripción|Escenario|
+|Usabilidad|Nuestro objetivo será tratar de garantizar que la aplicación resulte fácil de utilizar para cualquier tipo de usuario (Interfaz de usuario clara y de sencilla comprensión).|SC1|*
+|Disponibilidad|La aplicación deberá permanecer disponible en el mayor ratio de tiempo posible, proporcionando así una experiencia satisfactoria al público de la misma que pueda disfrutar de ella cuando deseen.||*
+|Seguridad|Se asegurará la protección de los datos sensibles de los usuarios así como se dará garantía de que los datos almacenados a modo de registro hisrórico de puntuaciones permanecerán inmutables. Se bloquearán los accesos no autorizados a la aplicación.||*
+|Rendimiento|Trataremos de minimizar los tiempos de respuesta por parte del sistema tratando así de garantizar la mejor experiencia por parte del usuario.|SC2|*
+|Variedad y Precisión|Las preguntas y las respuestas generadas por nuestra aplicación  deberán caracterizarse por tener la mayor precisión posible para garantizar que la respuesta correcta sea única. Además deberán abarcar diversos temas para no crear un juego de preguntas monotemáticas. |SC3|
+|Accesibilidad|Aseguraremos una experiencia satisfactoria para todo tipo de usuario por lo que nuestra aplicación pondrá especial atención a la accesibilidad de la misma, previniendo las posibles dificultades que le podrían surgir a los distintos grupos de usuarios según sus capacidades físicas y/o cognitivas. |SC4|*
+|===
 
 ****
 
 === Quality Tree
 
 [role="arc42help"]
 ****
-.Content
-The quality tree (as defined in ATAM – Architecture Tradeoff Analysis Method) with quality/evaluation scenarios as leafs.
-
-.Motivation
-The tree structure with priorities provides an overview for a sometimes large number of quality requirements.
 
-.Form
-The quality tree is a high-level overview of the quality goals and requirements:
-
-* tree-like refinement of the term "quality". Use "quality" or "usefulness" as a root
-* a mind map with quality categories as main branches
-
-In any case the tree should include links to the scenarios of the following section.
+En este apartado podemos ver de manera más visual cuáles son los requisitos de calidad representados en forma de árbol con el conocido "quality tree" (tal y como se define en ATAM - Arquitecture Tradeoff Analysis Method) que cuenta con los requisitos en forma de hojas en su diagrama.
 
+image::10_qr_tree.jpg["Quality Tree"]
 
 ****
 
 === Quality Scenarios
 
 [role="arc42help"]
 ****
-.Contents
-Concretization of (sometimes vague or implicit) quality requirements using (quality) scenarios.
 
-These scenarios describe what should happen when a stimulus arrives at the system.
+A la hora de describir los requisitos de calidad de la aplicación de generación de preguntas y respuestas que vamos a llevar a cabo es plausible que algunos de los mismos hayan sido explicados de manera excesivamente genérica. Es por esto que en este apartado vamos a mostrar algunos ejemplos más concretos para representar de una manera más comprensible lo que buscamos lograr con nuestra producto.
+
+* Cabe destacar lo que es un escenario: 
+** Un escenario describe lo que debería ocurrir cuando un determinado estímulo llega al sistema/aplicación. También cabe destacar que para los arquitectos existen dos tipos de escenarios: 
+*** Escenario de uso: Describe la reacción del sistema en tiempo real ante un estímulo.
+*** Escenario de cambio: Describe una modificación del sistema o de su entorno (p.e: Funcionalidades añadidas o cambios en los requisitos).
 
-For architects, two kinds of scenarios are important:
+. Escenarios de uso:
 
-* Usage scenarios (also called application scenarios or use case scenarios) describe the system’s runtime reaction to a certain stimulus. This also includes scenarios that describe the system’s efficiency or performance. Example: The system reacts to a user’s request within one second.
-* Change scenarios describe a modification of the system or of its immediate environment. Example: Additional functionality is implemented or requirements for a quality attribute change.
+|===
+| Id | Explicación
+| SC1 |  Un usuario nuevo podrá jugar a nuestro juego sin necesidad de que ninguno de nosotros le explique su funcionamiento.
+| SC2 | Cualquiera de las interacciones del usuario con el juego tendrá respuesta en menos de 2 segundos.
+| SC3 | A lo largo de una misma partida el usuario hará frente a preguntas de diversos temas (deportes, geografía, historia...)
+| SC4 | Un usuario con problemas de visión podrá distinguir todos los elementos de la aplicación (de la interfaz gráfica) perfectamente pudiendo jugar varias partidas y navegar por la aplicación sin problema alguno.
+|===
 
-.Motivation
-Scenarios make quality requirements concrete and allow to
-more easily measure or decide whether they are fulfilled.
+. Escenarios de cambio:
 
-Especially when you want to assess your architecture using methods like
-ATAM you need to describe your quality goals (from section 1.2)
-more precisely down to a level of scenarios that can be discussed and evaluated.
+|===
+| La incorporación de nuevos juegos dentro de la aplicación no debería afectar al sistema puesto que la manera en la que se va a implementar el juego propuesto de preguntas garantiza su flexibilidad ante el cambio y su posible extensión en un futuro.
+|===
 
-.Form
-Tabular or free form text.
 ****