diff --git a/docs/images/03-deployment-diagram-EN.png b/docs/images/03-deployment-diagram-EN.png new file mode 100644 index 00000000..372e2fb7 Binary files /dev/null and b/docs/images/03-deployment-diagram-EN.png differ diff --git a/docs/images/QualityTree.png b/docs/images/QualityTree.png new file mode 100644 index 00000000..6266b73f Binary files /dev/null and b/docs/images/QualityTree.png differ diff --git a/docs/src/01_introduction_and_goals.adoc b/docs/src/01_introduction_and_goals.adoc index ddb2ae3d..87c25b63 100644 --- a/docs/src/01_introduction_and_goals.adoc +++ b/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 -| __ | __ | __ -| __ | __ | __ +| _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._ |=== diff --git a/docs/src/02_architecture_constraints.adoc b/docs/src/02_architecture_constraints.adoc index 03deaad8..fdf41026 100644 --- a/docs/src/02_architecture_constraints.adoc +++ b/docs/src/02_architecture_constraints.adoc @@ -1,47 +1,65 @@ +ifndef::imagesdir[:imagesdir: ../images] + [[section-architecture-constraints]] == Architecture Constraints -=== Technical Constraints +[role="arc42help"] +**** +.Contents +Any requirement that constraints software architects in their freedom of design and implementation decisions or decision about the development process. These constraints sometimes go beyond individual systems and are valid for whole organizations and companies. -[cols="1,2", options="header"] -|========================================================================================================================================================================================================= -| Constraint | Explanation -| Docker | The application will operate within a Docker environment. -| GitHub | We'll leverage GitHub as our remote repository for project development, task delegation among team members, and version control. - -|========================================================================================================================================================================================================= +.Motivation +Architects should know exactly where they are free in their design decisions and where they must adhere to constraints. +Constraints must always be dealt with; they may be negotiable, though. -=== Organizational Constraints +.Form +Simple tables of constraints with explanations. +If needed you can subdivide them into +technical constraints, organizational and political constraints and +conventions (e.g. programming or versioning guidelines, documentation or naming conventions) -[cols="1,2", options="header"] -|========================================================================================================================================================================================================================================================== -| Constraint | Explanation -| Size of the team | The team comprises six individuals. -| Meetings | Weekly meetings are scheduled to discuss task organization during each laboratory class session. In the event of requiring an extraordinary meeting, various tools such as WhatsApp or Discord are employed to coordinate effectively. -| Testing | Various scenarios will be explored to ensure the app's functionality is tested. We'll employ a range of techniques to maximize test coverage, striving for comprehensive assessment. -| Experience | Team members possess limited and diversed experience with the diverse technologies being employed. -|========================================================================================================================================================================================================================================================== +.Further Information -=== Conventions +See https://docs.arc42.org/section-2/[Architecture Constraints] in the arc42 documentation. -[cols="1,2", options="header"] -|=== -| Constraint | Explanation +**** +=== Technical constraints -| Documentation -| The documentation must adhere to the Arc42 method, ensuring it is clear, simple, and effective. +[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_) +|=== -| Accessibility -| The application should be user-friendly, allowing all individuals to navigate effortlessly, irrespective of any disabilities, ensuring inclusivity for all users. +=== Organizational constraints -| Programming Language conventions -| We ought to follow the conventions specific to the programming languages we're employing. +[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. +|=== -| Clean Code -| The code in the application must be meticulously crafted and neat, with a focus on readability and maintainability. +=== Conventions -| Mircroservices -| The application will be divided into microservices to facilitate its development. +[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. |=== diff --git a/docs/src/03_system_scope_and_context.adoc b/docs/src/03_system_scope_and_context.adoc index c528e907..78cc50b5 100644 --- a/docs/src/03_system_scope_and_context.adoc +++ b/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 **** -**** - -**** +[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 **** -**** - -**** +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. -**** +image::03-deployment-diagram-EN.png[] diff --git a/docs/src/06_runtime_view.adoc b/docs/src/06_runtime_view.adoc index e10f375b..e63a553a 100644 --- a/docs/src/06_runtime_view.adoc +++ b/docs/src/06_runtime_view.adoc @@ -63,3 +63,16 @@ Alice <-- Bob: another authentication Response === ... === + +=== 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 +---- \ No newline at end of file diff --git a/docs/src/09_architecture_decisions.adoc b/docs/src/09_architecture_decisions.adoc index 51e9aad9..73da571c 100644 --- a/docs/src/09_architecture_decisions.adoc +++ b/docs/src/09_architecture_decisions.adoc @@ -33,3 +33,22 @@ See https://docs.arc42.org/section-9/[Architecture Decisions] in the arc42 docum There you will find links and examples about ADR. **** + +[options="header",cols="1,3,3"] +|=== +|Architecture decisions +|Advantages +|Disagvantanges + +|React +|It is the most used javascript framework and there is a lot of documentation about it. +|All of us in the team will have to learn how to use it because we have never worked with it. + +|JavaScript +|It is a language we have all used. +|It is a complex language that can cause us problems while other simpler languages could make our work easier. + +|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. +|=== diff --git a/docs/src/10_quality_requirements.adoc b/docs/src/10_quality_requirements.adoc index 68475e80..a7be69a8 100644 --- a/docs/src/10_quality_requirements.adoc +++ b/docs/src/10_quality_requirements.adoc @@ -6,7 +6,6 @@ ifndef::imagesdir[:imagesdir: ../images] [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) @@ -25,6 +24,9 @@ See https://docs.arc42.org/section-10/[Quality Requirements] in the arc42 docume **** +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"] @@ -43,9 +45,10 @@ The quality tree is a high-level overview of the quality goals and requirements: In any case the tree should include links to the scenarios of the following section. - **** +image::QualityTree.png[] + === Quality Scenarios [role="arc42help"] @@ -71,3 +74,40 @@ 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. + +[options="header",cols="1,3,3,1"] +|=== +|Quality goal +|Motivation +|Usage Scenarios +|Priority + +|Privacy +|In order to be able to play, the user must log in to the application. +|Only the user who created/owns the account will have access to it (unless he/she gives someone else his/her credentials). +|High + +|Usability +|The ease of interaction with the user should be enhanced through intuitive and simple interfaces to enhance the user experience. +|Users will be able to understand how the game works thanks to the clarity of its rules and ease of navigation. +|High + +|Diversity +|The questions provided by the application will be of various topics. +|The user must correctly answer questions on different topics. This will improve the user experience and maintain the interest of the participants. +|High + +|Integrity +|The game must be played without errors. +|The answer determined as correct for each question by the system shall be the one that is actually correct. +|High + +|Interactivity +|The user must answer a series of questions in which the user must select the correct answer in each case. +|For each of the questions, the user must select the correct answer from those provided by the system. +|High +|=== \ No newline at end of file diff --git a/docs/src/11_technical_risks.adoc b/docs/src/11_technical_risks.adoc index dc5575fc..b488dee0 100644 --- a/docs/src/11_technical_risks.adoc +++ b/docs/src/11_technical_risks.adoc @@ -23,3 +23,11 @@ List of risks and/or technical debts, probably including suggested measures to m See https://docs.arc42.org/section-11/[Risks and Technical Debt] in the arc42 documentation. **** + +[options="header"] +|=== +|Risk |Consequence + +|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. +|=== \ No newline at end of file diff --git a/docs/src/12_glossary.adoc b/docs/src/12_glossary.adoc index 192b2353..cb656f34 100644 --- a/docs/src/12_glossary.adoc +++ b/docs/src/12_glossary.adoc @@ -32,11 +32,9 @@ See https://docs.arc42.org/section-12/[Glossary] in the arc42 documentation. [cols="e,2e" options="header"] |=== -|Term |Definition +|Term |Definition -| -| - -| -| +|MongoDB |NoSQL database system that, instead of storing data in tables as a relational database does, stores data in JSON-like documents with a flexible schema. +|REACT |Open source JavaScript library developed by Facebook to build interactive and responsive user interfaces (UI). It is one of the most popular tools for modern web application development. +|Usability |Ease with which users can interact with a product, system or application to achieve their objectives effectively, efficiently and satisfactorily. |===