diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 00000000..9e26dfee --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1 @@ +{} \ No newline at end of file diff --git a/README.md b/README.md index dfe373c3..e81f57ef 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,16 @@ +## 👨‍💻 Contributors: + +| Contributor | Contact | +| ------------- | ------------- | +| Méndez Fernández, Hugo | | +| Barrero Cruz, Pablo | | +| Lago Conde, Alberto | | +| García-Ovies Pérez, Pablo | | +| Bustamante Larriet, Samuel | | +| González García, María Teresa | | +| Andina Pailos, Daniel | | + + # wiq_es04a [![Deploy on release](https://github.com/Arquisoft/wiq_es04a/actions/workflows/release.yml/badge.svg)](https://github.com/Arquisoft/wiq_es04a/actions/workflows/release.yml) diff --git a/docs/README.md b/docs/README.md index 3b91fa84..3d696d0c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -32,4 +32,4 @@ The documentation will be generated under the `docs/build` directory. ### Documentation deployment If we want to deploy it to GitHub pages, so it is accessible via [https://arquisoft.github.io/wiq_es04a/](https://arquisoft.github.io/wiq_es04a/), we need to execute `npm run deploy`. -If you check the `package.json` in this directory you can see how deploying is as easy as executing `gh-pages -d build`, which can be directly executed using `npm run deploy` in the docs directory. The `gh-pages` package is in charge of pushing the documentation generated directory (basically some htmls) to a special github branch called gh-pages. Everything pushed to this branch is accessible on the repository page. Note that we only want to push there the documentation. Also is important that the documentation build is not pushed to the other branches of the project. \ No newline at end of file +If you check the `package.json` in this directory you can see how deploying is as easy as executing `gh-pages -d build`, which can be directly executed using `npm run deploy` in the docs directory. The `gh-pages` package is in charge of pushing the documentation generated directory (basically some htmls) to a special github branch called gh-pages. Everything pushed to this branch is accessible on the repository page. Note that we only want to push there the documentation. Also is important that the documentation build is not pushed to the other branches of the project. diff --git a/docs/images/03_Business_1.png b/docs/images/03_Business_1.png new file mode 100644 index 00000000..e9414421 Binary files /dev/null and b/docs/images/03_Business_1.png differ diff --git a/docs/images/03_Technical_1.png b/docs/images/03_Technical_1.png new file mode 100644 index 00000000..41a64d4d Binary files /dev/null and b/docs/images/03_Technical_1.png differ diff --git a/docs/images/03_Technical_2.png b/docs/images/03_Technical_2.png new file mode 100644 index 00000000..dbeb0b2b Binary files /dev/null and b/docs/images/03_Technical_2.png differ diff --git a/docs/images/05_level1.png b/docs/images/05_level1.png new file mode 100644 index 00000000..dfa39418 Binary files /dev/null and b/docs/images/05_level1.png differ diff --git a/docs/images/05_level2_usersManagement.png b/docs/images/05_level2_usersManagement.png new file mode 100644 index 00000000..de6f8679 Binary files /dev/null and b/docs/images/05_level2_usersManagement.png differ diff --git a/docs/images/05_scope_context.png b/docs/images/05_scope_context.png new file mode 100644 index 00000000..9bea72d4 Binary files /dev/null and b/docs/images/05_scope_context.png differ diff --git a/docs/images/06_login_sequence.png b/docs/images/06_login_sequence.png new file mode 100644 index 00000000..2d8e1949 Binary files /dev/null and b/docs/images/06_login_sequence.png differ diff --git a/docs/images/06_register_sequence.png b/docs/images/06_register_sequence.png new file mode 100644 index 00000000..aa33517e Binary files /dev/null and b/docs/images/06_register_sequence.png differ diff --git a/docs/images/08_domain_model.png b/docs/images/08_domain_model.png new file mode 100644 index 00000000..cb4b21f6 Binary files /dev/null and b/docs/images/08_domain_model.png differ diff --git a/docs/images/08_mindmap_concepts.png b/docs/images/08_mindmap_concepts.png new file mode 100644 index 00000000..450f0b69 Binary files /dev/null and b/docs/images/08_mindmap_concepts.png differ diff --git a/docs/images/DeploymentView.png b/docs/images/DeploymentView.png new file mode 100644 index 00000000..7e519b22 Binary files /dev/null and b/docs/images/DeploymentView.png differ diff --git a/docs/images/Quality_Tree.png b/docs/images/Quality_Tree.png new file mode 100644 index 00000000..15623e08 Binary files /dev/null and b/docs/images/Quality_Tree.png differ diff --git a/docs/images/deploymentViewMermaid.png b/docs/images/deploymentViewMermaid.png new file mode 100644 index 00000000..69555f69 Binary files /dev/null and b/docs/images/deploymentViewMermaid.png differ diff --git a/docs/index.adoc b/docs/index.adoc index 468be5fd..addd6bb5 100644 --- a/docs/index.adoc +++ b/docs/index.adoc @@ -6,7 +6,7 @@ // configure EN settings for asciidoc include::src/config.adoc[] -= image:arc42-logo.png[arc42] Template += image:arc42-logo.png[arc42] Wikidata Infinite Quest :revnumber: 8.2 EN :revdate: January 2023 :revremark: (based upon AsciiDoc version) diff --git a/docs/src/01_introduction_and_goals.adoc b/docs/src/01_introduction_and_goals.adoc index d20ec35b..4880475b 100644 --- a/docs/src/01_introduction_and_goals.adoc +++ b/docs/src/01_introduction_and_goals.adoc @@ -15,6 +15,19 @@ These include * relevant stakeholders and their expectations **** +The aim of this project is to create a version of the famous quiz show "Saber y Ganar". In the quiz you have to +answer different questions about various topics (chosing topic will be possible), winning a reward for each correct answer. +One of the most relevant requirement is that the questions are generated from WikiData so there will always be different questions. + +To do the game we are going to develop a web application that will be available to enter from any device with internet connection. + +Regarding quality requirements, the goal is to achieve an optimal level, especially in terms of usability, + maintainability, efficiency, security, and testability. + +The main stakeholders in the project are several. Firstly, Professor José Emilio Labra, who teaches the +subject. Also, the students and members of the HappySoftware development team. Lastly, potential users of +the application will show interest in the project, as their user experience depends on it. + === Requirements Overview [role="arc42help"] @@ -41,6 +54,17 @@ See https://docs.arc42.org/section-1/[Introduction and Goals] in the arc42 docum **** +An enumeration of the requirements that the project must meet in terms of functionality can be elaborated: + +The application must be accessed through a web frontend. +A record of users and their game history will be maintained. +Both questions and answers will be generated using data collected from Wikidata, with only one of the +four answer options being correct. +There will be a countdown to answer each question. +Two APIs will exist to access information about both users and generated questions. +Reference to the requirements source: +https://docs.google.com/document/d/1pahOfYFY--Wi7_9bbxiKOGevB_9tOSyRm78blncgBKg/[Reference to the requirements source] + === Quality Goals [role="arc42help"] @@ -63,6 +87,15 @@ If you as an architect do not know how the quality of your work will be judged.. A table with quality goals and concrete scenarios, ordered by priorities **** +[options="header",cols="1,2"] +|=== +|Quality goal|Concrete scenario +|Usability|It must be easy to use the app, thus everybody could use it +|Availability|The system should be available the most time possible +|Security|The user's data must remain confidential. +|Performance|Using the system must be as smooth as possible. Especially, the question generation must be fast. +|=== + === Stakeholders [role="arc42help"] @@ -88,6 +121,9 @@ Table with role names, person names, and their expectations with respect to the [options="header",cols="1,2,2"] |=== |Role/Name|Contact|Expectations -| __ | __ | __ -| __ | __ | __ +| Happy Software |Hugo Méndez Fernández, Pablo Barrero Cruz, Alberto Lago Conde, Pablo García-Ovies Pérez, Samuel Bustamante Larriet, María Teresa González García, Daniel Andina Pailos| Students are the developers of the app. They need to do a great project to obtain a good mark. +| Teachers | José Emilio Labra | They will qualify the proyect. +| Users | Users of the game | They want to have fun answering questions. It must be intuitive and easy to use. |=== + + diff --git a/docs/src/02_architecture_constraints.adoc b/docs/src/02_architecture_constraints.adoc index 226e501f..4283e80e 100644 --- a/docs/src/02_architecture_constraints.adoc +++ b/docs/src/02_architecture_constraints.adoc @@ -3,7 +3,6 @@ ifndef::imagesdir[:imagesdir: ../images] [[section-architecture-constraints]] == Architecture Constraints - [role="arc42help"] **** .Contents @@ -19,9 +18,52 @@ 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) - .Further Information See https://docs.arc42.org/section-2/[Architecture Constraints] in the arc42 documentation. **** +There are various architectural constraints that affect this application. They have been divided into the following sections. + +=== Naming Conventions +[options="header"] +|=== +| Constraint | Description +| Application name | The name of the developed application will be WIQ. We have discussed the https://github.com/Arquisoft/wiq_es04a/discussions/19[meaning of these acronyms] +|=== + +=== Application Requirements +[options="header"] +|=== +| Constraint | Description +| Theme | Online question and answer application. It is similar to the "Saber y Ganar" game show. +| Question generation | Both questions and answers will be automatically generated from Wikidata. +| Question structure | Each question will have one correct answer and multiple incorrect or distracting answers. There will be a time limit to answer each question. +| Frontend | The system will have at least one Web frontend deployed. Access will be through the Web. +| User management | Users can register and log in to play. Registered users can also check their participation history in the system (number of games, correct/incorrect answers, times, etc.). +| API usage | APIs will be used to access users and generated questions information. +| Docker | Docker will be used to deploy the application locally and remotely. +|=== + +=== Documentation +[options="header"] +|=== +| Constraint | Description +| Use of Arc42 | The project will follow the Arc42 documentation standard. +|=== + +=== Organizational and Versioning Constraints +[options="header"] +|=== +| Constraint | Description +| Project organization | The project is distributed in three established deliveries. Therefore, each module of the project will evolve in several versions, marked by the deliveries. At the end of these deliveries a final presentation will take place. Then, the team will explain the application. +| Git and Github | The use of Git as a version control system and the Github platform is mandatory. The public repository will be hosted on this platform. +|=== + +=== Development Team Constraints +[options="header"] +|=== +| Constraint | Description +| Technical and theoretical knowledge | We are not professional developers and have limited experience. Therefore, we will use tools and languages minimally known by some team members. +| Budget | We will use free tools or services for which the University has a license. +|=== \ No newline at end of file diff --git a/docs/src/03_system_scope_and_context.adoc b/docs/src/03_system_scope_and_context.adoc index c528e907..9fae1132 100644 --- a/docs/src/03_system_scope_and_context.adoc +++ b/docs/src/03_system_scope_and_context.adoc @@ -48,9 +48,10 @@ The title of the table is the name of your system, the three columns contain the **** -**** +image:03_Business_1.png["Diagram 3.1: Business Context"] -**** +- **WIQ:** Overview of the whole system. Essentialy, a web application in which users will be able to register/log in, play "Saber y Ganar" and display statistics of their games. +- **Wikidata:** Free and open knowledge base that acts as a central storage repository for structured data. Its API will be used to obtain information used in questions and answers of the application. === Technical Context @@ -68,8 +69,17 @@ together with a mapping table showing the relationships between channels and inp **** -**** +==== System Scope +image:03_Technical_1.png["Diagram 3.2: Techincal Context"] -**** -**** +- **WIQ Webapp:** Module that supports user interaction via UI _i.e._, the front-end of the whole system. +- **Gateway Service:** Express service that is exposed to the public and serves as a proxy to the users management allowing sign up and log in. +- **Question Generation Service**: Service that will be used internally to manage information retrival from Wikidata. + +==== Gateway Service System +image:03_Technical_2.png["Diagram 3.3: Communication"] + + +- **User service:** Express service that handles the insertion of new users in the system. +- **Auth service:** Express service that handles the authentication of users. diff --git a/docs/src/04_solution_strategy.adoc b/docs/src/04_solution_strategy.adoc index 7bf03f7a..9c5a7122 100644 --- a/docs/src/04_solution_strategy.adoc +++ b/docs/src/04_solution_strategy.adoc @@ -3,7 +3,6 @@ ifndef::imagesdir[:imagesdir: ../images] [[section-solution-strategy]] == Solution Strategy - [role="arc42help"] **** .Contents @@ -30,3 +29,46 @@ Refer to details in the following sections. See https://docs.arc42.org/section-4/[Solution Strategy] in the arc42 documentation. **** + +=== Technology decisions + +To develop the app we will use the following technologies: + +* JavaScript will be the main programming language +* ReactJS to build the user interface +* Docker Compose to deploy all the microservices +* GitHub for version control +* WikiData API to obtain question and answer information + +We have considered the trade-offs that belong to each technology, such as SpringBoot or PHP for the backend of the app. +However, JavaScript was the language that adapted better to our requirements due to the simplicity of the language and its + focus on agile development that can lead to faster development cycles. +One of the main disadvantages is that we had to learn it, because our main language is Java. + +Decisions about the top-level decomposition of the system + +We decided to use a microservices arquitecture, having different modules for each functionality. +For example, we will use a microservice to generate the questions. + + === Decisions on how to achieve key quality goals + + Quality goals are explained in detail in point 10. + +[options="header",cols="1,2"] +|=== +|Quality goal| Decisions to achieve it. +|Usability| We are going to use real users to test the app interface and improve it according to their feedback. +|Availability| Docker Compose will be helpful to avoid problems with the deploy of the app. In addition we will use web hosting to expose it to the internet. +|Security| A login system with encrypted password storage will be used to protect the user data. +|Performance| We will use the minimum required calls to the APIs to mantain the minimum time response, for example, with bulk requests. +|=== + +=== Relevant organizational decisions + +Our framework will be based on working every week with two weekly meetings, one will be held during lab time in order to assign tasks and make minor decisions. +On the other hand, the weekend meeting will be intended for more thorough reviews as well as more significant decisions. + +Each assigned task will be created as an Issue in GitHub to track the progress done. In addition, we are going to use GitHub Projects to organize the workflow of the team. +To merge the code to the develop branch we are going to use Pull Requests in order to be approved by every person of the team. + + diff --git a/docs/src/05_building_block_view.adoc b/docs/src/05_building_block_view.adoc index df5c29c8..d95fdbe1 100644 --- a/docs/src/05_building_block_view.adoc +++ b/docs/src/05_building_block_view.adoc @@ -2,8 +2,8 @@ ifndef::imagesdir[:imagesdir: ../images] [[section-building-block-view]] - == Building Block View +The building block view shows in a graphic way a decomposition of the system. [role="arc42help"] **** @@ -42,6 +42,8 @@ See https://docs.arc42.org/section-5/[Building Block View] in the arc42 document === Whitebox Overall System +Main view of the system. WIQ application is related to one external component: the Wikidata API + [role="arc42help"] **** Here you describe the decomposition of the overall system using the following white box template. It contains @@ -63,45 +65,15 @@ In the best case you will get away with examples or simple signatures. **** -_****_ +image:05_scope_context.png["Main Build Block"] Motivation:: -__ - - -Contained Building Blocks:: -__ - -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** -| __ | __ -| __ | __ -|=== - - - -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. -**** - - -==== +This is a general overview of the application. Here it can be seen the external services that will be used. [role="arc42help"] **** -Here you describe +Here you describe black boxes according the the following black box template: * Purpose/Responsibility @@ -113,100 +85,72 @@ according the the following black box template: **** -__ - -__ - -_<(Optional) Quality/Performance Characteristics>_ - -_<(Optional) Directory/File Location>_ - -_<(Optional) Fulfilled Requirements>_ - -_<(optional) Open Issues/Problems/Risks>_ - - - - -==== - -__ - -==== - -__ - - -==== - -... - -==== - - +Contained Building Blocks:: +* **WIQ**: It is the main application, represented as a blackbox that will be detailed in the following decompositions. +* **Wikidata API**: It is the external API that the system uses to generate questions and answers. -=== Level 2 +=== Level 1 [role="arc42help"] **** -Here you can specify the inner structure of (some) building blocks from level 1 as white boxes. +Here you can specify the inner structure of (some) building blocks from Overall System 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 __ +==== White Box WIQ [role="arc42help"] **** -...describes the internal structure of _building block 1_. +...describes the internal structure of _building block WIQ_. **** +_**Overview Diagram**_ -__ - -==== White Box __ +image:05_level1.png["White Box WIQ"] +Motivation:: -__ - -... - -==== White Box __ - - -__ - +First decomposition of the system. It shows the webapp, users managament and question generator modules as blackboxes. Also displays the docs module which contains the documentation of the project. +Contained Building Blocks:: +* **WebApp**: It is the main module of the application. +* **UsersManagement**: Handles user management. +* **QuestionGenerationSystem**: It is responsible for the automatic generation of questions and answers using the Wikidata API. +* **Docs**: It is the module of the project devoted to provide all the documentation of the application. It won't be decomposed any further. -=== Level 3 +=== Level 2 [role="arc42help"] **** -Here you can specify the inner structure of (some) building blocks from level 2 as white boxes. +Here you can specify the inner structure of (some) building blocks from level 1 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_> +==== White Box Users Management [role="arc42help"] **** -Specifies the internal structure of _building block x.1_. +Specifies the internal structure of _building block Users Management_. **** +_**Overview Diagram**_ +image:05_level2_usersManagement.png["White Box Users Management"] -__ - - -==== White Box <_building block x.2_> +Motivation:: -__ +Decomposition of the level 1 system. It shows the gateway, users, authentification and database modules as blackboxes. +Contained Building Blocks:: +* **Gateway Service**: Express service that is exposed to the public and serves as a proxy to the two next ones. +* **Authentication Service**: Express service that handles the authentication of users. +* **User Service**: Express service that handles the insertion of new users in the system. +* **Data Base**: Pending to decide. +**PENDING TO COMPLETE...** -==== White Box <_building block y.1_> -__ diff --git a/docs/src/06_runtime_view.adoc b/docs/src/06_runtime_view.adoc index e10f375b..de94c831 100644 --- a/docs/src/06_runtime_view.adoc +++ b/docs/src/06_runtime_view.adoc @@ -3,6 +3,7 @@ ifndef::imagesdir[:imagesdir: ../images] [[section-runtime-view]] == Runtime View +In this Runtime View section, some sequence diagrams of different interactions with the system will be shown. [role="arc42help"] **** @@ -37,29 +38,12 @@ See https://docs.arc42.org/section-6/[Runtime View] in the arc42 documentation. **** -=== +=== Register Scenario +image:06_register_sequence.png["Register Sequence"] -* __ -* __ +=== Login Scenario -It is possible to use a sequence diagram: +image:06_login_sequence.png["Login Sequence"] -[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 ----- - -=== - -=== ... - -=== +=== TBD diff --git a/docs/src/07_deployment_view.adoc b/docs/src/07_deployment_view.adoc index 22b45c27..4c589282 100644 --- a/docs/src/07_deployment_view.adoc +++ b/docs/src/07_deployment_view.adoc @@ -42,53 +42,14 @@ See https://docs.arc42.org/section-7/[Deployment View] in the arc42 documentatio **** -=== Infrastructure Level 1 +We have several services deployed in a single containter using Docker Compose, this eases the deployment. +This are the different container and their relations: -[role="arc42help"] -**** -Describe (usually in a combination of diagrams, tables, and text): - -* distribution of a system to multiple locations, environments, computers, processors, .., as well as physical connections between them -* important justifications or motivations for this deployment structure -* quality and/or performance features of this infrastructure -* mapping of software artifacts to elements of this infrastructure - -For multiple environments or alternative deployments please copy and adapt this section of arc42 for all relevant environments. -**** - -_****_ - -Motivation:: - -__ - -Quality and/or Performance Features:: - -__ - -Mapping of Building Blocks to Infrastructure:: -__ - - -=== Infrastructure Level 2 - -[role="arc42help"] -**** -Here you can include the internal structure of (some) infrastructure elements from level 1. - -Please copy the structure from level 1 for each selected element. -**** - -==== __ - -__ - -==== __ - -__ - -... +- WebApp: Gets data from Gateway Service. +- Gateway Service: Data access interface for services. +- User Services: Manages authentication and login systems. +- Database: Persistance system for the application. -==== __ +We are going to use an Azure VM to deploy all this services. -__ +image::deploymentViewMermaid.png["Deployment View"] diff --git a/docs/src/08_concepts.adoc b/docs/src/08_concepts.adoc index 591ccf1f..193d09ac 100644 --- a/docs/src/08_concepts.adoc +++ b/docs/src/08_concepts.adoc @@ -3,7 +3,6 @@ ifndef::imagesdir[:imagesdir: ../images] [[section-concepts]] == Cross-cutting Concepts - [role="arc42help"] **** .Content @@ -56,18 +55,36 @@ See https://docs.arc42.org/section-8/[Concepts] in the arc42 documentation. **** -=== __ +Some important concepts need to be taken into account so as to a better understanding of the application. These concepts have to do with the following categories. + +. Domain concepts +. User Experience (UX) +. Operation Concepts +. Architecture and Design Patterns +. Development Concepts + +Next, each category will be detailed. -__ +=== Domain concepts +At the moment, nothing has been definitively decided or implemented to support the following outline. This simply illustrates how a preliminary version of the structure of our application could look like. +image::08_domain_model.png["Initial version of the domain model"] +=== User Experience (UX) +* https://arquisoft.github.io/wiq_es04a/#_technical_terms[**Frontend**]: the frontend of this application consists of a web app which will be deployed. Now, the user can register and log in with accounts already created on an intuitive page. +* https://arquisoft.github.io/wiq_es04a/#_technical_terms[**Internationalization**] The application will likely be available in various languages, including English as the main language. This would provide a better user experience as users could better tailor the application to their personal preferences. -=== __ +=== Operation Concepts +* **Usability**: The application should be easy to use. For this reason, we will probably some various people to try our application. This way we can know its strengths and weaknesses and improve them. Usability affects User Experience as well, so it is an important aspect of the application. -__ +=== Security +At the moment, there are no security mechanisms implemented, but decisions regarding this aspect will be taken as progress is made. -... +=== Architecture and Design Patterns +* https://arquisoft.github.io/wiq_es04a/#_technical_terms[**Microservice**]: In this application there are some microservices such as the User Management, which involves signing up, logging in and everything related to the points and timing of the user. Microservices provide an easy way of creating a complex application composed by independent systems. -=== __ +=== Development Concepts +* **Testing**: Numerous use-cases will be studied so as to provide a solid and easy-to-use application. For the moment, there is some testing in e2e folder referring to how accounts are created and how to log in the application. +* https://arquisoft.github.io/wiq_es04a/#_acronyms[**CI/CD**]: The application will be in continuous integration and deployment. Team members commit frequently into the repository where the proyect is stored. This makes it easier when assembling project parts involving collaboration from different team members. -__ +image::08_mindmap_concepts.png["Initial version of cross-cutting concepts"] diff --git a/docs/src/09_architecture_decisions.adoc b/docs/src/09_architecture_decisions.adoc index 51e9aad9..3d3242c6 100644 --- a/docs/src/09_architecture_decisions.adoc +++ b/docs/src/09_architecture_decisions.adoc @@ -33,3 +33,12 @@ See https://docs.arc42.org/section-9/[Architecture Decisions] in the arc42 docum There you will find links and examples about ADR. **** + +The architectural decisions are completely documented in our https://github.com/Arquisoft/wiq_es04a/wiki[repository Wiki section]. Henceforth, to avoid redundancy, instead of re-document those decisions here, we will refer to them. + +=== Team Working Methodology +- https://github.com/Arquisoft/wiq_es04a/wiki/ADR-01-‐-Usage-of-A-Succesful-Branching-Model[ADR 01] - Usage of A Succesful Branching Model + +_TBD when more architecture decisions are taken_ + + diff --git a/docs/src/10_quality_requirements.adoc b/docs/src/10_quality_requirements.adoc index 68475e80..ac8accf6 100644 --- a/docs/src/10_quality_requirements.adoc +++ b/docs/src/10_quality_requirements.adoc @@ -3,6 +3,13 @@ ifndef::imagesdir[:imagesdir: ../images] [[section-quality-scenarios]] == Quality Requirements +The main quality goals are: + +* **Usability**: The interface should be intuitive, with clear instructions and an accessible design. This will allow users of all abilities to navigate and use the application effortlessly. +* **Availability**: The system should aim for maximum availability, ensuring it is accessible around the clock. This will guarantee uninterrupted access most of the time, regardless of their time zone or schedule. +* **Security**: User data confidentiality must be upheld as a top priority, ensuring sensitive information remains secure and protected at all times. This commitment to privacy instills trust and confidence among users, fostering a safe and secure environment for their data. +* **Performance**: Efficiency is paramount in system usage, particularly in swift question generation, ensuring a seamless experience for users. Streamlining processes enhances overall usability, enabling swift and effortless interaction with the system. + [role="arc42help"] **** @@ -27,6 +34,8 @@ See https://docs.arc42.org/section-10/[Quality Requirements] in the arc42 docume === Quality Tree +image::Quality_Tree.png["Quality Tree"] + [role="arc42help"] **** .Content @@ -48,6 +57,29 @@ In any case the tree should include links to the scenarios of the following sect === Quality Scenarios +Usage Scenario table: + +[options="header",cols="1,2"] +|=== +|Usage Scenario|System Reaction +|The user initiates the web application, enters their username and password, and clicks the login button.|The system verifies the information entered by the user, and if correct, redirects them to the main page; otherwise, it indicates an error has occurred. +|The user surveys the main window, where several buttons with different options appear.|In response to pressing each of these buttons, the system will display the corresponding content. +|The user starts the game and is awaiting the questions.|The system swiftly generates the question and its possible answers. +|The user loses the game and decides to stop playing for a while. Five hours later, they decide to play again.|The system remains active and functions correctly. +|=== + + +Change Scenario table: + +[options="header",cols="1,2"] +|=== +|Change Scenario|System Reaction +|Adding an additional login system to access the account not only through email but also through the username. |The system should be capable of adapting to provide this functionality without affecting the existing ones. +|Adding a new game mode or functionality.|When adding a new feature, the application's usage methodology should not be distorted, ensuring it can still be used in the same manner. +|Adding a new game language.|When adding a new game language, the system should continue to function smoothly. +|=== + + [role="arc42help"] **** .Contents diff --git a/docs/src/11_technical_risks.adoc b/docs/src/11_technical_risks.adoc index dc5575fc..e2c21d9a 100644 --- a/docs/src/11_technical_risks.adoc +++ b/docs/src/11_technical_risks.adoc @@ -23,3 +23,19 @@ 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. **** +=== Technical risks +To assess the relevance level of the following technical risks, we will use number 1 to indicate low relevance, 2 for medium relevance, and 3 for high relevance. +[cols="1,1,3", options="header"] +|=== +| Technical Risk | Relevance | Considerations +| Limited knowledge of certain tools or languages | 2 | A solution could be to use the tools and languages that are most well-known to the team members. Also, each member should try to learn those aspects they know less about. +| The team has not worked together before | 1 | A suggestion could be to mantain a good communication and inform about any aspect that could affect others. +| Being a big group | 1 | Being many members can difficult the communication. However, if the previous suggestions are followed there should not be any problem. +|=== + +=== Technical debts +[cols="1,3", options="header"] +|=== +| Technical Debt | Considerations +| Low-quality code | The use of new technologies and languages can lead to poorly written or poorly designed code. To address this issue, we will use pull requests to ensure that the code is reviewed by multiple team members. +|=== diff --git a/docs/src/12_glossary.adoc b/docs/src/12_glossary.adoc index 192b2353..ca1e1f6a 100644 --- a/docs/src/12_glossary.adoc +++ b/docs/src/12_glossary.adoc @@ -3,6 +3,8 @@ ifndef::imagesdir[:imagesdir: ../images] [[section-glossary]] == Glossary +In this section we will present, define and translate some concepts that we consider relevant to know when facing our application. + [role="arc42help"] **** .Contents @@ -30,13 +32,110 @@ See https://docs.arc42.org/section-12/[Glossary] in the arc42 documentation. **** -[cols="e,2e" options="header"] +=== Acronyms +[cols="1,1,3",options="header"] +|=== +|Acronym |Term |Definition + +|ADR +|Arquitectural Design Record +|Document that describes a choice the team makes about a significant aspect of the software architecture they're planning to build. Each ADR describes the architectural decision, its context, and its consequences, and its goal is to ensure that the proposed design meets functional, aesthetic, regulatory, and safety requirements before proceeding further with the project. + +|API +|Application Programming Interface +|Set of rules, protocols, and tools that allows different software applications to communicate and interact with each other. It defines the methods and data formats that developers can use to request and exchange information between different software components. + +|CI/CD +|Continuous Integration & Continuous Delivery +|CI refers to the practice of automatically and frequently integrating code changes into a shared source code repository; CD is a 2 part process that refers to the integration, testing, and delivery of code changes. Continuous delivery stops short of automatic production deployment, while continuous deployment automatically releases the updates into the production environment. + +|PR +|Pull Request +|Proposal to merge a set of changes from one branch into another. In a pull request, collaborators can review and discuss the proposed set of changes before they integrate the changes into the main codebase. + +|WIQ +|https://github.com/Arquisoft/wiq_es04a/discussions/19[Wikidata Infinite Quest] +|Web application's name, where the users can register and login themselves to play different type of rounds. |=== -|Term |Definition -| -| +=== Domain Specific Terms +[cols="1,3,1",options="header"] +|=== +|Term |Definition |ES Translation + +|Discarding +|Test in which the participants must answer a series of multiple-choice questions; for each question, they are presented with a set of options and must eliminate those they believe to be incorrect until they arrive at the correct answer. This process of elimination continues until the contestants are confident in the correct answer or until the allotted time for the test runs out +|Descartando + +|Discovering cities +|Test in which contestants receive clues about a specific city and must guess which city it is; this clues may include descriptions of geographical features, famous monuments, historical or cultural events, among other aspects related to the city in question. +|Descubriendo ciudades + +|HappySw +|Name of the fictitious company under which the members of the group will simulate that we have been hired to develop the application. +|_N/A_ + +|Know & Win +|Popular Spanish television program that combines quiz shows with educational entertainment aired daily on La 2 of Televisión Española. The show is known for its unique format, which includes a variety of challenges and tests where contestants demonstrate their knowledge in different areas such as history, geography, science, popular culture, literature, art, among other subjects. +|"Saber Y Ganar" + +|Warm question +|Test in which contestants' aim is to answer questions rapidly and accurately, requiring quick thinking, as questions are presented rapidly without pauses between them. Contestants strive to provide correct answers to accumulate points, but they must also carefully assess the risk of answering incorrectly, which could lead to losing points. +|Pregunta caliente + +|Wise Men Stack +|Test in which questions are presented on a wide range of topics spanning from literature and history to science and popular culture. Contestants must answer as many questions correctly as possible within a limited time frame. +|Batería de sabios + +|=== + +=== Technical Terms +[cols="1,3,1",options="header"] +|=== +|Term |Definition |ES Translation + +|Arc42 +|Set of recommendations for documenting and designing software architectures, particularly for software-intensive systems, that provides a template for architecture documentation structured into various sections covering different aspects of the architecture and aiming to promote clear communication and understanding of this one among stakeholders. +|_N/A_ + +|Backend +|Server-side of a software application or website. It encompasses everything that users don't see directly, such as databases, servers, and application logic. The backend is responsible for processing requests from the frontend and generating the appropriate responses. +|_N/A_ + +|Container +|Lightweight, portable, and self-contained unit that packages together all the necessary software components, such as code, runtime, libraries, and dependencies, needed to run an application. Containers provide a consistent environment for running applications across different computing environments. +|Contenedor + +|Docker +|Docker is a popular platform used for developing, shipping, and running applications within containers providing a way to automate the deployment of those applications using a client-server architecture. +|_N/A_ + +|Frontend +|Part of a software application or website that users interact with directly. It encompasses the user interface (UI) and user experience (UX) components that users see and interact with in their web browsers or on their devices. This includes elements such as buttons, forms, menus, and any visual or interactive elements users interact with to use the application. +|_N/A_ + +|Git +|Free and open-source version control system used for tracking changes in source code during software development. It allows multiple developers to collaborate on projects simultaneously and efficiently manage changes to the codebase. +|_N/A_ + +|Github +|Online software development platform built around Git used for storing, tracking, and collaborating on software projects. It makes it easy for developers to share code files and collaborate with fellow developers on open-source projects. +|_N/A_ + +|Internationalization +|Process of designing and developing a software application in such a way that it can easily adapt to different languages, cultures, and regions of the world. This involves for example the application's ability to handle different sets of characters, date and time formats, units of measurement, and other cultural and linguistic aspects. +|Internacionalización + +|Microservice +|Software architectural style that structures an application as a collection of loosely coupled services; each service is designed to perform a specific and narrowly defined function within the application. These services are typically small, independently deployable, and can be developed, tested, and deployed separately from the rest of the application. +|Microservicio + +|User +|Typically refers to an individual or entity that interacts with the system or software to perform tasks, access resources, or obtain information. Users can interact with computer systems through various means, such as graphical user interfaces, command-line interfaces, or the mentioned APIs. +|Usuario + +|Wikidata +|Free and open knowledge base that acts as a central storage repository for structured data from Wikimedia projects and beyond. It provides a common platform for collecting and sharing structured data about various topics, including but not limited to, people, places, events, concepts, and objects. +|_N/A_ -| -| |=== diff --git a/docs/src_mermaid/03_Business_1 b/docs/src_mermaid/03_Business_1 new file mode 100644 index 00000000..111dc47f --- /dev/null +++ b/docs/src_mermaid/03_Business_1 @@ -0,0 +1,8 @@ +flowchart TD + el1[User] -.->|Interacts with| sis1(WIQ Webapp) + subgraph WIQ + sis1 --> |Authenticate| sis2(Gateway Service) + sis1 --> |Create user| sis2 + sis1 --> |Get questions| sis5(Question Generation Service) + end + sis5 -.-> D[Wikidata] \ No newline at end of file diff --git a/docs/src_mermaid/03_Technical_1 b/docs/src_mermaid/03_Technical_1 new file mode 100644 index 00000000..1279aee4 --- /dev/null +++ b/docs/src_mermaid/03_Technical_1 @@ -0,0 +1,12 @@ +flowchart TD + el1[User] -.->|Interacts with| sis1(WIQ Webapp) + subgraph WIQ + sis1 --> |Authenticate| sis2(Gateway Service) + sis1 --> |Create user| sis2 + sis1 --> |Get questions| sis5(Question Generation Service) + sis2 --> |Log in validation| sis3(Authentication service) + sis2 --> |Sign up user| sis4(User service) + sis3 --> db1[(MongoDB)] + sis4 --> db1 + end + sis5 -.-> D[Wikidata] \ No newline at end of file diff --git a/docs/src_mermaid/03_Technical_2 b/docs/src_mermaid/03_Technical_2 new file mode 100644 index 00000000..34fd6cff --- /dev/null +++ b/docs/src_mermaid/03_Technical_2 @@ -0,0 +1,5 @@ +flowchart TD + sis2(Gateway Service) --> |Log in validation| sis3(Authentication service) + sis2 --> |Sign up user| sis4(User service) + sis3 --> db1[(MongoDB)] + sis4 --> db1 \ No newline at end of file diff --git a/docs/src_mermaid/08_domain_model_v1 b/docs/src_mermaid/08_domain_model_v1 new file mode 100644 index 00000000..d24a55fe --- /dev/null +++ b/docs/src_mermaid/08_domain_model_v1 @@ -0,0 +1,22 @@ +classDiagram + User "*"-->"1" Contest + Contest "1"-->"*" Question + Contest "1"-->"*" Profile + Contest "1"-->"*" Award + Profile "1"-->"*" Award + class Contest { + - List~Question~ questions + - List~Profile~ profiles + } + class Profile { + - int points + - List~Award~ awards + } + class Question { + - String question + - List~String~ answers + - String correctAnswer + } + class Award { + - int price + } \ No newline at end of file diff --git a/docs/src_mermaid/08_mindmap_concepts_v1 b/docs/src_mermaid/08_mindmap_concepts_v1 new file mode 100644 index 00000000..ae148f22 --- /dev/null +++ b/docs/src_mermaid/08_mindmap_concepts_v1 @@ -0,0 +1,14 @@ +mindmap + root((Cross-cutting
concepts)) + Domain concepts + Security + Operation concepts + Usability + Architecture and Design Patterns + Microservices + User Experience + User interface + Internationalization + Development concepts + Testing + CI/CD \ No newline at end of file