Merge branch 'develop' into documentation_alejandro_liliana

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "asciidoc.antora.enableAntoraSupport": true
+}

docs/src/01_introduction_and_goals.adoc

@@ -41,6 +41,17 @@ See https://docs.arc42.org/section-1/[Introduction and Goals] in the arc42 docum
 
 ****
 
+The WIQ web application allows users to play a game similar to the one of Saber y Ganar quiz show. This game consists on answering a number of questions with different types and subjects obtaining  a prize for each question well answered. Game´s questions are automatically generated from data available in Wikidata (https://www.wikidata.org/).
+
+* The system will have at least a web front-end which will be available and accessible through the web.
+* Users will be able to register to the system and obtain the historical data from their participation: number of games, questions passed and failed, times, etc ..
+* Questions will be automatically generated from data available in Wikidata.
+* Questions have to be answered before some specific time.
+* Each question will have one right answer and several incorrect ones or distractors. Both the right answer and the distractors should be automatically generated.
+* The system will give access to the information about the users through an API.
+* The system will give access to information about the generated questions through an API.
+
+
 === Quality Goals
 
 [role="arc42help"]
@@ -62,6 +73,17 @@ If you as an architect do not know how the quality of your work will be judged..
 .Form
 A table with quality goals and concrete scenarios, ordered by priorities
 ****
+.Quality goals ordered by priority (from most to least important)
+[options="header",cols="1,3"]
+|===
+|Quality Goal|Description
+| _Satisfaction_ | _Users will not get repeated questions in at least a hundred questions._
+| _Modularity_ | _The application will be divided in modules so that a change on one component has minimal impact on other components._
+| _Testability_ | _The application should be able to go through different test and complete them successfully._
+| _Learnability_ | _Any user must be able to use the app with ease. The interface must remind the user to the one in  Saber y Ganar quiz show._
+| _Time behaviour_ | _Users will not have to wait more than 500ms to get a new question._
+|===
+
 
 === Stakeholders
 
@@ -88,6 +110,10 @@ Table with role names, person names, and their expectations with respect to the
 [options="header",cols="1,2,2"]
 |===
 |Role/Name|Contact|Expectations
-| _<Role-1>_ | _<Contact-1>_ | _<Expectation-1>_
-| _<Role-2>_ | _<Contact-2>_ | _<Expectation-2>_
+| _Professors_ | _ASW module professors_ | _Get a great project which can be evaluated and shown in their github._
+| _Developers_ | _wiq_es6c team_ | _Carrying out a full real project using all the knowledge obtained in the degree._
+| _Responsible company_ | _HappySw_ | _Development of an experimental version of the Saber y Ganar quiz show._
+| _Client_ | _RTVE_ | _Getting a Web App to promote its famous Saber y Ganar quiz show by letting their viewers enjoy a similar experience._
+| _Main beneficiaries_ | _Public users_ | _Having a great time playing an interesting and easy to use quiz game._
+| _Side beneficiaries_ | _Wikidata_ | _Obtain free promotion of their application and its ease to use in multiple projects._
 |===

docs/src/02_architecture_constraints.adoc

@@ -3,7 +3,6 @@ ifndef::imagesdir[:imagesdir: ../images]
 [[section-architecture-constraints]]
 == Architecture Constraints
 
-
 [role="arc42help"]
 ****
 .Contents
@@ -25,3 +24,42 @@ conventions (e.g. programming or versioning guidelines, documentation or naming
 See https://docs.arc42.org/section-2/[Architecture Constraints] in the arc42 documentation.
 
 ****
+
+=== Technical constraints
+
+[cols="2,4" options="header"]
+|===
+|Constraint           |Explanation
+|*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.
+|*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_)
+|===
+
+=== Organizational constraints
+
+[cols="2,7" options="header"]
+|===
+|Constraint           |Explanation
+|*Time*        |The team has to complete the project during the semester. 
+|*Team size*        |The development teams must be composed of 5-7 members. In our case, the final team is composed of 6 members.
+|*Budget*        |No budget is provided for the development, so any costs that may arise have to be covered by the development team.
+|*Deliverables*          |Along the development process, the team must prepare deliverables set for certain dates, consisting of documentation and/or application prototypes.
+|*Team meetings*          |In order to plan the development of the project, as well as to assign tasks and make design decisions, the team will participate in several meetings. These meetings can be done in and out of the classroom, as needed. A record must be created for every meeting, summarizing the progress made.
+|*Project testing*         |The development team must test acceptable coverage of the project using different methods (_unit testing_, _integration testing_, _acceptance testing_... etc.)
+|*Knowledge*        |There are many aspects of the development of this project that are foreign to some of us (usage of _REACT_, deployments, microsystems architecture... etc.) so some research is required to keep up.
+|===
+
+=== Conventions
+
+[cols="2,4" options="header"]
+|===
+|Constraint           |Explanation
+|*Use of English*        |The totality of the project must be written in English, as to facilitate its understanding internationally. 
+|*Programming Language conventions*      | We ought to follow the conventions specific to the programming languages we're employing.
+|*Documentation format*          |The documentation must adhere to the Arc42 method, ensuring it is clear, simple, and effective.
+|*Clean code*      |In order to ease the understanding and maintenance of the project, all code written must be organized, descriptive and easy to read.
+|*Accesibility*      |The application should be user-friendly, allowing all individuals to navigate effortlessly, irrespective of any disabilities, ensuring inclusivity for all users.
+|*Microservices*      | The application will be divided into microservices to facilitate its development.
+|===

docs/src/03_system_scope_and_context.adoc

@@ -3,7 +3,6 @@ ifndef::imagesdir[:imagesdir: ../images]
 [[section-system-scope-and-context]]
 == System Scope and Context
 
-
 [role="arc42help"]
 ****
 .Contents
@@ -25,10 +24,8 @@ Various options:
 .Further Information
 
 See https://docs.arc42.org/section-3/[Context and Scope] in the arc42 documentation.
-
 ****
 
-
 === Business Context
 
 [role="arc42help"]
@@ -48,9 +45,13 @@ The title of the table is the name of your system, the three columns contain the
 
 ****
 
-**<Diagram or Table>**
-
-**<optionally: Explanation of external domain interfaces>**
+[cols=3 options="header"]
+|===
+|Entity           |Input        |Output
+|*User*      | App usage and experience. | The user will introduce and send its credentials every time it creates a new account or logs into an existing one.
+|*WebApp*     | User data and input, as well as external API calls received.  | Handled API calls, sent to their respective microservice in order to be processed and answered.
+|*Wikidata*      |Calls to Wikidata's REST API asking for certain data, which will be used to construct the questions.  | Said data. Its format may vary, according to the necessities of the questions generator. 
+|===
 
 === Technical Context
 
@@ -68,8 +69,6 @@ together with a mapping table showing the relationships between channels and inp
 
 ****
 
-**<Diagram or Table>**
-
-**<optionally: Explanation of technical interfaces>**
+The following diagram represents the general structure of the project, as well as the communication channels between various system components. It shows communication to external sources, as well as communications between the various microsystems.
 
-**<Mapping Input/Output to Channels>**
+image::03-deployment-diagram-EN.png[]

docs/src/04_solution_strategy.adoc

@@ -3,30 +3,51 @@ ifndef::imagesdir[:imagesdir: ../images]
 [[section-solution-strategy]]
 == Solution Strategy
 
+=== Technology Decisions
 
-[role="arc42help"]
-****
-.Contents
-A short summary and explanation of the fundamental decisions and solution strategies, that shape system architecture. It includes
+In order to develop the application and adhere to the constraints, we selected the following technologies:
 
-* technology decisions
-* decisions about the top-level decomposition of the system, e.g. usage of an architectural pattern or design pattern
-* decisions on how to achieve key quality goals
-* relevant organizational decisions, e.g. selecting a development process or delegating certain tasks to third parties.
+- ReactJS: JavaScript library that streamlines the development of graphical interfaces for web applications.
+- TypeScript: Extension of JavaScript, bolstering it with type support for improved development.
+- GitHub: Platform offering remote repository services for project development, task management, and version control.
+- MongoDB: A non-linear database selected to oversee storage of diverse application contents, with each microservice possessing its dedicated database.
+- NodeJS: Facilitates efficient management of asynchronous events, notably beneficial for scalable network applications and database administration.
+- Docker: Employed for seamless deployment of the application environment.
 
-.Motivation
-These decisions form the cornerstones for your architecture. They are the foundation for many other detailed decisions or implementation rules.
+=== Top-level Decomposition
 
-.Form
-Keep the explanations of such key decisions short.
+==== Diagramming tools
 
-Motivate what was decided and why it was decided that way,
-based upon problem statement, quality goals and key constraints.
-Refer to details in the following sections.
+We will use PlantUML and UMLet for creating the documentation's diagrams.
 
+=== Approaches to Achieve Top Quality Goals
 
-.Further Information
+[cols="1,2,3"]
+|===
+| Quality Goal | Scenario | Solution Approach
 
-See https://docs.arc42.org/section-4/[Solution Strategy] in the arc42 documentation.
+| Privacy
+| Users seek reassurance in the safety and privacy of their data within our app.
+| Ensuring user data security and privacy within the application.
 
-****
+| Usability
+| Seamless execution of all application functions is crucial for user satisfaction.
+| Optimizing usability through the utilization of React.
+
+| Maintainability
+| Application architecture must facilitate seamless addition or modification of functionalities with minimal code changes.
+| Implementing design patterns and adhering to code conventions to ensure clean and maintainable code. Additionally, prioritizing testing during development for long-term maintainability.
+
+| Scalability
+| The application's design must accommodate changes effortlessly throughout its lifecycle.
+| Employing a microservices approach to minimize code repetition and enhance understanding of application distribution, ensuring future scalability.
+
+|===
+
+=== Organizational Decisions
+
+We've established the following organizational guidelines:
+
+- *Language*: Adhering to international standards, the project, encompassing code and documentation, will be developed in English as the primary language.
+- *Issues:* All deliberations will be documented as issues on GitHub.
+- *GitHub Projects:* Employing this tool, we'll plan the application's development process, utilizing GitHub's integrated features for efficient project management in accordance with AGILE methodology.

docs/src/06_runtime_view.adoc

@@ -87,3 +87,16 @@ Alice <-- Bob: another authentication Response
 === ...
 
 === <Runtime Scenario n>
+
+=== Wikidata questions requests
+
+[plantuml,"Sequence diagram WikidataApi",png]
+----
+actor User
+entity App
+entity WikidataApi
+User -> App: Starts a game
+App -> WikidataApi: Request data
+App <-- WikidataApi: Returns data
+User <-- App: Displays data in question-answer format
+----

docs/src/09_architecture_decisions.adoc

@@ -5,6 +5,33 @@ ifndef::imagesdir[:imagesdir: ../images]
 
 
 [role="arc42help"]
+****
+.Contents
+Important, expensive, large scale or risky architecture decisions including rationales.
+With "decisions" we mean selecting one alternative based on given criteria.
+
+Please use your judgement to decide whether an architectural decision should be documented
+here in this central section or whether you better document it locally
+(e.g. within the white box template of one building block).
+
+Avoid redundancy. 
+Refer to section 4, where you already captured the most important decisions of your architecture.
+
+.Motivation
+Stakeholders of your system should be able to comprehend and retrace your decisions.
+
+.Form
+Various options:
+
+* ADR (https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions[Documenting Architecture Decisions]) for every important decision
+* List or table, ordered by importance and consequences or:
+* more detailed in form of separate sections per decision
+
+.Further Information
+
+See https://docs.arc42.org/section-9/[Architecture Decisions] in the arc42 documentation.
+There you will find links and examples about ADR.
+
 ****
 
 [options="header",cols="1,3,3"]
@@ -24,5 +51,4 @@ ifndef::imagesdir[:imagesdir: ../images]
 |MongoDB
 |Being a non-relational database, it is easier to use. In addition, it is used by large telecommunications companies.
 |Non-relational databases are the ones with which we have the least experience.
-
-****
+|===

docs/src/10_quality_requirements.adoc

@@ -4,18 +4,77 @@ ifndef::imagesdir[:imagesdir: ../images]
 == Quality Requirements
 
 
+[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)
+
+Here you can also capture quality requirements with lesser priority,
+which will not create high risks when they are not fully achieved.
+
+.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.
+
 ****
 
 To describe the quality requirements that the game will have, we will use quality scenarios. Quality scenarios describe 
 the action to be performed by the user or the system (stimulus) in order to generate a response to the interaction.
 
+=== 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.
+
 ****
 
-=== Quality Tree
 image::QualityTree.png[]
 
 === 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.
+
+For architects, two kinds of scenarios are important:
+
+* 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.
+
+.Motivation
+Scenarios make quality requirements concrete and allow to
+more easily measure or decide whether they are fulfilled.
+
+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.
+
+.Form
+Tabular or free form text.
+****
+
 Quality scenarios, also known as use cases, are detailed descriptions of situations in which a user interacts with 
 a system and describe the expected outcomes along with the conditions of the environment in which the interaction 
 occurs.

docs/src/11_technical_risks.adoc

@@ -5,6 +5,23 @@ ifndef::imagesdir[:imagesdir: ../images]
 
 
 [role="arc42help"]
+****
+.Contents
+A list of identified technical risks or technical debts, ordered by priority
+
+.Motivation
+“Risk management is project management for grown-ups” (Tim Lister, Atlantic Systems Guild.) 
+
+This should be your motto for systematic detection and evaluation of risks and technical debts in the architecture, which will be needed by management stakeholders (e.g. project managers, product owners) as part of the overall risk analysis and measurement planning.
+
+.Form
+List of risks and/or technical debts, probably including suggested measures to minimize, mitigate or avoid risks or reduce technical debts.
+
+
+.Further Information
+
+See https://docs.arc42.org/section-11/[Risks and Technical Debt] in the arc42 documentation.
+
 ****
 
 [options="header"]
@@ -13,6 +30,4 @@ ifndef::imagesdir[:imagesdir: ../images]
 
 |Knowledge of REACT         |It is a framework that no team member has used before. Therefore, we have all had to learn how to use it. 
 |Internal group conflicts   |Lack of free time for team members makes group work difficult. 
-|===
-
-****
+|===