diff --git a/README.md b/README.md index 19a056a..9ca7eb3 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,19 @@ # wiq_en3a -Members: -- Sergio Truébano Robles -> uo289930@uniovi.es -- Pedro Limeres Granado -> uo282763@uniovi.es -- Alberto Guerra Rodas -> UO282421@uniovi.es -- Ángel Macías Rodríguez -> uo289362@uniovi.es -- Rita Fernández-Catuxo Ortiz -> uo284185@uniovi.es -- Vira Terletska -> viraterletska2005@gmail.com -- Sergio Llenderrozos Piñera -> uo283367@uniovi.es +## Welcome to WIQ👩‍🎓👨‍🎓 + +The WIQ is a web application where you can show off your knowledge. + +Creat an account or log in if you are already a member and start the engaging quiz! +Enjoy the variaty of questions, which are automatically generated from a vast pool of data available in Wikidata🌎. Each question offers multiple-choice options, including correct answer and several distractors🔍. Choose a right answer and win the prize🏆. Stay sharp and focused, there are also the time limits, --> the clock is ticking🕐 ⏳. + + +The more you know the more you win 🥇! +Play with your friends and compare the scores. Who is the smartest❓ + +🤓Let the game begin!👀🧠 + + [![Deploy on release](https://github.com/Arquisoft/wiq_en3a/actions/workflows/release.yml/badge.svg)](https://github.com/Arquisoft/wiq_en3a/actions/workflows/release.yml) [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=Arquisoft_wiq_en3a&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=Arquisoft_wiq_en3a) @@ -15,7 +21,7 @@ Members: 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. +➡This repo is a basic application composed of several components. - **Gateway service**. Express service that is exposed to the public and serves as a proxy to the two previous ones. - **User service**. Express service that handles the insertion of new users in the system. @@ -24,7 +30,7 @@ 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 +## Quick start guide 🏁 ### Using docker @@ -40,7 +46,7 @@ and launch it with docker compose: docker compose --profile dev up --build ``` -### Starting Component by component +### Starting Component by component🔍 First, start the database. Either install and run Mongo or run it using docker: @@ -54,7 +60,7 @@ Lastly, go to the webapp directory and launch this component with `npm install` After all the components are launched, the app should be available in localhost in port 3000. -## Deployment +## Deployment➡ For the deployment, we have several options. @@ -64,7 +70,7 @@ Other options include using the container services that most cloud services prov 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 +### 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: @@ -86,7 +92,7 @@ sudo curl -L "https://github.com/docker/compose/releases/download/1.28.5/docker- sudo chmod +x /usr/local/bin/docker-compose ``` -### Continuous delivery (GitHub Actions) +### 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. @@ -121,3 +127,13 @@ This action uses three secrets that must be configured in the repository: - 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. + +## 👩‍💻Members: + +- Sergio Truébano Robles -> uo289930@uniovi.es +- Pedro Limeres Granado -> uo282763@uniovi.es +- Alberto Guerra Rodas -> UO282421@uniovi.es +- Ángel Macías Rodríguez -> uo289362@uniovi.es +- Rita Fernández-Catuxo Ortiz -> uo284185@uniovi.es +- Vira Terletska -> uo305097@uniovi.es +- Sergio Llenderrozos Piñera -> uo283367@uniovi.es diff --git a/docs/images/03_business_context.png b/docs/images/03_business_context.png new file mode 100644 index 0000000..021e185 Binary files /dev/null and b/docs/images/03_business_context.png differ diff --git a/docs/images/10-Quality-Tree-EN.png b/docs/images/10-Quality-Tree-EN.png new file mode 100644 index 0000000..dbae1bf Binary files /dev/null and b/docs/images/10-Quality-Tree-EN.png differ diff --git a/docs/package-lock.json b/docs/package-lock.json index ab1646f..1b11ca1 100644 --- a/docs/package-lock.json +++ b/docs/package-lock.json @@ -9,6 +9,8 @@ "version": "1.0.0", "dependencies": { "gh-pages": "^3.2.3", + "graphviz": "^0.0.9", + "plantuml": "^0.0.2", "shx": "^0.3.3" } }, @@ -68,11 +70,32 @@ "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz", "integrity": "sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg==" }, + "node_modules/cross-spawn": { + "version": "7.0.3", + "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.3.tgz", + "integrity": "sha512-iRDPJKUPVEND7dHPO8rkbOnPpyDygcDFtWjpeWNCgy8WP2rXcxXL8TskReQl6OrB2G7+UJrags1q15Fudc7G6w==", + "dependencies": { + "path-key": "^3.1.0", + "shebang-command": "^2.0.0", + "which": "^2.0.1" + }, + "engines": { + "node": ">= 8" + } + }, "node_modules/email-addresses": { "version": "3.1.0", "resolved": "https://registry.npmjs.org/email-addresses/-/email-addresses-3.1.0.tgz", "integrity": "sha512-k0/r7GrWVL32kZlGwfPNgB2Y/mMXVTq/decgLczm/j34whdaspNrZO8CnXPf1laaHxI6ptUlsnAxN+UAPw+fzg==" }, + "node_modules/end-of-stream": { + "version": "1.4.4", + "resolved": "https://registry.npmjs.org/end-of-stream/-/end-of-stream-1.4.4.tgz", + "integrity": "sha512-+uw1inIHVPQoaVuHzRyXd21icM+cnt4CzD5rW+NC1wjOUSTOs+Te7FOv7AhN7vS9x/oIyhLP5PR1H+phQAHu5Q==", + "dependencies": { + "once": "^1.4.0" + } + }, "node_modules/escape-string-regexp": { "version": "1.0.5", "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-1.0.5.tgz", @@ -81,6 +104,28 @@ "node": ">=0.8.0" } }, + "node_modules/execa": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/execa/-/execa-4.1.0.tgz", + "integrity": "sha512-j5W0//W7f8UxAn8hXVnwG8tLwdiUy4FJLcSupCg6maBYZDpyBvTApK7KyuI4bKj8KOh1r2YH+6ucuYtJv1bTZA==", + "dependencies": { + "cross-spawn": "^7.0.0", + "get-stream": "^5.0.0", + "human-signals": "^1.1.1", + "is-stream": "^2.0.0", + "merge-stream": "^2.0.0", + "npm-run-path": "^4.0.0", + "onetime": "^5.1.0", + "signal-exit": "^3.0.2", + "strip-final-newline": "^2.0.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sindresorhus/execa?sponsor=1" + } + }, "node_modules/filename-reserved-regex": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/filename-reserved-regex/-/filename-reserved-regex-2.0.0.tgz", @@ -159,6 +204,20 @@ "url": "https://github.com/sponsors/ljharb" } }, + "node_modules/get-stream": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/get-stream/-/get-stream-5.2.0.tgz", + "integrity": "sha512-nBF+F1rAZVCu/p7rjzgA+Yb4lfYXrpl7a6VmJrU8wF9I1CKvP/QwPNZHnOlwbTkY6dvtFIzFMSyQXbLoTQPRpA==", + "dependencies": { + "pump": "^3.0.0" + }, + "engines": { + "node": ">=8" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/gh-pages": { "version": "3.2.3", "resolved": "https://registry.npmjs.org/gh-pages/-/gh-pages-3.2.3.tgz", @@ -219,6 +278,17 @@ "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.11.tgz", "integrity": "sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==" }, + "node_modules/graphviz": { + "version": "0.0.9", + "resolved": "https://registry.npmjs.org/graphviz/-/graphviz-0.0.9.tgz", + "integrity": "sha512-SmoY2pOtcikmMCqCSy2NO1YsRfu9OO0wpTlOYW++giGjfX1a6gax/m1Fo8IdUd0/3H15cTOfR1SMKwohj4LKsg==", + "dependencies": { + "temp": "~0.4.0" + }, + "engines": { + "node": ">=0.6.8" + } + }, "node_modules/hasown": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/hasown/-/hasown-2.0.0.tgz", @@ -230,6 +300,14 @@ "node": ">= 0.4" } }, + "node_modules/human-signals": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/human-signals/-/human-signals-1.1.1.tgz", + "integrity": "sha512-SEQu7vl8KjNL2eoGBLF3+wAjpsNfA9XMlXAYj/3EdaNfAlxKthD1xjEQfGOUhllCGGJVNY34bRr6lPINhNjyZw==", + "engines": { + "node": ">=8.12.0" + } + }, "node_modules/inflight": { "version": "1.0.6", "resolved": "https://registry.npmjs.org/inflight/-/inflight-1.0.6.tgz", @@ -263,6 +341,22 @@ "url": "https://github.com/sponsors/ljharb" } }, + "node_modules/is-stream": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/is-stream/-/is-stream-2.0.1.tgz", + "integrity": "sha512-hFoiJiTl63nn+kstHGBtewWSKnQLpyb155KHheA1l39uvtO9nWIop1p3udqPcUd/xbF1VLMO4n7OI6p7RbngDg==", + "engines": { + "node": ">=8" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/isexe": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz", + "integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==" + }, "node_modules/jsonfile": { "version": "4.0.0", "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-4.0.0.tgz", @@ -301,6 +395,19 @@ "url": "https://github.com/sponsors/sindresorhus" } }, + "node_modules/merge-stream": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/merge-stream/-/merge-stream-2.0.0.tgz", + "integrity": "sha512-abv/qOcuPfk3URPfDzmZU1LKmuw8kT+0nIHvKrKgFrwifol/doWcdA4ZqsWQ8ENrFKkd67Mfpo/LovbIUsbt3w==" + }, + "node_modules/mimic-fn": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/mimic-fn/-/mimic-fn-2.1.0.tgz", + "integrity": "sha512-OqbOk5oEQeAZ8WXWydlu9HJjz9WVdEIvamMCcXmuqUYjTknH/sqsWvhQ3vgwKFRR1HpjvNBKQ37nbJgYzGqGcg==", + "engines": { + "node": ">=6" + } + }, "node_modules/minimatch": { "version": "3.1.2", "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.2.tgz", @@ -320,6 +427,17 @@ "url": "https://github.com/sponsors/ljharb" } }, + "node_modules/npm-run-path": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/npm-run-path/-/npm-run-path-4.0.1.tgz", + "integrity": "sha512-S48WzZW777zhNIrn7gxOlISNAqi9ZC/uQFnRdbeIHhZhCA6UqpkOT8T1G7BvfdgP4Er8gF4sUbaS0i7QvIfCWw==", + "dependencies": { + "path-key": "^3.0.0" + }, + "engines": { + "node": ">=8" + } + }, "node_modules/object-assign": { "version": "4.1.1", "resolved": "https://registry.npmjs.org/object-assign/-/object-assign-4.1.1.tgz", @@ -336,6 +454,20 @@ "wrappy": "1" } }, + "node_modules/onetime": { + "version": "5.1.2", + "resolved": "https://registry.npmjs.org/onetime/-/onetime-5.1.2.tgz", + "integrity": "sha512-kbpaSSGJTWdAY5KPVeMOKXSrPtr8C8C7wodJbcsd51jRnmD+GZu8Y0VoU6Dm5Z4vWr0Ig/1NKuWRKf7j5aaYSg==", + "dependencies": { + "mimic-fn": "^2.1.0" + }, + "engines": { + "node": ">=6" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/p-limit": { "version": "2.3.0", "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-2.3.0.tgz", @@ -385,6 +517,14 @@ "node": ">=0.10.0" } }, + "node_modules/path-key": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz", + "integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==", + "engines": { + "node": ">=8" + } + }, "node_modules/path-parse": { "version": "1.0.7", "resolved": "https://registry.npmjs.org/path-parse/-/path-parse-1.0.7.tgz", @@ -428,6 +568,24 @@ "node": ">=8" } }, + "node_modules/plantuml": { + "version": "0.0.2", + "resolved": "https://registry.npmjs.org/plantuml/-/plantuml-0.0.2.tgz", + "integrity": "sha512-3YzQJUO1Yg+mDckTm3Ht5Q8bmtN8g3M9LD8fXqiqHDW3vzUpHrUe9lxVY6AT1I50w7FdOned0hhJno4JBIku2g==", + "dependencies": { + "execa": "^4.0.0", + "get-stream": "^5.1.0" + } + }, + "node_modules/pump": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/pump/-/pump-3.0.0.tgz", + "integrity": "sha512-LwZy+p3SFs1Pytd/jYct4wpv49HiYCqd9Rlc5ZVdk0V+8Yzv6jR5Blk3TRmPL1ft69TxP0IMZGJ+WPFU2BFhww==", + "dependencies": { + "end-of-stream": "^1.1.0", + "once": "^1.3.1" + } + }, "node_modules/rechoir": { "version": "0.6.2", "resolved": "https://registry.npmjs.org/rechoir/-/rechoir-0.6.2.tgz", @@ -463,6 +621,25 @@ "semver": "bin/semver.js" } }, + "node_modules/shebang-command": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz", + "integrity": "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==", + "dependencies": { + "shebang-regex": "^3.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/shebang-regex": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz", + "integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==", + "engines": { + "node": ">=8" + } + }, "node_modules/shelljs": { "version": "0.8.5", "resolved": "https://registry.npmjs.org/shelljs/-/shelljs-0.8.5.tgz", @@ -494,6 +671,19 @@ "node": ">=6" } }, + "node_modules/signal-exit": { + "version": "3.0.7", + "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-3.0.7.tgz", + "integrity": "sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ==" + }, + "node_modules/strip-final-newline": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/strip-final-newline/-/strip-final-newline-2.0.0.tgz", + "integrity": "sha512-BrpvfNAE3dcvq7ll3xVumzjKjZQ5tI1sEUIKr3Uoks0XUl45St3FlatVqef9prk4jRDzhW6WZg+3bk93y6pLjA==", + "engines": { + "node": ">=6" + } + }, "node_modules/strip-outer": { "version": "1.0.1", "resolved": "https://registry.npmjs.org/strip-outer/-/strip-outer-1.0.1.tgz", @@ -516,6 +706,14 @@ "url": "https://github.com/sponsors/ljharb" } }, + "node_modules/temp": { + "version": "0.4.0", + "resolved": "https://registry.npmjs.org/temp/-/temp-0.4.0.tgz", + "integrity": "sha512-IsFisGgDKk7qzK9erMIkQe/XwiSUdac7z3wYOsjcLkhPBy3k1SlvLoIh2dAHIlEpgA971CgguMrx9z8fFg7tSA==", + "engines": [ + "node >=0.4.0" + ] + }, "node_modules/trim-repeated": { "version": "1.0.0", "resolved": "https://registry.npmjs.org/trim-repeated/-/trim-repeated-1.0.0.tgz", @@ -535,6 +733,20 @@ "node": ">= 4.0.0" } }, + "node_modules/which": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz", + "integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==", + "dependencies": { + "isexe": "^2.0.0" + }, + "bin": { + "node-which": "bin/node-which" + }, + "engines": { + "node": ">= 8" + } + }, "node_modules/wrappy": { "version": "1.0.2", "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz", diff --git a/docs/package.json b/docs/package.json index 22e2370..226f9de 100644 --- a/docs/package.json +++ b/docs/package.json @@ -4,12 +4,13 @@ "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", + "graphviz": "^0.0.9", + "plantuml": "^0.0.2", + "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 ddb2ae3..bbe1446 100644 --- a/docs/src/01_introduction_and_goals.adoc +++ b/docs/src/01_introduction_and_goals.adoc @@ -3,11 +3,16 @@ ifndef::imagesdir[:imagesdir: ../images] [[section-introduction-and-goals]] == Introduction and Goals +The WIQ web application is developed by HappySw for RTVE to create an experimental version of the Saber y Ganar quiz show. +The primary goal of WIQ is to provide users with an engaging platform where they can participate in quiz games, +answer questions generated from Wikidata, and win prizes. + +This document outlines the essential requirements guiding the software architects and development team in creating WIQ. + [role="arc42help"] **** -Describes the relevant requirements and the driving forces that software architects and development team must consider. +Describes the relevant requirements that software architects and development team must consider. These include - * underlying business goals, * essential features, * essential functional requirements, @@ -16,6 +21,17 @@ These include **** === Requirements Overview + +The system aims to fulfill the following essential requirements: + +1. Users can register and login to participate in quiz games. +2. Questions are automatically generated from data available in Wikidata. +3. Users receive historical data of their participation, including the number of games played, questions passed and failed, and timestamps. +4. Each question must be answered within a specific time limit. +5. Questions consist of one correct answer and several distractors, all automatically generated. +6. Access to user information and generated questions is available through an API. + + [role="arc42help"] **** @@ -43,6 +59,14 @@ See https://docs.arc42.org/section-1/[Introduction and Goals] in the arc42 docum === Quality Goals +|=== +| Quality Goal | Description +| Reliability | Ensure consistent and accurate question generation and user data management. +| Performance | Optimize system response times and capacity to handle multiple user interactions simultaneously. +| Security | Implement robust security measures to protect user data and prevent unauthorized access. +|=== + + [role="arc42help"] **** .Contents @@ -86,8 +110,14 @@ Table with role names, person names, and their expectations with respect to the **** [options="header",cols="1,2,2"] + + |=== -|Role/Name|Contact|Expectations -| __ | __ | __ -| __ | __ | __ +| Role/Name | Contact | Expectations +| Users | N/A | Intuitive and enjoyable quiz experience +| RTVE | Project Manager | Reliable and engaging platform for users +| HappySw Team | Development Team | Clear documentation and reliable system performance |=== + + + diff --git a/docs/src/02_architecture_constraints.adoc b/docs/src/02_architecture_constraints.adoc index 226e501..6c8153e 100644 --- a/docs/src/02_architecture_constraints.adoc +++ b/docs/src/02_architecture_constraints.adoc @@ -3,6 +3,34 @@ ifndef::imagesdir[:imagesdir: ../images] [[section-architecture-constraints]] == Architecture Constraints +When designing the WIQ application, there are several constraints that must be taken into consideration, as they will have a significant impact on the overall design of the application and the architectural decisions. These constraints must be considered in order to ensure that the final product meets the needs and expectations of the users and stakeholders. The following table summarizes these constraints and provides a brief explanation for each one divided into technical, organizational and political constraints. + +=== Technical constraints +|=== +|Constraint|Explanation +| WikiData | Our application must generate questions automatically getting data from WikiData +| Docker | We are using docker for the deployment.It's a platform that allows you to package Our application and its dependencies into a standardized unit called a container. +| Azure | Azure is a cloud computing platform where we are going to host our WIQ application +| Version control and monitoring (GitHub) | For the WIQ application, GitHub is a useful tool for version control and collaboration among the team members working on the project. It allows easier coordination and organization of the development process, as well as keeping track of changes and contributions made by each team member. +| User Experience | The design of the application must make its use friendly and easy +| Test coverage | Code must meet a good test quality and coverage to ensure the expected outcome. +|=== + +=== Organizational constraints +|=== +|Constraint|Explanation +| Team | The project will be done in a team composed of 7 students, so work must be assigned accordingly. +| Git-based development | The project will be built around the Git workflow, so all tools used must be able to closely interact with this system. +| Meetings | The project’s development process must be reflected in the minutes of each meeting that happens. +| Delivery deadlines | There are 4 deliverables every 3 weeks that should be followed accordingly before the deployment of the application +|=== + +=== Political constraints +|=== +|Constraint|Explanation +| Documentation | We are going to use AsciiDoc and follow the Arc42 template. +| Language | The documentation and application will be developed in English. +|=== [role="arc42help"] **** diff --git a/docs/src/03_system_scope_and_context.adoc b/docs/src/03_system_scope_and_context.adoc index c528e90..6ac0574 100644 --- a/docs/src/03_system_scope_and_context.adoc +++ b/docs/src/03_system_scope_and_context.adoc @@ -48,9 +48,17 @@ The title of the table is the name of your system, the three columns contain the **** -**** +image::03_business_context.png["Business Context Diagram"] + +[cols="1,1,1" options="header"] +|=== +| **Partner** | **Input** | **Output** +| User | The user interacts with the WIQ web application using the front-end of the application. | The display of a page of the application with the questions and statistics. +| Database | Stores relevant information of the application (users, number of games, questions passed/failed, times…). | Retrieves the information that the application requires. +| Question generation | Questions generated from Wikidata. | These generated questions are sent to the application. +| Wikidata API | Receives a query linked to the question to be asked. | Returns the necessary information to formulate the question. +|=== -**** === Technical Context @@ -69,7 +77,30 @@ together with a mapping table showing the relationships between channels and inp **** **** +[cols="2,2"] +|=== +| **Component** | **Technologies Used** +| Front-end | HTML, CSS, JavaScript (Svelte/React) +| Back-end | .NET/node.js, API de Wikidata +| Database | MongoDB +| Arquitechture | Microservices +| Deployment and Maintenance | Docker +|=== **** **** +[cols="2,2"] +|=== +| **Component** | **Functionality** +| Front-end | User interaction and results display. +| Back-end | Logical processing, communication with external API and database. +| Database | Data storage. +| External API | Data query from Wikidata. +|=== + +In this flow: +- The user interacts with the user interface (front-end) through clicks and responses. +- The back-end processes the requests, consults the Wikidata API, and updates the screen. +- The channels are the HTTP connections between the components. +- The mapping evaluates the user’s responses in real time to provide an appropriate response. \ No newline at end of file diff --git a/docs/src/04_solution_strategy.adoc b/docs/src/04_solution_strategy.adoc index 8576b37..a58461f 100644 --- a/docs/src/04_solution_strategy.adoc +++ b/docs/src/04_solution_strategy.adoc @@ -4,6 +4,33 @@ ifndef::imagesdir[:imagesdir: ../images] == Solution Strategy This section will cover all the technological, architectural, design and organizational decisions made along the project for its appropiate development +[role="arc42help"] +**** +.Contents +A short summary and explanation of the fundamental decisions and solution strategies, that shape system architecture. It includes + +* 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. + +.Motivation +These decisions form the cornerstones for your architecture. They are the foundation for many other detailed decisions or implementation rules. + +.Form +Keep the explanations of such key decisions short. + +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. + + +.Further Information + +See https://docs.arc42.org/section-4/[Solution Strategy] in the arc42 documentation. + +**** + === Technologies * *React*: JavaScript library for web and native user interfaces. It allows developers to create interactive web applications by breaking down the UI into reusable components. React uses a declarative approach to efficiently update and render components, resulting in faster and more maintainable code. It's widely adopted in the industry due to its simplicity, performance, and robustness. * *Svelte*: modern JavaScript framework that compiles code at build time for efficient updates to the DOM. It emphasizes smaller bundle sizes and better performance, offering a simpler approach to building dynamic web applications compared to traditional frameworks like React or Vue. diff --git a/docs/src/05_building_block_view.adoc b/docs/src/05_building_block_view.adoc index df5c29c..4a10859 100644 --- a/docs/src/05_building_block_view.adoc +++ b/docs/src/05_building_block_view.adoc @@ -63,18 +63,165 @@ In the best case you will get away with examples or simple signatures. **** -_****_ + +[plantuml, format="png"] +---- +@startuml +title Scope & Context +left to right direction +' Define custom style for components +skinparam componentStyle uml2 + +' Define components as rectangles without default stereotypes +rectangle "WIQ" as WIQ +cloud "Wikidata API" as WikidataAPI +actor "User" as User + +' Define connections +User --> WIQ +WIQ --> WikidataAPI +@enduml +---- + + Motivation:: -__ +This is a basic introduction to the app, highlighting the external services it uses and how they work together. + +Contained Building Blocks:: + +[cols="1,2" options="header"] +|=== +| **Name** | **Responsibility** +| WIQ | It’s the main application, currently represented as a whitebox. The following sections will break it down in detail. +| WikidataAPI | External API used as the knowledge hub. +|=== + + +[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. +**** + + +==== + +[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>_ + + + + +==== + +__ + +==== + +__ + + +==== + +... + +==== +**** + +=== Level 1 + +[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 + +**** + +[plantuml, format=png] +.... +actor user as "User browser" +frame WIQ { + node Frontend + node UserManagement + node QuestionGeneration +} +cloud Wikidata as "Wikidata" + +user -- Frontend +Frontend -- UserManagement +Frontend -- QuestionGeneration +QuestionGeneration -- Wikidata +.... + + + +Motivation:: +The reasoning behind this separation is to achieve a modular architecture with clear separation of concerns. +It also allows to expose the user management and the question generation as APIs. Contained Building Blocks:: -__ + +[cols="1,2" options="header"] +|=== +| **Name** | **Responsibility** +| Frontend | Represents the user interface and manages the quiz logic of the application. +| User Management | Handles everything related to user accounts. +| Question Generator | Generates questions from Wikidata data and sends them to the frontend. +|=== Important Interfaces:: -__ + +[cols="1,2" options="header"] +|=== +| **Name** | **Description** +| Frontend <-> User Management | This interface defines how the frontend communicates with the User Management Service to log in, retrieve user data, or perform actions requiring authorization. +| Question Generator <-> Frontend | This interface defines how the Question Generator Service delivers processed questions to the frontend for display. +| Question Generator <-> Wikidata API | This interface represents the service fetching data from the Wikidata API. +|=== + [role="arc42help"] **** @@ -111,7 +258,7 @@ according the the following black box template: * (Optional) Fulfilled requirements (if you need traceability to requirements). * (Optional) Open issues/problems/risks -**** + __ @@ -143,7 +290,7 @@ __ ==== - +**** === Level 2 @@ -156,27 +303,53 @@ Please prefer relevance over completeness. Specify important, surprising, risky, Leave out normal, simple, boring or standardized parts of your system **** -==== White Box __ +==== White Box User Management Service [role="arc42help"] **** -...describes the internal structure of _building block 1_. +...describes the internal structure of the User Management Service. **** -__ +[plantuml, format="png"] +---- +@startuml +' Define custom style for components +skinparam componentStyle uml2 -==== White Box __ +' Define components as rectangles without default stereotypes +rectangle "User Management" as UserManagement +database "Users MongoDB Database" as MongoDB +' Define connections +UserManagement --> MongoDB -__ - -... +@enduml +---- -==== White Box __ +==== White Box Question Generation Service -__ +[role="arc42help"] +**** +...describes the internal structure of the Question Generation Service. +**** +[plantuml, format="png"] +---- +@startuml +' Define custom style for components +skinparam componentStyle uml2 + +' Define components as rectangles without default stereotypes +rectangle "Question Generation" as QuestionGeneration +database "Questions MongoDB Database" as MongoDB +cloud "Wikidata API" as WikidataAPI + +' Define connections +QuestionGeneration --> MongoDB +QuestionGeneration --> WikidataAPI +@enduml +---- === Level 3 diff --git a/docs/src/06_runtime_view.adoc b/docs/src/06_runtime_view.adoc index 388cbae..4faafae 100644 --- a/docs/src/06_runtime_view.adoc +++ b/docs/src/06_runtime_view.adoc @@ -42,6 +42,7 @@ UsersService -> DB: CreateUserData() DB -> UsersService: Confirm data UsersService -> UsersService: signUp() UsersService -> FrontEnd: Redirect to login page +@enduml ---- === Data retrieval from WikiData @@ -64,4 +65,6 @@ QuestionGenerator-> QuestionGenerator: popGameQuestions() QuestionGenerator-> FrontEnd: Send game FrontEnd -> User: Question 1 User-> FrontEnd: Answer 1 ----- \ No newline at end of file +---- + +=== diff --git a/docs/src/07_deployment_view.adoc b/docs/src/07_deployment_view.adoc index 22b45c2..8927d2a 100644 --- a/docs/src/07_deployment_view.adoc +++ b/docs/src/07_deployment_view.adoc @@ -5,6 +5,171 @@ ifndef::imagesdir[:imagesdir: ../images] == Deployment View +Our project is configurated using GitHub actions in such a way that every release that is made will trigger some unitary and end to end test, and an attempt to deploy the application over a server. +This will allow our team to achieve continuous deployment and delivery. + +=== Quick deployment guide + +Using your Azure account: + +* Create an Ubuntu-20.04 virtual machine from Azure link:https://www.portal.azure.com[www.portal.azure.com] +** Select an available location (usually Switzerland North, Zone 1, is available) +** Select the virtual machine "Standard B1s (1 vcpu, 1GiB of memory)" +** Set the username to `azureuser` +** Allow SSH on port 22 + +* Configure GitHub repository secrets with the server's information: +** Download the private key (.pem file) and paste all of its textual content over `DEPLOY_KEY`. Save the file for later configurations over SSH at the virtual machine. +** Check the public IP at Azure and paste it over `DEPLOY_HOST`. +** `DEPLOY_USER` does not need to be changed + +* Once the virtual machine is created and the repository is configured, go to Network Settings and add extra rules: +** Open port number 3000 for user services +** Open port number 8000 for accessing the web application +*** More services will be available in the future, so discussions will be made for additional ports supporting our services. + +* Configure the virtual machine connecting through SSH for using Docker: +** Use some tool for connecting to the server using SSH (PuTTY, MobaXterm...) +** Use the public IP address and the local .pem file for making the connection. +** Run the following commands for preparing the virtual machine: + ++ +[listing] +---- +sudo apt update +---- + ++ +[listing] +---- +sudo apt install apt-transport-https ca-certificates curl software-properties-common +---- + ++ +[listing] +---- +curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add - +---- + ++ +[listing] +---- +sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu focal stable" +---- + ++ +[listing] +---- +sudo apt update +---- + ++ +[listing] +---- +sudo apt install docker-ce +---- + ++ +[listing] +---- +sudo usermod -aG docker ${USER} +---- + ++ +[listing] +---- +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 +---- + ++ +[listing] +---- +sudo chmod +x /usr/local/bin/docker-compose +---- + +* Make a release in GitHub: +** On the right-hand side of the main Code section of our repository, there is a section called Releases. It will be needed to add a new version following the version naming convention. +** Once the release is made, some GitHub actions will be triggered, and the containers will be tested and running once everything finishes. +** If some test fails during the process, deployment will be automatically aborted. + + +=== Infrastructure +General view of system's infrastructure +[plantuml, target=deployment-diagram, format=png] +.... +actor client as "Client" +frame UbuntuServer { + frame Docker { + + + frame WebAPP { + node React + } + + frame NodeJSGateway { + node Authentication + + node Users + } + + frame MongoDB { + node UsersDatabase + + node ResultsDatabase + } + + frame .NET { + node RestAPI + } + } + + frame GitHub{ + + frame GitHubActions{ + node dockerCompose + } + + } +} + +.NET -- ResultsDatabase : MongoDB (port 27017) +NodeJSGateway -- UsersDatabase : MongoDB (port 27017) +WebAPP -- NodeJSGateway : (port 8000:8002) +WebAPP -- .NET : .NET (port TBD) +client -- WebAPP : Web Browser (port 3000) + +Docker -- GitHubActions : on release +.... + + +=== Infrastructure Level 1 - Azure Ubuntu Server + +The Ubuntu server allows us to have a isolated machine with the minimal required configuration and installations for running our services. +Having our server on Azure, allows us to minimize the costs of having that machine running, as well as to avoid taking care of some responsabilities such as security, availability or maintainance. + + +=== Infrastructure Level 2 - Docker + +Instead of having a virtual machine for running the whole application by itself, the application is splitted into different services that can be completely isolated. +Docker allows us to create containers with the minimum amount of resources needed for running that specific service, such that resources are not wasted and services that could be more used do not collapse others. Each container contains the specific docker image for running the specific service. +Each implemented service will be isolated at deploy time, so there is no need of making the services at the same programming language or following the same architectural patterns, and responses will be responded through different independent endpoints. + +The virtual machine will contain as many containers as services in the application. + +For now, the project contains: +** Web application service running on port 3000 +*** Gateway (middleware) service running on port 8000 +*** Users and authentication services running on ports 8001 and 8002 respectively +** Mongo DB server running on port 27017 +** Prometheus running on port 9090 for monitoring +** Grafana running on port 9091 for analytics and monitoring + + +=== Infrastructure Level 3 - GitHub actions + +GitHub actions will provide us with continuous automatic delivery and integration, automating the deployment phase at each release. + + [role="arc42help"] **** .Content @@ -92,3 +257,5 @@ __ ==== __ __ + + diff --git a/docs/src/09_architecture_decisions.adoc b/docs/src/09_architecture_decisions.adoc index 51e9aad..512a075 100644 --- a/docs/src/09_architecture_decisions.adoc +++ b/docs/src/09_architecture_decisions.adoc @@ -3,6 +3,28 @@ ifndef::imagesdir[:imagesdir: ../images] [[section-design-decisions]] == Architecture Decisions +Along the process of developing the application, decisions had to be taken as problems arise. +These are the initial decicision that we have made but they change during the course of the project +The following table contains some of the design decisions that were imposed to us due to the architectural constraints: + +.Imposed decisions +|=== +|Code|Decision|Advantages|Disadvantages +|ID1| React.js or Svelte | Quite easy to learn in comparison to other front-end libraries. Increasingly popular in the web.|Not all of us know about its usage +|ID2| MongoDB | It does not need to be started manually. Free and easy to understand|We are quite new with MongoDB. +|ID3| Docker | Fast deployment, ease of moving/maintaining your applications. Easy as we already have DockerFiles example|We do not have much experience using Docker +|ID4| PlantUML | Allows drawing diagrams very easily, with a simple syntax.|Does not allow as much control over the exact layout of the elements in the diagram as other tools. +|=== + +.Architectural Records +|=== +|Code |Context |Record + +|ADR1 | TBD | TBD + +|ADR2 | TBD | TBD + +|=== [role="arc42help"] **** diff --git a/docs/src/10_quality_requirements.adoc b/docs/src/10_quality_requirements.adoc index 68475e8..061e5e9 100644 --- a/docs/src/10_quality_requirements.adoc +++ b/docs/src/10_quality_requirements.adoc @@ -26,6 +26,7 @@ See https://docs.arc42.org/section-10/[Quality Requirements] in the arc42 docume **** === Quality Tree +image::10-Quality-Tree-EN.png["Quality Tree"] [role="arc42help"] **** @@ -44,6 +45,7 @@ The quality tree is a high-level overview of the quality goals and requirements: In any case the tree should include links to the scenarios of the following section. + **** === Quality Scenarios @@ -71,3 +73,64 @@ more precisely down to a level of scenarios that can be discussed and evaluated. .Form Tabular or free form text. **** + +*Usage scenarios* + +[options="header", cols="1,1,1,1"] +|=== +| Quality goal | Motivation | Usage scenario | Priority + +| *Reliability* +| The application must provide users with constistent performance and predictable results. +| When users access the web it must behave the same every time giving the almost equal results and response times. +| Very high + +| *Performance* +| The application must have a reasonable response time. Slow applications are not positively popular in society. +| The application must be able to give a fast response time to the users so the game is dynamic and entertaining. +| Very high + +| *Security* +| Our web must be secure not only to protect data but to provide a realiable solution to our users. If we can't assure our clients the web is secure, no one will use it. +| Data will be only accessible by its owner. If a user tries to access other people's information, the system will deny the operation, as data will be stored in a secure system. +| Very high + +| *Portability* +| To reach the maximum number of users the application must work in the maximum number of infrastructures. +| When users access the web from different browsers and devices, it must work and provide all the possible functionalities. +| Very high + +| *Usability* +| To make the website stand out from the competition, it must be easy to use, attract attention and be aestethic. +| When the user wants to do something in the application, he/she should be able to do it without difficulty, guided by the interface elements. +| Very high + +| *Testability* +| All features of the application must be testable in order to verify that the web built was the one asked for. +| The unit tests passed by the developers must generate an observable output. +| High + +| *Availability* +| The application must be available 24 hours a day all weeks. +| The user must be able to play at any time because it will be its free time. +| High + +|=== + + +*Change scenarios* + +[options="header", cols="1,1,1,1"] +|=== +| Quality goal | Motivation | Change scenario | Priority +| *Maintainability* +| An application should be maintainable to remain usable over the years and to be able to improve functionalities and to fix misfunctionalities. +| When developers must introduce a new feature to the web, they should be able to do it without changing the software architecture. +| High + +| *Maintainability* +| An application should be maintainable to remain usable over the years and to be able to improve functionalities and to fix misfunctionalities. +| When fixing errors and bugs on the system, developers should be able to do it without major consequences on the system. +| High + +|=== \ No newline at end of file diff --git a/docs/src/12_glossary.adoc b/docs/src/12_glossary.adoc index faff791..9cd9498 100644 --- a/docs/src/12_glossary.adoc +++ b/docs/src/12_glossary.adoc @@ -35,6 +35,39 @@ See https://docs.arc42.org/section-12/[Glossary] in the arc42 documentation. |=== |Term |Definition +|WIQ +|A web application where users can register and login in order to play. The game consists on answering a number of questions with different types and subjects obtaining a prize for each question well answered. + +|Wikidata +|It is a collaborative, free and open knowledge base that stores structured information. It aims to provide a common source of data that can be used by Wikimedia projects and anyone else, under a public domain license. + +|Saber y ganar +|It is a Spanish television quiz show. It involves contestants competing in several rounds of questions to test their knowledge in different categories. + +|Diagram +|A visual representation of information, data flow, processes, or systems using symbols, shapes, and lines to illustrate relationships, connections, and concepts. + +|Front-ent +|Refers to the part of a software application or website that users interact with directly. It encompasses the user interface, design elements, and functionality visible to users. + +|Back-end +|The behind-the-scenes part of a software application or website responsible for handling data processing, server-side logic, and database interactions. It includes the server, database, and application logic that users do not directly interact with. + +|Microservices +|An architectural approach to building software applications as a collection of small, loosely coupled services. Each service is designed to perform a specific business function and can be developed, deployed, and scaled independently. + +|Stakeholder +|Individuals or groups with an interest or concern in a project, product, or organization. Stakeholders may include any party affected by or involved in the outcomes of a particular initiative. + +|Docker +|A platform for developing, shipping, and running applications in containers. It allows developers to package applications and their dependencies into standardized units called containers, providing a consistent environment for software deployment across different computing environments. + +|MongoDB +|A popular open-source NoSQL database management system known for its flexibility, scalability, and ease of use. It stores data in a flexible, JSON-like format called BSON and is commonly used for applications requiring high-volume data storage and real-time data processing. + +|Svelte +|A modern JavaScript framework for building user interfaces. Unlike traditional frameworks that require the runtime presence of a virtual DOM, Svelte shifts the work to compile-time, resulting in highly optimized and efficient code with smaller bundle sizes. + |API (Application programming interface) |Set of rules and protocols that allows different software applications to communicate and interact with each other. APIs define the methods and data formats that applications can use to request and exchange information. They enable developers to access the functionality of other software components or services without having to understand their internal workings. APIs are commonly used to integrate third-party services, access data from remote servers, and build modular and interoperable software systems. diff --git a/package-lock.json b/package-lock.json new file mode 100644 index 0000000..59845ca --- /dev/null +++ b/package-lock.json @@ -0,0 +1,6 @@ +{ + "name": "wiq_en3a", + "lockfileVersion": 3, + "requires": true, + "packages": {} +}