diff --git a/.gitignore b/.gitignore index 925baa5e..66497da2 100644 --- a/.gitignore +++ b/.gitignore @@ -3,7 +3,9 @@ coverage docs/build ### IntelliJ IDEA ### -.idea *.iws *.iml -*.ipr \ No newline at end of file +*.ipr +.idea +.vscode +.DS_Store diff --git a/Quickstart.md b/Quickstart.md new file mode 100644 index 00000000..08764ec8 --- /dev/null +++ b/Quickstart.md @@ -0,0 +1,97 @@ +## Quick start guide + +### Using docker + +The fastest way for launching this sample project is using docker. Just clone the project: + +```sh +git clone https://github.com/Arquisoft/wiq_en2b.git +``` + +and launch it with docker compose: + +```sh +docker compose --profile dev up --build +``` + +### Starting Component by component + +First, start the database. Either install and run Mongo or run it using docker: + +```docker run -d -p 27017:27017 --name=my-mongo mongo:latest``` + +You can also use services like Mongo Altas for running a Mongo database in the cloud. + +Now, launch the auth, user and gateway services. Just go to each directory and run `npm install` followed by `npm start`. + +Lastly, go to the webapp directory and launch this component with `npm install` followed by `npm start`. + +After all the components are launched, the app should be available in localhost in port 3000. + +## Deployment + +For the deployment, we have several options. + +The first and more flexible is to deploy to a virtual machine using SSH. This will work with any cloud service (or with our own server). + +Other options include using the container services that most cloud services provide. This means, deploying our Docker containers directly. + +We are going to use the first approach, creating a virtual machine in a cloud service and after installing docker and docker-compose, deploy our containers there using GitHub Actions and SSH. + +### Machine requirements for deployment + +The machine for deployment can be created in services like Microsoft Azure or Amazon AWS. These are in general the settings that it must have: + +- Linux machine with Ubuntu > 20.04. +- Docker and docker-compose installed. +- Open ports for the applications installed (in this case, ports 3000 for the webapp and 8000 for the gateway service). + +Once you have the virtual machine created, you can install **docker** and **docker-compose** using the following instructions: + +```ssh +sudo apt update +sudo apt install apt-transport-https ca-certificates curl software-properties-common +curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add - +sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu focal stable" +sudo apt update +sudo apt install docker-ce +sudo usermod -aG docker ${USER} +sudo curl -L "https://github.com/docker/compose/releases/download/1.28.5/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose +sudo chmod +x /usr/local/bin/docker-compose +``` + +### Continuous delivery (GitHub Actions) + +Once we have our machine ready, we could deploy by hand the application, taking our docker-compose file and executing it in the remote machine. + +In this repository, this process is done automatically using **GitHub Actions**. The idea is to trigger a series of actions when some condition is met in the repository. + +As you can see, unitary tests of each module and e2e tests are executed before pushing the docker images and deploying them. Using this approach we avoid deploying versions that do not pass the tests. + +The deploy action is the following: + +```yml +deploy: + name: Deploy over SSH + runs-on: ubuntu-latest + needs: [docker-push-userservice,docker-push-authservice,docker-push-gatewayservice,docker-push-webapp] + steps: + - name: Deploy over SSH + uses: fifsky/ssh-action@master + with: + host: ${{ secrets.DEPLOY_HOST }} + user: ${{ secrets.DEPLOY_USER }} + key: ${{ secrets.DEPLOY_KEY }} + command: | + wget https://raw.githubusercontent.com/arquisoft/wiq_en2b/master/docker-compose.yml -O docker-compose.yml + wget https://raw.githubusercontent.com/arquisoft/wiq_en2b/master/.env -O .env + docker compose down + docker compose --profile prod up -d +``` + +This action uses three secrets that must be configured in the repository: +- DEPLOY_HOST: IP of the remote machine. +- DEPLOY_USER: user with permission to execute the commands in the remote machine. +- DEPLOY_KEY: key to authenticate the user in the remote machine. + +Note that this action logs in the remote machine and downloads the docker-compose file from the repository and launches it. Obviously, previous actions have been executed which have uploaded the docker images to the GitHub Packages repository. diff --git a/README.md b/README.md index dda9a07c..8d4ff531 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,17 @@ -# wiq_en2b +# 🧠🤔 wiq_en2b ❓📚 -[![Deploy on release](https://github.com/Arquisoft/wiq_en2b/actions/workflows/release.yml/badge.svg)](https://github.com/Arquisoft/wiq_en2b/actions/workflows/release.yml) -[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=Arquisoft_wiq_en2b&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=Arquisoft_wiq_en2b) -[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=Arquisoft_wiq_en2b&metric=coverage)](https://sonarcloud.io/summary/new_code?id=Arquisoft_wiq_en2b) +WIQ is a quiz game project inspired by the engaging and thought-provoking show "Saber y Ganar." +We aim to create a platform that not only challenges your knowledge but also sparks curiosity and the thrill of discovery. + + +## What Sets WIQ Apart +🤔 Thoughtful Questions: Dive into a world of intriguing and diverse questions, all generated procedurally using WikiData. +🌐 Encourage to improve: WIQ lets you keep track of your score to see in which areas you need to improve. + +## Features +🏆 Adaptable difficulty: You can adjust the difficulty to push your limits. +🌐 Multiplayer: Compete with friends and strangers to prove you are the best. -This is a base repo for the [Software Architecture course](http://arquisoft.github.io/) in [2023/2024 edition](https://arquisoft.github.io/course2324.html). - ## Contributors | Nombre | UO | |---------------------------------|----------| @@ -16,6 +22,15 @@ This is a base repo for the [Software Architecture course](http://arquisoft.gith | Sergio Quintana Fernández | UO288090 | | Diego Villanueva Berros | UO283615 | | Gonzalo Suárez Losada | UO283928 | + +*** + + +[![Deploy on release](https://github.com/Arquisoft/wiq_en2b/actions/workflows/release.yml/badge.svg)](https://github.com/Arquisoft/wiq_en2b/actions/workflows/release.yml) +[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=Arquisoft_wiq_en2b&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=Arquisoft_wiq_en2b) +[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=Arquisoft_wiq_en2b&metric=coverage)](https://sonarcloud.io/summary/new_code?id=Arquisoft_wiq_en2b) + +This is a base repo for the [Software Architecture course](http://arquisoft.github.io/) in [2023/2024 edition](https://arquisoft.github.io/course2324.html). This repo is a basic application composed of several components. @@ -26,100 +41,3 @@ This repo is a basic application composed of several components. Both the user and auth service share a Mongo database that is accessed with mongoose. -## Quick start guide - -### Using docker - -The fastest way for launching this sample project is using docker. Just clone the project: - -```sh -git clone https://github.com/Arquisoft/wiq_en2b.git -``` - -and launch it with docker compose: - -```sh -docker compose --profile dev up --build -``` - -### Starting Component by component - -First, start the database. Either install and run Mongo or run it using docker: - -```docker run -d -p 27017:27017 --name=my-mongo mongo:latest``` - -You can also use services like Mongo Altas for running a Mongo database in the cloud. - -Now, launch the auth, user and gateway services. Just go to each directory and run `npm install` followed by `npm start`. - -Lastly, go to the webapp directory and launch this component with `npm install` followed by `npm start`. - -After all the components are launched, the app should be available in localhost in port 3000. - -## Deployment - -For the deployment, we have several options. - -The first and more flexible is to deploy to a virtual machine using SSH. This will work with any cloud service (or with our own server). - -Other options include using the container services that most cloud services provide. This means, deploying our Docker containers directly. - -We are going to use the first approach, creating a virtual machine in a cloud service and after installing docker and docker-compose, deploy our containers there using GitHub Actions and SSH. - -### Machine requirements for deployment - -The machine for deployment can be created in services like Microsoft Azure or Amazon AWS. These are in general the settings that it must have: - -- Linux machine with Ubuntu > 20.04. -- Docker and docker-compose installed. -- Open ports for the applications installed (in this case, ports 3000 for the webapp and 8000 for the gateway service). - -Once you have the virtual machine created, you can install **docker** and **docker-compose** using the following instructions: - -```ssh -sudo apt update -sudo apt install apt-transport-https ca-certificates curl software-properties-common -curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add - -sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu focal stable" -sudo apt update -sudo apt install docker-ce -sudo usermod -aG docker ${USER} -sudo curl -L "https://github.com/docker/compose/releases/download/1.28.5/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose -sudo chmod +x /usr/local/bin/docker-compose -``` - -### Continuous delivery (GitHub Actions) - -Once we have our machine ready, we could deploy by hand the application, taking our docker-compose file and executing it in the remote machine. - -In this repository, this process is done automatically using **GitHub Actions**. The idea is to trigger a series of actions when some condition is met in the repository. - -As you can see, unitary tests of each module and e2e tests are executed before pushing the docker images and deploying them. Using this approach we avoid deploying versions that do not pass the tests. - -The deploy action is the following: - -```yml -deploy: - name: Deploy over SSH - runs-on: ubuntu-latest - needs: [docker-push-userservice,docker-push-authservice,docker-push-gatewayservice,docker-push-webapp] - steps: - - name: Deploy over SSH - uses: fifsky/ssh-action@master - with: - host: ${{ secrets.DEPLOY_HOST }} - user: ${{ secrets.DEPLOY_USER }} - key: ${{ secrets.DEPLOY_KEY }} - command: | - wget https://raw.githubusercontent.com/arquisoft/wiq_en2b/master/docker-compose.yml -O docker-compose.yml - wget https://raw.githubusercontent.com/arquisoft/wiq_en2b/master/.env -O .env - docker compose down - docker compose --profile prod up -d -``` - -This action uses three secrets that must be configured in the repository: -- DEPLOY_HOST: IP of the remote machine. -- DEPLOY_USER: user with permission to execute the commands in the remote machine. -- DEPLOY_KEY: key to authenticate the user in the remote machine. - -Note that this action logs in the remote machine and downloads the docker-compose file from the repository and launches it. Obviously, previous actions have been executed which have uploaded the docker images to the GitHub Packages repository. diff --git a/docs/diagrams/10_Quality_Tree.puml b/docs/diagrams/10_Quality_Tree.puml new file mode 100644 index 00000000..809e0a0d --- /dev/null +++ b/docs/diagrams/10_Quality_Tree.puml @@ -0,0 +1,23 @@ +@startuml +title Quality attributes +agent Quality +agent Security +agent Reliability +agent Transferability +agent Usability +agent "Performance Efficiency" +agent Maintainability +agent Availability +agent Compatibility +agent "Functional Suitability" + +Quality --- Security +Quality --- Reliability +Quality --- Transferability +Quality --- Usability +Quality --- "Performance Efficiency" +Quality --- Maintainability +Quality --- Availability +Quality --- Compatibility +Quality --- "Functional Suitability" +@enduml diff --git a/docs/diagrams/BusinessContextDiagram.puml b/docs/diagrams/BusinessContextDiagram.puml new file mode 100644 index 00000000..2a2fbdf7 --- /dev/null +++ b/docs/diagrams/BusinessContextDiagram.puml @@ -0,0 +1,18 @@ +@startuml +!includeurl https://raw.githubusercontent.com/RicardoNiepel/C4-PlantUML/master/C4_Container.puml +!include + +title Context Diagram for the WIQ System +LAYOUT_WITH_LEGEND() + +'Containers +Person(player, Player,"An authenticated player that wants to play WIQ games") + +Container(wiq, "WIQ Application","", "Application that allows the users to play WIQ games") + +System_Ext(wikidata,"WikiData API","Contains the information used for the question generation") + +'RELATIONS +Rel(player,wiq,"Plays games") +Rel(wiq,wikidata,"Asks for data for question generation") +@enduml \ No newline at end of file diff --git a/docs/diagrams/ContainerDiagram.puml b/docs/diagrams/ContainerDiagram.puml new file mode 100644 index 00000000..e0bd97a1 --- /dev/null +++ b/docs/diagrams/ContainerDiagram.puml @@ -0,0 +1,24 @@ +@startuml +!includeurl https://raw.githubusercontent.com/RicardoNiepel/C4-PlantUML/master/C4_Container.puml +!include + +title Context Diagram for the WIQ System +LAYOUT_WITH_LEGEND() + +'Containers +Person(player, Player,"An authenticated player that wants to play WIQ games") + +System_Boundary(wiq,"WIQ"){ + Container(web_app, "WIQ Client", "React, Typescript", "Allows the user to play WIQ games") + Container(backend_api, "WIQ REST API","Java SpringBoot 3","Handles the users, game logic and question generation") + ContainerDb(database,"WIQ Database","PostgreSQL","Stores users, questions and other game info") +} + +System_Ext(wikidata,"WikiData API","Contains the information used for the question generation") + +'RELATIONS +Rel(player,web_app,"Uses","HTTPS") +Rel(backend_api,wikidata,"Asks for data","SPARQL,HTTPS") +Rel(web_app,backend_api,"Asks for user/game information","JSON,HTTPS") +Rel(backend_api,database,"Stores game/user information","JPA") +@enduml \ No newline at end of file diff --git a/docs/diagrams/DeploymentDiagram.puml b/docs/diagrams/DeploymentDiagram.puml new file mode 100644 index 00000000..eaa1314c --- /dev/null +++ b/docs/diagrams/DeploymentDiagram.puml @@ -0,0 +1,32 @@ +@startuml + +title WIQ Deployment View + +legend right + |Color| Type | + |<#PeachPuff>| WIQ Server | + |<#DarkSalmon>| External Service | +end legend + +node "Server Hosting WIQ" #PeachPuff { + node "WIQ WebApp Server"{ + component "WIQ React Application" + } + node "WIQ API" { + component "WIQ_API.jar" + } + node "PostgreSQL Docker" { + database "WIQ Database" + } +} +node "User Computer" #DarkSalmon{ + frame "Web Client" +} +node "WikiData Server" #DarkSalmon { + frame "WikiData REST API" +} +"Web Client" ..> "WIQ React Application" : "HTTPS" +"WIQ React Application" ..> "WIQ_API.jar" : "HTTPS" +"WIQ_API.jar" ..> "WIQ Database" : "JPA" +"WIQ API" ..> "WikiData REST API" : "HTTPS, SPARQL" +@enduml \ No newline at end of file diff --git a/docs/diagrams/TechnicalContextDiagram.puml b/docs/diagrams/TechnicalContextDiagram.puml new file mode 100644 index 00000000..0c035bb9 --- /dev/null +++ b/docs/diagrams/TechnicalContextDiagram.puml @@ -0,0 +1,23 @@ +@startuml +!includeurl https://raw.githubusercontent.com/RicardoNiepel/C4-PlantUML/master/C4_Container.puml +!include + +title Context Diagram for the WIQ System +LAYOUT_WITH_LEGEND() + +'Containers +Person(player, Player's Browser,"Preferred browser (Firefox, Chrome, Opera...)") + +System_Boundary(wiq,"WIQ Server"){ + Container(web_app, "WIQ Client", "React, Typescript", "nginx web server") + Container(backend_api, "WIQ REST API","Java SpringBoot 3",".jar file") + ContainerDb(database,"WIQ Database","PostgreSQL","PostgreSQL docker container") +} +System_Ext(wikidata,"WikiData API","REST API") + +'RELATIONS +Rel(player,web_app,"Uses","HTTPS") +Rel(backend_api,wikidata,"Asks for data","SPARQL,HTTPS") +Rel(web_app,backend_api,"Asks for user/game information","JSON,HTTPS") +Rel(backend_api,database,"Stores game/user information","JPA") +@enduml \ No newline at end of file diff --git a/docs/images/10_Quality_Tree.png b/docs/images/10_Quality_Tree.png new file mode 100644 index 00000000..292718bf Binary files /dev/null and b/docs/images/10_Quality_Tree.png differ diff --git a/docs/images/BusinessContext.png b/docs/images/BusinessContext.png new file mode 100644 index 00000000..8d332809 Binary files /dev/null and b/docs/images/BusinessContext.png differ diff --git a/docs/images/ContainerDiagram.png b/docs/images/ContainerDiagram.png new file mode 100644 index 00000000..8c1c1488 Binary files /dev/null and b/docs/images/ContainerDiagram.png differ diff --git a/docs/images/DeploymentDiagram.png b/docs/images/DeploymentDiagram.png new file mode 100644 index 00000000..7453c347 Binary files /dev/null and b/docs/images/DeploymentDiagram.png differ diff --git a/docs/images/TechnicalContextDiagram.png b/docs/images/TechnicalContextDiagram.png new file mode 100644 index 00000000..6b635ca7 Binary files /dev/null and b/docs/images/TechnicalContextDiagram.png differ diff --git a/docs/index.adoc b/docs/index.adoc index 468be5fd..29cb7d6a 100644 --- a/docs/index.adoc +++ b/docs/index.adoc @@ -96,4 +96,6 @@ include::src/11_technical_risks.adoc[] // 12. Glossary include::src/12_glossary.adoc[] - +<<<< +// 13. Annex +include::src/13_annex.adoc[] diff --git a/docs/package.json b/docs/package.json index 22e2370d..4a13c872 100644 --- a/docs/package.json +++ b/docs/package.json @@ -4,12 +4,11 @@ "description": "Npm project just for the docs", "main": "index.js", "scripts": { - "build": "shx rm -rf build && asciidoctor -D build -a imagesdir=./images -r asciidoctor-diagram index.adoc && shx cp -R images build", - "deploy": "gh-pages -d build" + "build": "shx rm -rf build && asciidoctor -D build -a imagesdir=./images -r asciidoctor-diagram index.adoc && shx cp -R images build", + "deploy": "gh-pages -d build" }, "dependencies": { - "gh-pages": "^3.2.3", - "shx": "^0.3.3" + "gh-pages": "^3.2.3", + "shx": "^0.3.3" } - } - \ No newline at end of file +} diff --git a/docs/src/01_introduction_and_goals.adoc b/docs/src/01_introduction_and_goals.adoc index ddb2ae3d..7b59875b 100644 --- a/docs/src/01_introduction_and_goals.adoc +++ b/docs/src/01_introduction_and_goals.adoc @@ -2,92 +2,46 @@ ifndef::imagesdir[:imagesdir: ../images] [[section-introduction-and-goals]] == Introduction and Goals - -[role="arc42help"] -**** -Describes the relevant requirements and the driving forces that software architects and development team must consider. -These include - -* underlying business goals, -* essential features, -* essential functional requirements, -* quality goals for the architecture and -* relevant stakeholders and their expectations -**** +RTVE has hired the company HappySw, composed of students from the Oviedo School of Software Engineering, to develop a new experimental version of the quiz show Saber y Ganar. This application will be called WIQ, where users will be able to register and log in to play. The application will consist of answering questions of different types generated with Wikidata. For each question answered correctly, points will be obtained. === Requirements Overview - -[role="arc42help"] -**** -.Contents -Short description of the functional requirements, driving forces, extract (or abstract) -of requirements. Link to (hopefully existing) requirements documents -(with version number and information where to find it). - -.Motivation -From the point of view of the end users a system is created or modified to -improve support of a business activity and/or improve the quality. - -.Form -Short textual description, probably in tabular use-case format. -If requirements documents exist this overview should refer to these documents. - -Keep these excerpts as short as possible. Balance readability of this document with potential redundancy w.r.t to requirements documents. +* The system shall provide non-registered users with the option to sign up. +* The system shall provide unidentified users with the option to log in. +* The system shall only be used by registered users. +* The system shall have a game mode with 9 rounds. +* In each round, the system shall generate a question. +* In each round, the system shall generate four answers, with only one being correct. +* The system shall offer registered users access to the number of games they have played. +* The system shall offer registered users access the number of questions they have answered correctly. +* The system shall offer registered users access the number of questions they have answered incorrectly. +* The system shall offer registered users access the time they have spent within the system. +* The system shall offer registered users access the ranking of the game. +* The system shall set a time limit for registered users to respond to each question. + +See the complete functional requirements in the xref:#section-annex[Annex] of the documentation. -.Further Information - -See https://docs.arc42.org/section-1/[Introduction and Goals] in the arc42 documentation. - -**** - === Quality Goals - -[role="arc42help"] -**** -.Contents -The top three (max five) quality goals for the architecture whose fulfillment is of highest importance to the major stakeholders. -We really mean quality goals for the architecture. Don't confuse them with project goals. -They are not necessarily identical. - -Consider this overview of potential topics (based upon the ISO 25010 standard): - -image::01_2_iso-25010-topics-EN.drawio.png["Categories of Quality Requirements"] - -.Motivation -You should know the quality goals of your most important stakeholders, since they will influence fundamental architectural decisions. -Make sure to be very concrete about these qualities, avoid buzzwords. -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 -**** +[options="header",cols="1,3"] +|=== +|Goal|Description +| Functional suitability | The system shall fulfill its intended purpose effectively and efficiently, allowing users to register, log in, play the quiz, and access their user statistics. +| Security | The system must prioritize user data security. It must implement robust authentication mechanisms for user registration and login. The API access points for user information and generated questions must be secured with proper authorization. +| Reliability | The system should be reliable in generating questions from Wikidata, ensuring that questions are accurate and diverse. The system must handle user registrations, logins, and game data storage without errors. +| Availability | The system must be available 99.99% of the time a user tries to access it. +| Maintainability | The system must be designed and implemented in a way that facilitates easy maintenance and updates. +| Performance efficiency | The system must deliver optimal performance, ensuring responsive interactions for users. The automatic generation of questions from Wikidata and the real-time gameplay must be efficient. The system must handle N concurrent users. +| Usability | The system must provide a user-friendly interface, making it easy for users to register, log in, and play the game. The system learning time for a user should be less than 4 hours. +| Compatibility | The system must be compatible with various web browsers and devices, ensuring a seamless experience for users regardless of their choice of platform. It has to be well-optimized for different screen sizes and functionalities. +| Transferability | The system must allow for easy transfer of user data and game-related information through its APIs. +|=== === Stakeholders - -[role="arc42help"] -**** -.Contents -Explicit overview of stakeholders of the system, i.e. all person, roles or organizations that - -* should know the architecture -* have to be convinced of the architecture -* have to work with the architecture or with code -* need the documentation of the architecture for their work -* have to come up with decisions about the system or its development - -.Motivation -You should know all parties involved in development of the system or affected by the system. -Otherwise, you may get nasty surprises later in the development process. -These stakeholders determine the extent and the level of detail of your work and its results. - -.Form -Table with role names, person names, and their expectations with respect to the architecture and its documentation. -**** - -[options="header",cols="1,2,2"] +[options="header",cols="1,1,2"] |=== |Role/Name|Contact|Expectations -| __ | __ | __ -| __ | __ | __ +| RTVE | rtve@email.com | To have a new experimental version of the Saber y Ganar quiz show. +| HappySw | happysw@email.com | Develop a good application that fullfills the requirements expected by the client. +| Registered user | Unknown | To play with an entertaining and easy-to-use application. An application with which the user learn about different topics. +| Wikidata | wikid@email.com | Being able to offer service allowing people to use the data through the API. |=== diff --git a/docs/src/02_architecture_constraints.adoc b/docs/src/02_architecture_constraints.adoc index 226e501f..6d48d584 100644 --- a/docs/src/02_architecture_constraints.adoc +++ b/docs/src/02_architecture_constraints.adoc @@ -3,25 +3,28 @@ ifndef::imagesdir[:imagesdir: ../images] [[section-architecture-constraints]] == Architecture Constraints +The application must be developed according to some constraints that were defined by the professors. These constraints are meant to be the cornerstones of our project as they are mandatory and provide a baseline to work on. The following tables will define the constraints. + + +*Technical constraints* +|=== +| *Constraint* | *Description* +| Web accesible front-end | The application must be possible to access through a web browser +| Use of WikiData | The system must make use of WikiData to gather information +| Automatic questions | The questions prompted by the game must be generated automatically +|=== + +*Organizational constraints* +|=== +| *Constraint* | *Description* +| Weekly meetings | Each class week, the team must meet and discuss the development +| Use of GitHub | GitHub must be used to communicate and keep track of the development process +| Deliverables | The project will be reviewed by the professors on three occasions +|=== + +*Conventional constraints* +|=== +| *Constraint* | *Description* +| Documentation in Arc42 | The documentation must follow the Arc42 template +|=== -[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. - -.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. - -.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) - - -.Further Information - -See https://docs.arc42.org/section-2/[Architecture Constraints] in the arc42 documentation. - -**** diff --git a/docs/src/03_system_scope_and_context.adoc b/docs/src/03_system_scope_and_context.adoc index c528e907..4ba4c3ec 100644 --- a/docs/src/03_system_scope_and_context.adoc +++ b/docs/src/03_system_scope_and_context.adoc @@ -1,75 +1,16 @@ ifndef::imagesdir[:imagesdir: ../images] - [[section-system-scope-and-context]] == System Scope and Context - - -[role="arc42help"] -**** -.Contents -System scope and context - as the name suggests - delimits your system (i.e. your scope) from all its communication partners -(neighboring systems and users, i.e. the context of your system). It thereby specifies the external interfaces. - -If necessary, differentiate the business context (domain specific inputs and outputs) from the technical context (channels, protocols, hardware). - -.Motivation -The domain interfaces and technical interfaces to communication partners are among your system's most critical aspects. Make sure that you completely understand them. - -.Form -Various options: - -* Context diagrams -* Lists of communication partners and their interfaces. - - -.Further Information - -See https://docs.arc42.org/section-3/[Context and Scope] in the arc42 documentation. - -**** - - === Business Context - -[role="arc42help"] -**** -.Contents -Specification of *all* communication partners (users, IT-systems, ...) with explanations of domain specific inputs and outputs or interfaces. -Optionally you can add domain specific formats or communication protocols. - -.Motivation -All stakeholders should understand which data are exchanged with the environment of the system. - -.Form -All kinds of diagrams that show the system as a black box and specify the domain interfaces to communication partners. - -Alternatively (or additionally) you can use a table. -The title of the table is the name of your system, the three columns contain the name of the communication partner, the inputs, and the outputs. - -**** - **** -**** +image::BusinessContext.png[align="center",title="Business Context",link="BusinessContext.png] -=== Technical Context +The WIQ application will communicate with the WikiData API through REST HTTP calls using SPARQL for the queries. It will ask the API for information that will later be used for generating the questions that will be shown to the player. This information will come in the form of text, images or audio. -[role="arc42help"] -**** -.Contents -Technical interfaces (channels and transmission media) linking your system to its environment. In addition a mapping of domain specific input/output to the channels, i.e. an explanation which I/O uses which channel. - -.Motivation -Many stakeholders make architectural decision based on the technical interfaces between the system and its context. Especially infrastructure or hardware designers decide these technical interfaces. - -.Form -E.g. UML deployment diagram describing channels to neighboring systems, -together with a mapping table showing the relationships between channels and input/output. - -**** - -**** +=== Technical Context +image::TechnicalContextDiagram.png[align="center",title="Technical Context",link="TechnicalContextDiagram.png] -**** +The WIQ application will be deployed together in the same server. The WIQ client will be deployed on a nginx web server. This client will communicate with the API through HTTPS REST calls and exchange information through JSON objects. The WIQ REST API will be run as a .jar file on the server and connect to a Database run on a postgresql docker container. The connection layer between the SpringBoot API and the database will be JPA. +The REST API will request information to the WikiData REST API through HTTPS calls passing a SPARQL query in order to retrieve data. -**** diff --git a/docs/src/04_solution_strategy.adoc b/docs/src/04_solution_strategy.adoc index 7bf03f7a..cfc818d4 100644 --- a/docs/src/04_solution_strategy.adoc +++ b/docs/src/04_solution_strategy.adoc @@ -3,30 +3,46 @@ ifndef::imagesdir[:imagesdir: ../images] [[section-solution-strategy]] == Solution Strategy +What follows is a summary of our solution's main decisions, and the approach we decided to use to create the system. -[role="arc42help"] -**** -.Contents -A short summary and explanation of the fundamental decisions and solution strategies, that shape system architecture. It includes +=== Technologies breakdown -* 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. +Regarding the technologies, we decided to use the following ones: -.Motivation -These decisions form the cornerstones for your architecture. They are the foundation for many other detailed decisions or implementation rules. + * **React** for the frontend, using the **Chakra UI** component library. Although the preferred way to use React is currently through a framework, we preferred this approach due to this being many of us first time using it, as well as a lack of experience using any framework in any of us. -.Form -Keep the explanations of such key decisions short. + ** As a consecuence of this, pure JavaScript is being used due to React 18 not supporting Typescript 5. -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. + * **PostgreSQL** as DBMS to store the information. We nearly immediately discarded using MongoDB due to many of us not having experience with it, and those that did preferring SQL. Many modern DBMS also include either JSON or JSONB data types, so using a DBMS whose main appeal is JSON and not many of us have experience with did not sit well with us. + * **Java SpringBoot** for the backend/API, it being a language we are all comfortable with. The server will easily support multithreading if needed due to SpringBoot being an abstraction over servlets, something we would be able only to simulate if we used Node.js as it uses a single-threaded event loop. -.Further Information +=== Organizational breakdown -See https://docs.arc42.org/section-4/[Solution Strategy] in the arc42 documentation. +Currently, we have been meeting twice a week, but that may change in the future. Most, if not all of us, were present for these meetings, and relevant decisions were also discussed on the side and between members, as well discussions related to opinions on some matter. Some of these meetings took place in person while others took place on a Discord Server. -**** +We also have a Whatsapp community for the team, and a Notion wiki. + +=== Important quality-related decisions + +|=== +|*Quality attribute pursued*|*Solution chosen* +|Privacy|All stored password will be hashed, both client-side and server-side, to avoid password disclosure. The client-side password is also intended to prevent password discoverage in case it is a repeated one. +|Robustness|Currently, all validations will take place server-side to avoid not being properly taken care of due to JavaScript desactivation, such as when using the NoScript plug-in +|Availability|Since Wikidata has a 1 minute limit related to the API, the backend will start querying it upon start and fill the database with questions to increase speed and thus improve user experience| +|=== + +=== Workflow + +We have divided ourselves in teams related to our own areas of expertise, but those divisions are indicative, and frontend teams may review or comment PRs if they wish, or vice versa. The frontend team may also ask input from the backend team if they wish, and the backend team may do the same. + +All in all, we strive to achieve a very flexible workflow in which everyone's input may be considered if they wish to give it. + +=== Code Style + +Regarding the code style, we must make two important distinctions: the frontend and backend. In the latter, we will mainly use Object Oriented Programming because our language of choice is Java, which strongly favours it. Regarding the former, it will be more of a case-by-case approach, as for instance, OOP-oriented React is deprecated in favor of a functional approach, but sometimes we may need OOP's strengths. + + * In the backend, the structure will be that of a typical Maven project. + * In the frontend, the structure will be quite different: + ** The `src/components` will contain single components which we may reuse. + ** The `src/pages` will contain the endpoints and will follow a simple structure. For instance, given a `/statistics/personal` and a `/statistics/general` endpoints, both will be independent React components that will return the page and be placed under the `src/pages/statistics` folder. \ No newline at end of file diff --git a/docs/src/05_building_block_view.adoc b/docs/src/05_building_block_view.adoc index df5c29c8..a58bcc73 100644 --- a/docs/src/05_building_block_view.adoc +++ b/docs/src/05_building_block_view.adoc @@ -5,208 +5,60 @@ ifndef::imagesdir[:imagesdir: ../images] == Building Block View -[role="arc42help"] -**** -.Content -The building block view shows the static decomposition of the system into building blocks (modules, components, subsystems, classes, interfaces, packages, libraries, frameworks, layers, partitions, tiers, functions, macros, operations, data structures, ...) as well as their dependencies (relationships, associations, ...) - -This view is mandatory for every architecture documentation. -In analogy to a house this is the _floor plan_. - -.Motivation -Maintain an overview of your source code by making its structure understandable through -abstraction. - -This allows you to communicate with your stakeholder on an abstract level without disclosing implementation details. - -.Form -The building block view is a hierarchical collection of black boxes and white boxes -(see figure below) and their descriptions. - -image::05_building_blocks-EN.png["Hierarchy of building blocks"] - -*Level 1* is the white box description of the overall system together with black -box descriptions of all contained building blocks. - -*Level 2* zooms into some building blocks of level 1. -Thus it contains the white box description of selected building blocks of level 1, together with black box descriptions of their internal building blocks. - -*Level 3* zooms into selected building blocks of level 2, and so on. - - -.Further Information - -See https://docs.arc42.org/section-5/[Building Block View] in the arc42 documentation. - -**** === Whitebox Overall System [role="arc42help"] **** -Here you describe the decomposition of the overall system using the following white box template. It contains - - * an overview diagram - * a motivation for the decomposition - * black box descriptions of the contained building blocks. For these we offer you alternatives: - - ** use _one_ table for a short and pragmatic overview of all contained building blocks and their interfaces - ** use a list of black box descriptions of the building blocks according to the black box template (see below). - Depending on your choice of tool this list could be sub-chapters (in text files), sub-pages (in a Wiki) or nested elements (in a modeling tool). - - - * (optional:) important interfaces, that are not explained in the black box templates of a building block, but are very important for understanding the white box. -Since there are so many ways to specify interfaces why do not provide a specific template for them. - In the worst case you have to specify and describe syntax, semantics, protocols, error handling, - restrictions, versions, qualities, necessary compatibilities and many things more. -In the best case you will get away with examples or simple signatures. - +This is the overall view of the application. The diagram is composed of 3 elements that will interact between each other. **** -_****_ - -Motivation:: +_**Overview Diagram**_ -__ +image::BusinessContext.png["Overall view of the business context"] +Motivation:: +This will be the general sketch of the elements interacting inside the application, including the external elements that will include the application. 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: +* **Player:** This is the user that will be playing with our application. They will need to be authenticated to be able to play. +* **WIQ Application:** This is the main application that will reproduce how the game will work. This part will be more detailed in the following parts. +* **WikiData API:** This is an external API, which will provide us with the information to produce the questions. -[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. **** - -==== - -[role="arc42help"] -**** -Here you describe -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 - -**** - -__ - -__ - -_<(Optional) Quality/Performance Characteristics>_ - -_<(Optional) Directory/File Location>_ - -_<(Optional) Fulfilled Requirements>_ - -_<(optional) Open Issues/Problems/Risks>_ - - - - -==== - -__ - -==== - -__ - - -==== - -... - -==== - +Important Interfaces:: +This part will be more detailed later, since the structure of the different interfaces/classes has not been discussed by the team yet. === Level 2 [role="arc42help"] **** -Here you can specify the inner structure of (some) building blocks from level 1 as white boxes. - -You have to decide which building blocks of your system are important enough to justify such a detailed description. -Please prefer relevance over completeness. Specify important, surprising, risky, complex or volatile building blocks. -Leave out normal, simple, boring or standardized parts of your system -**** - -==== White Box __ - -[role="arc42help"] -**** -...describes the internal structure of _building block 1_. +Here is an specification of the inner structure of the WIQ Application. **** -__ - -==== White Box __ +==== White Box _WIQ Application_ - -__ - -... - -==== White Box __ - - -__ - - - -=== Level 3 +image::ContainerDiagram.png["Container for the WIQ System"] [role="arc42help"] **** -Here you can specify the inner structure of (some) building blocks from level 2 as white boxes. - -When you need more detailed levels of your architecture please copy this -part of arc42 for additional levels. +This diagram describes the internal organization of the WIQ Application. **** +Motivation:: +An inner view on the WIQ Application and its components inside. How the WIQ application will be structured inside and its main components. -==== White Box <_building block x.1_> - -[role="arc42help"] +Contained Building Blocks:: **** -Specifies the internal structure of _building block x.1_. +* **WIQ Client:** This is the connection between the user and the application. It will allow the users to play the WIQ game. This part will be developed in React with Typescript for its clear component structure, simplified code quality and separation of concerns. +* **WIQ REST API:** This is the part responsible for managing the users that log into the application, managing also the logic of the game and sending the request to the Wikidata API for the question generation. This part is going to be developed in Springboot due to its foundations on the Java programming language, which is the language that the developers find the easiest to develop in. +* **WIQ Database:** This is where the most important data is going to be stored. Such as, users questions and other game info that will be specified in the future. The database we chose to use is PostgreSQL, since it is compatible with Docker and it's an object-relational kind of database, which is easier for the developers to use. Another alternative would've been to use MySQL. **** +Important Interfaces:: +This part will be more detailed later, since the structure of the different interfaces/classes has not been discussed by the team yet. -__ - - -==== White Box <_building block x.2_> - -__ - - - -==== White Box <_building block y.1_> - -__ diff --git a/docs/src/06_runtime_view.adoc b/docs/src/06_runtime_view.adoc index e10f375b..44dc3513 100644 --- a/docs/src/06_runtime_view.adoc +++ b/docs/src/06_runtime_view.adoc @@ -2,64 +2,95 @@ ifndef::imagesdir[:imagesdir: ../images] [[section-runtime-view]] == Runtime View +Here we can see what the main workflow of main parts of the project. +=== General Game's life cycle +* This diagram shows how should the application behave for an expected normal case scenario. -[role="arc42help"] -**** -.Contents -The runtime view describes concrete behavior and interactions of the system’s building blocks in form of scenarios from the following areas: +[plantuml,"Game's life cycle diagram",png] +---- +@startuml Game's life cycle + +actor Client + +skinparam Style strictuml +skinparam SequenceMessageAlignment center -* important use cases or features: how do building blocks execute them? -* interactions at critical external interfaces: how do building blocks cooperate with users and neighboring systems? -* operation and administration: launch, start-up, stop -* error and exception scenarios +Client --> API : start game +loop One question + API --> QuestionRetriever : ask for question + QuestionRetriever --> QuestionDB : querying question -Remark: The main criterion for the choice of possible scenarios (sequences, workflows) is their *architectural relevance*. It is *not* important to describe a large number of scenarios. You should rather document a representative selection. + QuestionDB --> QuestionRetriever : return first question and all answers + QuestionRetriever --> API : return first question and all answers -.Motivation -You should understand how (instances of) building blocks of your system perform their job and communicate at runtime. -You will mainly capture scenarios in your documentation to communicate your architecture to stakeholders that are less willing or able to read and understand the static models (building block view, deployment view). + API --> Client : return first question and all answers + Client -> API : send chosen answer + API --> API : check answer is correct + API --> Client : inform user guessed right +end loop One question -.Form -There are many notations for describing scenarios, e.g. -* numbered list of steps (in natural language) -* activity diagrams or flow charts -* sequence diagrams -* BPMN or EPCs (event process chains) -* state machines -* ... +API --> Client : inform user guessed right last question +API --> API : update ranking +API --> Client : show ranking +@enduml +---- + +=== Sign Up +[plantuml,"Sign up diagram",png] +---- +@startuml sign up -.Further Information +actor Client -See https://docs.arc42.org/section-6/[Runtime View] in the arc42 documentation. +skinparam Style strictuml +skinparam SequenceMessageAlignment center -**** +Client --> API : enters credentials +API --> BD : check credentials unused +API --> BD : register user +BD --> Client : return user token -=== +@enduml +---- +=== Login +[plantuml,"Login diagram",png] +---- +@startuml login -* __ -* __ +actor Client +skinparam Style strictuml +skinparam SequenceMessageAlignment center -It is possible to use a sequence diagram: +Client --> API : enters credentials +API --> BD : check credentials correct +BD --> API : return user token +API --> BD : save SWT +API --> Client : return user token -[plantuml,"Sequence diagram",png] +@enduml ---- -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 + +=== Question Generation +[plantuml,"Question generation diagram",png] ---- +@startuml question generator +skinparam Style strictuml +skinparam SequenceMessageAlignment center -=== +QuestionGenerator --> WikiDataQS : querying correct answer +QuestionGenerator <-- WikiDataQS : return correct answer -=== ... +QuestionGenerator --> WikiDataQS : querying wrong answers +QuestionGenerator <-- WikiDataQS : return wrong answers + +QuestionGenerator --> QuestionDB : store question +QuestionGenerator --> QuestionDB : store correct answer +QuestionGenerator --> QuestionDB : store wrong answers + +@enduml +---- -=== diff --git a/docs/src/07_deployment_view.adoc b/docs/src/07_deployment_view.adoc index 22b45c27..1b555d1d 100644 --- a/docs/src/07_deployment_view.adoc +++ b/docs/src/07_deployment_view.adoc @@ -2,93 +2,39 @@ ifndef::imagesdir[:imagesdir: ../images] [[section-deployment-view]] - == Deployment View -[role="arc42help"] -**** -.Content -The deployment view describes: - - 1. technical infrastructure used to execute your system, with infrastructure elements like geographical locations, environments, computers, processors, channels and net topologies as well as other infrastructure elements and - -2. mapping of (software) building blocks to that infrastructure elements. - -Often systems are executed in different environments, e.g. development environment, test environment, production environment. In such cases you should document all relevant environments. - -Especially document a deployment view if your software is executed as distributed system with more than one computer, processor, server or container or when you design and construct your own hardware processors and chips. - -From a software perspective it is sufficient to capture only those elements of an infrastructure that are needed to show a deployment of your building blocks. Hardware architects can go beyond that and describe an infrastructure to any level of detail they need to capture. - -.Motivation -Software does not run without hardware. -This underlying infrastructure can and will influence a system and/or some -cross-cutting concepts. Therefore, there is a need to know the infrastructure. - -.Form - -Maybe a highest level deployment diagram is already contained in section 3.2. as -technical context with your own infrastructure as ONE black box. In this section one can -zoom into this black box using additional deployment diagrams: - -* UML offers deployment diagrams to express that view. Use it, probably with nested diagrams, -when your infrastructure is more complex. -* When your (hardware) stakeholders prefer other kinds of diagrams rather than a deployment diagram, let them use any kind that is able to show nodes and channels of the infrastructure. - - -.Further Information - -See https://docs.arc42.org/section-7/[Deployment View] in the arc42 documentation. - -**** +image::DeploymentDiagram.png[align="center",title="Deployment Diagram",link="DeploymentDiagram.png] === Infrastructure Level 1 -[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:: -__ +The above diagram shows the initial version of the architecture and the division between its components. We will be using a simple client-server architecture, and the server will be querying Wikidata for the questions. By separating the architecture in this way we enforce a clear separation between the client/frontend and the server/backend, which benefits the system as a whole because so long the common API is implemented, the implementations themselves shall remain interchangeable. Quality and/or Performance Features:: -__ +As stated before, we consider the main advantage of this architecture the interchangeability of the components. There remain details to be scratched out though, but this is still an initial version. Mapping of Building Blocks to Infrastructure:: -__ + * The webapp/frontend/client is contained within the `webapp` subfolder. + * The API/backend is contained within the `api` subfolder. + ** The database will be generated on deployment. + ** Wikidata is an external component, so although it is an important part of the deployment architecture, it is something we do not have access to changing. === 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. -**** - -==== __ +==== Frontend/Client -__ +This component is self-contained and does not require much explanation. -==== __ +==== API/Backend -__ +===== Server -... +Our main idea is that the server will be a self-contained .jar file with all the dependencies required within. It will communicate with the database and periodically query Wikidata to generate questions until a certain number has been obtained once per minute to fill up the database and improve speed. -==== __ +===== Database -__ +The database will contain the data used by the system. Therefore, it will contain user data, as well as the data related to the questions and their answers. The databases to store the questions (and therefore the answers) and the user data might be different, though. diff --git a/docs/src/08_concepts.adoc b/docs/src/08_concepts.adoc index 591ccf1f..b14a2f16 100644 --- a/docs/src/08_concepts.adoc +++ b/docs/src/08_concepts.adoc @@ -3,71 +3,91 @@ ifndef::imagesdir[:imagesdir: ../images] [[section-concepts]] == Cross-cutting Concepts - -[role="arc42help"] -**** -.Content -This section describes overall, principal regulations and solution ideas that are relevant in multiple parts (= cross-cutting) of your system. -Such concepts are often related to multiple building blocks. -They can include many different topics, such as - -* models, especially domain models -* architecture or design patterns -* rules for using specific technology -* principal, often technical decisions of an overarching (= cross-cutting) nature -* implementation rules - - -.Motivation -Concepts form the basis for _conceptual integrity_ (consistency, homogeneity) of the architecture. -Thus, they are an important contribution to achieve inner qualities of your system. - -Some of these concepts cannot be assigned to individual building blocks, e.g. security or safety. - - -.Form -The form can be varied: - -* concept papers with any kind of structure -* cross-cutting model excerpts or scenarios using notations of the architecture views -* sample implementations, especially for technical concepts -* reference to typical usage of standard frameworks (e.g. using Hibernate for object/relational mapping) - -.Structure -A potential (but not mandatory) structure for this section could be: - -* Domain concepts -* User Experience concepts (UX) -* Safety and security concepts -* Architecture and design patterns -* "Under-the-hood" -* development concepts -* operational concepts - -Note: it might be difficult to assign individual concepts to one specific topic -on this list. - -image::08-Crosscutting-Concepts-Structure-EN.png["Possible topics for crosscutting concepts"] - - -.Further Information - -See https://docs.arc42.org/section-8/[Concepts] in the arc42 documentation. -**** - - -=== __ - -__ - - - -=== __ - -__ - -... - -=== __ - -__ +.Domain Model +This is the first version of the diagram, it will be updated if needed. + +[plantuml,"ConceptsDomainModel1",png] +---- +@startuml + +enum Category { + HISTORY + GEOGRAPHY + SCIENCE +} + +enum Type { + TEXT + IMAGE + AUDIO +} + +class Question{ + id: long + content: String + answers: List + correct: Answer + category: Category + language: String + Type: Type +} + +class User{ + answeredQuestions: int +} + +class UserStat{ +} + +class Answer { + text: String + category: Category + Type: Type +} + +class Game { + user: User + questions: List +} + + +class Ranking << Singleton >> { + +} + +User o--> Question +User "1" --> "1" UserStat +Game o--> Question +Game "n" --> "n" User +Question "n" --> "n" Answer +Ranking "1" --> "n" User + +@enduml +---- + +|=== +| Class | Explanation +| Question | The model of the questions, has a type to specify if it is text, image or audio. Stores both right and wrong answers +| User | The people using the application, they have statistics and take part in a ranking to compete +| Answer | Models each possible answer, created to reuse answers that are common to different questions, as well as distractors +| Game | It is created when the user starts a game and destroyed just when it ends. +|=== + +.Architecture and design patterns +We decided to use a React based frontend with BootSpring for the backend, which will follow the model view controller pattern to make the code clear. + +.User Experience +As this is a game, the focus must be in user experience so players can have an enjoyable experience, for achieving this, the response time should be as low as possible and the interfaces should be intuitive and beautiful. + +.Safety and Security concepts: +Authentication is done in SpringBoot3. Passwords must be hashed both in client and in API to ensure as much security as possible. + +.Robustness: +It is desired to make the application as independant as possible from Wikidata. This way, if it is down our application can still manage to be available for our users. +In order to archieve this, we will implement two modules regarding questions, one for retrieving it from Wikidata and storing it in our own DB and another for getting questions from it. + +.Development concepts: +Our code will be deployed within an Azure's Virtual Machine using continuous integration. + +.Under-the-hood: +Regarding Data persistence, our project has two DB, one for storing questions as stated before while the other one will be in charge of storing any other meaningful data for the game such us users or game's histories. diff --git a/docs/src/09_architecture_decisions.adoc b/docs/src/09_architecture_decisions.adoc index 51e9aad9..9bf87c3b 100644 --- a/docs/src/09_architecture_decisions.adoc +++ b/docs/src/09_architecture_decisions.adoc @@ -4,32 +4,20 @@ ifndef::imagesdir[:imagesdir: ../images] == Architecture Decisions -[role="arc42help"] -**** -.Contents -Important, expensive, large scale or risky architecture decisions including rationales. -With "decisions" we mean selecting one alternative based on given criteria. +During the application development process, decisions had to be made as issues emerged. The most interesting design decisions are reflected in this architectural records: -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). +|=== +|*Decision* |*Explanation* -Avoid redundancy. -Refer to section 4, where you already captured the most important decisions of your architecture. +|React +|Offers a powerful combination of performance, flexibility, and developer experience, making it a popular choice for building modern web applications. One of the members of the group has already worked with it in the past. It allows us to build a good user interface for the application. -.Motivation -Stakeholders of your system should be able to comprehend and retrace your decisions. +|SpringBoot +|This choice is based on the extensive experience accumulated by our team in developing with Java, as well as the familiarity and comfort offered by the tools and practices associated with the Spring Boot ecosystem. -.Form -Various options: +|PostgreSQL +|We have chosen to use the PostgreSQL database instead of MongoDB due to the relational nature of PostgreSQL, which offers a robust and coherent structure for storing and relating data. We made this decision to ensure data integrity, perform complex queries, and maintain consistency in our storage operations. -* 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. - -**** +|React Libraries +|To enhance the efficiency and effectiveness of our development process, we've taken proactive steps to incorporate specific libraries into our project. These carefully chosen libraries, meticulously outlined in detail within issue #16. +|=== diff --git a/docs/src/10_quality_requirements.adoc b/docs/src/10_quality_requirements.adoc index 68475e80..33d49327 100644 --- a/docs/src/10_quality_requirements.adoc +++ b/docs/src/10_quality_requirements.adoc @@ -2,72 +2,32 @@ ifndef::imagesdir[:imagesdir: ../images] [[section-quality-scenarios]] == 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. - -**** - === Quality Tree +This quality tree is a high-level overview of the quality goals and requirements. The Quality tree uses "quality" as a root while the rest of the quality categories will be displayed as branches. -[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. - - -**** +image:10_Quality_Tree.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. -**** +To obtain a measurable system response to stimulus corresponding to the various quality branches outlined in the mindmap, we will use quality scenarios. Scenarios make quality requirements concrete and allow to more easily measure or decide whether they are fulfilled. + +==== Usage Scenarios +[options="header",cols="1,3,1"] +|=== +|Quality attribute|Scenario|Priority +| Functional suitability | Users shall be able to register, log in, play the quiz, and access historical data without encountering errors or glitches. | High, Medium +| Security | User data shall be securely handled. Robust authentication mechanisms shall be in place for user registration and login. API access points for user information and generated questions shall be secured with proper authorization. | High, High +| Reliability | The system shall reliably generate accurate and diverse questions from Wikidata. User registrations, logins, and game data storage shall be handled without errors. | High, Medium +| Availability | The system shall be available 99.99% of the time when a user attempts to access it. | High, High +| Performance efficiency | The system shall deliver optimal performance, ensuring responsive interactions for users. It shall efficiently generate questions from Wikidata and handle real-time gameplay with up to N concurrent users. | High, High +| Usability | The system shall provide a user-friendly interface, allowing users to register, log in, and play the game with a learning time of less than 4 hours. | High, Medium +| Compatibility | The system shall be compatible with various web browsers and devices, providing a seamless experience for users regardless of their choice of platform. It shall be well-optimized for different screen sizes and functionalities. | High, Medium +| Transferability | The system shall allow for easy transfer of user data and game-related information through its APIs. | Medium, High +| Testability | The unit tests shall have at least 75% coverage. | High, Medium +|=== +==== Change Scenarios +[options="header",cols="1,3,1"] +|=== +|Quality attribute|Scenario|Priority +| Maintainability | The system shall be designed and implemented in a way that allows for easy maintenance and updates. | High, Medium +| Maintainability | The code of the system shall be well-documented, and modular, allowing for efficient troubleshooting and modifications. | High, Medium +|=== \ No newline at end of file diff --git a/docs/src/11_technical_risks.adoc b/docs/src/11_technical_risks.adoc index dc5575fc..0b9cbec2 100644 --- a/docs/src/11_technical_risks.adoc +++ b/docs/src/11_technical_risks.adoc @@ -4,22 +4,20 @@ ifndef::imagesdir[:imagesdir: ../images] == Risks and Technical Debts -[role="arc42help"] -**** -.Contents -A list of identified technical risks or technical debts, ordered by priority +|=== +|*Risk* |*Explanation* | *Mitigation proposed* -.Motivation -“Risk management is project management for grown-ups” (Tim Lister, Atlantic Systems Guild.) +|Little knowledge of the technologies to be used +|For most of the members of the team, is the first time working with technologies as React or Wikidata +|Explore technologies documentation to familiarize ourselves with the technology, and seek examples of use. -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. +|Lack of time +|We may face time constraints in fulfilling all the requirements for each deliverable and meeting every deadline. +|Try to maintain a steady and sustainable development pace. Prioritize building functional components initially, then iterate and enhance from there. -.Form -List of risks and/or technical debts, probably including suggested measures to minimize, mitigate or avoid risks or reduce technical debts. +|Coordination and responsability problems +|It is probably the first time involvement in developing a project from scratch, including decisions on architecture, design, and implementation, introduces various challenges. Misunderstandings regarding tasks and version control management errors can result in individuals inadvertently disrupting the work of others. Additionally, the necessity to make numerous decisions and reach agreements increases the likelihood of errors, potentially consuming significant time and effort. +|To ensure effective collaboration and organization, adhere to the teachers' instructions concerning GitHub, including utilizing features such as issues and pull requests, and maintain a disciplined approach to your work. Furthermore, leverage the collective knowledge and suggestions of every team member, integrating them with your existing expertise. +|=== - -.Further Information - -See https://docs.arc42.org/section-11/[Risks and Technical Debt] in the arc42 documentation. - -**** +In terms of technical debt, it's likely to be significant due to our lack of familiarity with the majority of the technologies involved for most of the team. Both Wikidata and React present considerable challenges, and we anticipate accumulating substantial technical debt in both areas. At present, our only strategy for mitigation is to search for potential solutions online. \ No newline at end of file diff --git a/docs/src/12_glossary.adoc b/docs/src/12_glossary.adoc index 192b2353..6bf7565d 100644 --- a/docs/src/12_glossary.adoc +++ b/docs/src/12_glossary.adoc @@ -3,40 +3,17 @@ ifndef::imagesdir[:imagesdir: ../images] [[section-glossary]] == Glossary -[role="arc42help"] -**** -.Contents -The most important domain and technical terms that your stakeholders use when discussing the system. - -You can also see the glossary as source for translations if you work in multi-language teams. - -.Motivation -You should clearly define your terms, so that all stakeholders - -* have an identical understanding of these terms -* do not use synonyms and homonyms - - -.Form - -A table with columns and . - -Potentially more columns in case you need translations. - - -.Further Information - -See https://docs.arc42.org/section-12/[Glossary] in the arc42 documentation. - -**** [cols="e,2e" options="header"] |=== |Term |Definition -| -| +|React +|An open-source JavaScript library for developing user interfaces. It can be used to develop web applications, and it has to be complemented with other libraries to develop full-fledged products. + +|SpringBoot +|Java Spring Boot (Spring Boot) is a tool that makes developing web application and microservices with Spring Framework faster and easier through three core capabilities: Autoconfiguration, an opinionated approach to configuration, the ability to create standalone applications. -| -| +|PostgreSQL +|Object-relational database management system (ORDMBS), which means that it has relational capabilities and an object-oriented design |=== diff --git a/docs/src/13_annex.adoc b/docs/src/13_annex.adoc new file mode 100644 index 00000000..855febbd --- /dev/null +++ b/docs/src/13_annex.adoc @@ -0,0 +1,79 @@ +ifndef::imagesdir[:imagesdir: ../images] + +[[section-annex]] +== Annex +=== Functional Requirements +==== Users Sign up. +[none or no-bullet] +* FR-USU 1. The system shall allow an unregistered user to register in the application. +* FR-USU 2. The system shall request the necessary data to register the new user. +[none or no-bullet] +** FR-USU 2.1. The system shall request the following mandatory data to register the new user: +[none or no-bullet] +*** FR-USU 2.1.1. Username. +*** FR-USU 2.1.2. Email address. +*** FR-USU 2.1.3. Password. +* FR-USU 3. The system shall not allow the user to be registered when any value entered by the new user is invalid. +* FR-USU 4. When all the values entered by the new user are valid, the system shall check if the user is already registered in the persistence system. +[none or no-bullet] +** FR-USU 4.1. When a user with the same data is already found in the persistence system, the user shall not be able to create a new account since it already exists. +** FR-USU 4.2. When no user matching the data is found in the persistence system. +[none or no-bullet] +*** FR-USU 4.2.1. The new user shall be registered in the system. + +==== Users Log in. +[none or no-bullet] +* FR-ULI 1. The system must allow an unidentified user to log in. +[none or no-bullet] +** FR-ULI 1.1. The system shall request the email address as the user identifier. +[none or no-bullet] +*** FR-ULI 1.1.1. The system must check that its format is valid. +*** FR-ULI 1.1.2. It is a mandatory field. +** FR-ULI 1.2. The system shall request the user's password. +[none or no-bullet] +*** FR-ULI 1.2.1. It is a mandatory field. +** FR-ULI 1.3. The system shall automatically validate the entered data to verify when it corresponds to a registered user account. +[none or no-bullet] +*** FR-ULI 1.3.1. When the user is not stored in the persistence system, an error message shall be displayed. +*** FR-ULI 1.3.2. When the user exists in the persistence system, but the passwords do not match, a message shall be displayed to the user notifying them of the error. +*** FR-ULI 1.3.3. When the user is stored in the persistence system and the passwords match, the user shall be logged in. +* FR-ULI 2. The system must allow users who are logged in to log out. + +==== Data management by the user. +[none or no-bullet] +* FR-DMU 1. The system shall allow all registered users to access their historical data from their participation. +[none or no-bullet] +** FR-DMU 1.1. Registered users shall be able to access the number of games they have played. +** FR-DMU 1.2. Registered users shall be able to access the number of questions they have answered correctly. +** FR-DMU 1.3. Registered users shall be able to access the number of questions they have answered incorrectly. +** FR-DMU 1.4. Registered users shall be able to access the time they have spent within the system. +** FR-DMU 1.5. Registered users shall be able to access the ranking of the game. + +==== Play to WIQ. +[none or no-bullet] +* FR-PWIQ 1. The system shall only allow registered users to play the WIQ game. +* FR-PWIQ 2. The game consists of nine rounds. +[none or no-bullet] +** FR-PWIQ 2.1. In each round, the system shall automatically generate a question to the registered user. +** FR-PWIQ 2.2. In each round, the system shall provide the registered user with four automatically generated possible answers. +** FR-PWIQ 2.3. In each round, there shall always be only one correct answer. +** FR-PWIQ 2.4. The system shall automatically end the game after completing the ninth round. +* FR-PWIQ 3. The registered user must respond to the question before the specified time expires. +[none or no-bullet] +** FR-PWIQ 3.1. When the specified time has not ended, and the registered user has provided an answer: +[none or no-bullet] +*** FR-PWIQ 3.1.1. The system shall check if the answer is correct. +[none or no-bullet] +**** FR-PWIQ 3.1.1.1. When the answer is correct: +[none or no-bullet] +***** FR-PWIQ 3.1.1.1.1. The registered user shall earn 10 points. +***** FR-PWIQ 3.1.1.1.2. When the registered user is in the ninth round, the system shall end the game. +***** FR-PWIQ 3.1.1.1.3. When the registered user is not in the ninth round, the system shall move to the next round. +**** FR-PWIQ 3.1.1.2. When the answer is incorrect: +[none or no-bullet] +***** FR-PWIQ 3.1.1.2.1. When the registered user is in the ninth round, the system shall end the game. +***** FR-PWIQ 3.1.1.2.2. When the registered user is not in the ninth round, the system shall move to the next round. +** FR-PWIQ 3.2. When the specified time has ended: +[none or no-bullet] +*** FR-PWIQ 3.2.1. When the registered user is in the ninth round, the system shall end the game. +*** FR-PWIQ 3.2.2. When the registered user is not in the ninth round, the system shall move to the next round. \ No newline at end of file