diff --git a/docs/README.md b/docs/README.md index 61766e4..af1623e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,6 +1,6 @@ ## The documentation In this project, the documentation is compiled locally and deployed to GitHub pages. -The deployment url is: [https://arquisoft.github.io/wiq_0/](https://arquisoft.github.io/wiq_0/). +The deployment url is: [https://arquisoft.github.io/wiq_7/](https://arquisoft.github.io/wiq_7/). ### Documentation build For the documentation, we are going to use [AsciiDoc](https://asciidoc.org/) and [PlantUML](https://plantuml.com) and follow the [Arc42](https://github.com/arc42/arc42-template) template. If you want to be able to generate the doc locally you need to install Ruby, Java and some dependencies to translate the AsciiDoc code into html. If you are in Linux you can install Ruby and Java simply by executing: @@ -17,6 +17,8 @@ Once Ruby is working you can install some gems with `asciidoctor` and `asciidoct gem install asciidoctor asciidoctor-diagram ``` +If you include diagrams created with PlantUML, it is necessary to install [Graphviz](https://graphviz.org) to ensure they are generated correctly. + Now it is turn to install some dependencies in the `package.json` file inside the `docs` directory: ```shell @@ -30,6 +32,6 @@ npm run build The documentation will be generated under the `docs/build` directory. ### Documentation deployment -If we want to deploy it to GitHub pages, so it is accessible via [https://arquisoft.github.io/wiq_0/](https://arquisoft.github.io/wiq_0/), we need to execute `npm run deploy`. +If we want to deploy it to GitHub pages, so it is accessible via [https://arquisoft.github.io/wiq_7/](https://arquisoft.github.io/wiq_7/), we need to execute `npm run deploy`. If you check the `package.json` in this directory you can see how deploying is as easy as executing `gh-pages -d build`, which can be directly executed using `npm run deploy` in the docs directory. The `gh-pages` package is in charge of pushing the documentation generated directory (basically some htmls) to a special github branch called gh-pages. Everything pushed to this branch is accessible on the repository page. Note that we only want to push there the documentation. Also is important that the documentation build is not pushed to the other branches of the project. \ No newline at end of file diff --git a/docs/images/01_2_iso-25010-topics-EN.drawio.png b/docs/images/01_2_iso-25010-topics-EN.drawio.png deleted file mode 100644 index 548f6fa..0000000 Binary files a/docs/images/01_2_iso-25010-topics-EN.drawio.png and /dev/null differ diff --git a/docs/images/05_building_blocks-EN.png b/docs/images/05_building_blocks-EN.png deleted file mode 100644 index 0862b64..0000000 Binary files a/docs/images/05_building_blocks-EN.png and /dev/null differ diff --git a/docs/images/08-Crosscutting-Concepts-Structure-EN.png b/docs/images/08-Crosscutting-Concepts-Structure-EN.png deleted file mode 100644 index 5598a0b..0000000 Binary files a/docs/images/08-Crosscutting-Concepts-Structure-EN.png and /dev/null differ diff --git a/docs/index.adoc b/docs/index.adoc index 468be5f..bb171f6 100644 --- a/docs/index.adoc +++ b/docs/index.adoc @@ -6,7 +6,7 @@ // configure EN settings for asciidoc include::src/config.adoc[] -= image:arc42-logo.png[arc42] Template += image:arc42-logo.png[arc42] Wiq 7 Documentation :revnumber: 8.2 EN :revdate: January 2023 :revremark: (based upon AsciiDoc version) diff --git a/docs/package-lock.json b/docs/package-lock.json index ab1646f..ee7d0f2 100644 --- a/docs/package-lock.json +++ b/docs/package-lock.json @@ -8,7 +8,7 @@ "name": "docs", "version": "1.0.0", "dependencies": { - "gh-pages": "^3.2.3", + "gh-pages": "^6.1.1", "shx": "^0.3.3" } }, @@ -32,12 +32,9 @@ } }, "node_modules/async": { - "version": "2.6.4", - "resolved": "https://registry.npmjs.org/async/-/async-2.6.4.tgz", - "integrity": "sha512-mzo5dfJYwAn29PeiJ0zvwTo04zj8HDJj0Mn8TD7sno7q12prdbnasKJHhkm2c1LgrhlJ0teaea8860oxi51mGA==", - "dependencies": { - "lodash": "^4.17.14" - } + "version": "3.2.5", + "resolved": "https://registry.npmjs.org/async/-/async-3.2.5.tgz", + "integrity": "sha512-baNZyqaaLhyLVKm/DlvdW051MSgO6b8eVfIezl9E5PqWxFgzLm/wQntEW4zOytVburDEr0JlALEpdOFwvErLsg==" }, "node_modules/balanced-match": { "version": "1.0.2", @@ -54,9 +51,12 @@ } }, "node_modules/commander": { - "version": "2.20.3", - "resolved": "https://registry.npmjs.org/commander/-/commander-2.20.3.tgz", - "integrity": "sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ==" + "version": "11.1.0", + "resolved": "https://registry.npmjs.org/commander/-/commander-11.1.0.tgz", + "integrity": "sha512-yPVavfyCcRhmorC7rWlkHn15b4wDVgVmBA7kV4QVBsF7kv/9TKJAbAXVTxvTnwP8HHKjRCJDClKbciiYS7p0DQ==", + "engines": { + "node": ">=16" + } }, "node_modules/commondir": { "version": "1.0.1", @@ -69,9 +69,9 @@ "integrity": "sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg==" }, "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==" + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/email-addresses/-/email-addresses-5.0.0.tgz", + "integrity": "sha512-4OIPYlA6JXqtVn8zpHpGiI7vE6EQOAg16aGnDMIAlZVinnoZ8208tW1hAbjWydgN/4PLTT9q+O1K6AH/vALJGw==" }, "node_modules/escape-string-regexp": { "version": "1.0.5", @@ -134,16 +134,16 @@ } }, "node_modules/fs-extra": { - "version": "8.1.0", - "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-8.1.0.tgz", - "integrity": "sha512-yhlQgA6mnOJUKOsRUFsgJdQCvkKhcz8tlZG5HBQfReYZy46OwLcY+Zia0mtdHsOo9y/hP+CxMN0TU9QxoOtG4g==", + "version": "11.2.0", + "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-11.2.0.tgz", + "integrity": "sha512-PmDi3uwK5nFuXh7XDTlVnS17xJS7vW36is2+w3xcv8SVxiB4NyATf4ctkVY5bkSjX0Y4nbvZCq1/EjtEyr9ktw==", "dependencies": { "graceful-fs": "^4.2.0", - "jsonfile": "^4.0.0", - "universalify": "^0.1.0" + "jsonfile": "^6.0.1", + "universalify": "^2.0.0" }, "engines": { - "node": ">=6 <7 || >=8" + "node": ">=14.14" } }, "node_modules/fs.realpath": { @@ -160,16 +160,16 @@ } }, "node_modules/gh-pages": { - "version": "3.2.3", - "resolved": "https://registry.npmjs.org/gh-pages/-/gh-pages-3.2.3.tgz", - "integrity": "sha512-jA1PbapQ1jqzacECfjUaO9gV8uBgU6XNMV0oXLtfCX3haGLe5Atq8BxlrADhbD6/UdG9j6tZLWAkAybndOXTJg==", + "version": "6.1.1", + "resolved": "https://registry.npmjs.org/gh-pages/-/gh-pages-6.1.1.tgz", + "integrity": "sha512-upnohfjBwN5hBP9w2dPE7HO5JJTHzSGMV1JrLrHvNuqmjoYHg6TBrCcnEoorjG/e0ejbuvnwyKMdTyM40PEByw==", "dependencies": { - "async": "^2.6.1", - "commander": "^2.18.0", - "email-addresses": "^3.0.1", + "async": "^3.2.4", + "commander": "^11.0.0", + "email-addresses": "^5.0.0", "filenamify": "^4.3.0", "find-cache-dir": "^3.3.1", - "fs-extra": "^8.1.0", + "fs-extra": "^11.1.1", "globby": "^6.1.0" }, "bin": { @@ -264,9 +264,12 @@ } }, "node_modules/jsonfile": { - "version": "4.0.0", - "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-4.0.0.tgz", - "integrity": "sha512-m6F1R3z8jjlf2imQHS2Qez5sjKWQzbuuhuJ/FKYFRZvPE3PuHcSMVZzfsLhGVOkfd20obL5SWEBew5ShlquNxg==", + "version": "6.1.0", + "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-6.1.0.tgz", + "integrity": "sha512-5dgndWOriYSm5cnYaJNhalLNDKOqFwyDB/rr1E9ZsGciGvKPs8R2xYGCacuf3z6K1YKDz182fd+fY3cn3pMqXQ==", + "dependencies": { + "universalify": "^2.0.0" + }, "optionalDependencies": { "graceful-fs": "^4.1.6" } @@ -282,11 +285,6 @@ "node": ">=8" } }, - "node_modules/lodash": { - "version": "4.17.21", - "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz", - "integrity": "sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg==" - }, "node_modules/make-dir": { "version": "3.1.0", "resolved": "https://registry.npmjs.org/make-dir/-/make-dir-3.1.0.tgz", @@ -528,11 +526,11 @@ } }, "node_modules/universalify": { - "version": "0.1.2", - "resolved": "https://registry.npmjs.org/universalify/-/universalify-0.1.2.tgz", - "integrity": "sha512-rBJeI5CXAlmy1pV+617WB9J63U6XcazHHF2f2dbJix4XzpUF0RS3Zbj0FGIOCAva5P/d/GBOYaACQ1w+0azUkg==", + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/universalify/-/universalify-2.0.1.tgz", + "integrity": "sha512-gptHNQghINnc/vTGIk0SOFGFNXw7JVrlRUtConJRlvaw6DuX0wO5Jeko9sWrMBhh+PsYAZ7oXAiOnf/UKogyiw==", "engines": { - "node": ">= 4.0.0" + "node": ">= 10.0.0" } }, "node_modules/wrappy": { diff --git a/docs/package.json b/docs/package.json index 22e2370..7a3058d 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": "^6.1.1", + "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..ac4b21c 100644 --- a/docs/src/01_introduction_and_goals.adoc +++ b/docs/src/01_introduction_and_goals.adoc @@ -1,93 +1,64 @@ -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 -**** - -=== 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. +== Introduction and Goals -Keep these excerpts as short as possible. Balance readability of this document with potential redundancy w.r.t to requirements documents. +Saber y Ganar is the Software Architecture project developed by Ángel Luis Álvarez Iglesias (uo17919), under the supervision of Jorge Álvarez Fidalgo. +This project consists of an application that features a question-and-answer game, designed to be both engaging and educational. Additionally, the application offers a statistics tracking system, allowing registered users to view their own performance metrics and compare them with those of other players. -.Further Information +The application is built using the MERN stack, which includes MongoDB for the database, Express.js for the server-side framework, React for the front-end development, and Node.js for the runtime environment. -See https://docs.arc42.org/section-1/[Introduction and Goals] in the arc42 documentation. +=== Requirements Overview -**** +[cols="1,3", options="header"] +|=== +| Requirement Code | Description +| RE1 +| The system will have at least a web front-end which will be available and accessible through the web. +| RE2 +| Users will be able to register to the system and obtain the historical data from their participation: number of games, questions passed and failed, times, ... +| RE3 +| Questions will be automatically generated from data available in Wikidata. +| RE4 +| Questions have to be answered before some specific time. +| RE5 +| Each question will have one right answer and several incorrect ones or distractors. Both the right answer and the distractors should be automatically generated. +| RE6 +| The system will give access to the information about the users through an API. +| RE7 +| The system will give access to information about the generated questions through an API. +| RE8 +| Allow different game modes like the ones that appear in the quiz show page (Each wise man with his subject, Travel with us, The hot question, Discovering cities, ...). +|=== === 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 -**** +[cols="1,2,1", options="header"] +|=== +| Quality Objective | Implementation | Priority +| Usability +| To ensure the application is user-friendly, we will maintain a consistent design and emphasize predictability, making it easy to learn and providing a seamless user experience.| 5 +| Testability +| We will perform thorough tests to ensure the proper functioning of all services within the application. | 4 +| Performance +| We will strive to optimize resource usage within the application to ensure its performance remains fast and efficient. | 4 +| Reliability +| We will focus on building a robust application by implementing error-handling mechanisms and redundancy measures to ensure consistent performance and minimize downtime. | 3 +| Security +| The goal is to meet essential security standards to prevent unauthorized access to accounts and protect user information from exposure. However, this is not a primary objective of the project. | 1 +|=== === 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"] +[cols="1,2,2", options="header"] |=== -|Role/Name|Contact|Expectations -| __ | __ | __ -| __ | __ | __ +| Role | Description | Expectations +| Client +| Our client is RTVE, represented by the course instructors, who have requested the development of an application based on the "Saber y Ganar" TV show. | An application that fulfills all the requirements outlined in the section above. +| Development team +| The student uo17919. | Develop a comprehensive application as described in the lab practice guide. It must meet all specified requirements and clearly demonstrate the effort invested in the project. +| Users +| The target audience for the application (the players) who will test or use the final product. | A fun and well-functioning game that features a variety of questions to offer a challenging experience. +| Github users +| The users who will access the project repository on Github. | A well-documented project that is easy to understand and navigate, featuring high-quality code and a clear architecture. |=== diff --git a/docs/src/02_architecture_constraints.adoc b/docs/src/02_architecture_constraints.adoc index 226e501..cf6e5c7 100644 --- a/docs/src/02_architecture_constraints.adoc +++ b/docs/src/02_architecture_constraints.adoc @@ -1,27 +1,37 @@ -ifndef::imagesdir[:imagesdir: ../images] - [[section-architecture-constraints]] -== Architecture Constraints - - -[role="arc42help"] -**** -.Contents -Any requirement that constraints software architects in their freedom of design and implementation decisions or decision about the development process. These constraints sometimes go beyond individual systems and are valid for whole organizations and companies. - -.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. +== Architecture Constraints -**** +=== Technical Architecture Constraints + +[cols="1,2", options="header"] +|=== +| Technical architecture constraints | Description +| Web application +| As indicated in RE1, access to the application shall be through the web, so a web application must be developed rather than a desktop application. +| Wikidata +| As indicated in RE3, the questions shall be automatically generated from Wikidata data. +| Github +| The project shall be hosted in a GitHub repository created by the ArquiSoft organization for the Software Architecture course at the School of Software Engineering at the University of Oviedo. +| Github actions +| The project shall use GitHub Actions to automate the testing and deployment processes. +| Docker +| The project shall use Docker to containerize the application. +|=== + +=== Organizational and Political Constraints + +[cols="1,2", options="header"] +|=== +| Organizational and political constraints | Description +| Development time | The team shall develop the application in accordance with the established deadlines, even if this means using alternative development technologies or altering the original architectural decisions. +| Compliance with privacy regulations | The application shall adhere to updated data privacy regulations to ensure the confidentiality of the contestants. +|=== + +=== Conventions + +[cols="1,2", options="header"] +|=== +| Conventions | Description +| Documentation | The development team shall use arc42 to document the application architecture, design decisions, and implementation details, ensuring ease of future updates and maintenance. +|=== diff --git a/docs/src/03_system_scope_and_context.adoc b/docs/src/03_system_scope_and_context.adoc index c528e90..4430e7f 100644 --- a/docs/src/03_system_scope_and_context.adoc +++ b/docs/src/03_system_scope_and_context.adoc @@ -1,75 +1,88 @@ -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. - -**** +== System Scope and Context === 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. +[plantuml, "business_context", svg] +---- +actor player +rectangle wiq as "wiq" +rectangle wikidata as "wikidata" -.Form -All kinds of diagrams that show the system as a black box and specify the domain interfaces to communication partners. +player -right-> wiq: interacts +wiq <-right-> wikidata: queries +---- -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. -**** - -**** - -**** +[cols="1,2" options="header"] +|=== +| Name | Description +| Player | The user who plays the game. +| Wiq | The application is used by players and interacts with Wikidata to automatically generate questions. +| Wikidata | Collaborative database of free knowledge that stores structured data (https://www.wikidata.org/). +|=== === Technical Context -[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. - -**** - -**** - -**** - -**** +[plantuml, "technical_context", svg] +---- +left to right direction + +actor user as "user" +Component web as "webApp" { + Component front as "Frontend" + Component "Services" { + Component gw as "Gateway" + Component userserv as "User service" + Component authserv as "Authentication service" + Component statsserv as "Statistic service" + Component questionserv as "Question service" + } +database mongo as "MongDB" +} +Component wikidata + +user <--> front: interact +front <--> gw: interact + +gw <--> userserv: register +gw <--> authserv: login +gw <--> statsserv: generate stats +gw <--> questionserv: generate questions + +userserv <--> mongo: read/write +authserv <--> mongo: read/write +statsserv <--> mongo: read/write +questionserv <--> mongo: read/write +questionserv <-l-> wikidata: query + +userserv -[hidden]l- authserv +authserv -[hidden]l- statsserv +statsserv -[hidden]l- questionserv +---- + +[cols="1,2" options="header"] +|=== +| Name | Description +| User +| The user who plays the game. +| WebApp +| The application is used by players and interacts with Wikidata to automatically generate questions. +| Frontend +| The user interface of the application. +| Gateway +| The entry point of the application. +| User service +| Manages user registration. +| Authentication service +| Manages user authentication. +| Statistic service +| Manages game statistics. +| Question service +| Handles the generation and formulation of game questions. +| MongoDB +| Database used to store the data of the application. +| Wikidata +| Collaborative database of free knowledge that stores structured data (https://www.wikidata.org/). +|=== diff --git a/docs/src/04_solution_strategy.adoc b/docs/src/04_solution_strategy.adoc index 7bf03f7..0b35dda 100644 --- a/docs/src/04_solution_strategy.adoc +++ b/docs/src/04_solution_strategy.adoc @@ -1,32 +1,45 @@ -ifndef::imagesdir[:imagesdir: ../images] - [[section-solution-strategy]] -== Solution Strategy - - -[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. +== Solution Strategy -**** +=== Technology decisions +[cols="1,2", options="header"] +|=== +| Technology | Description +| Git +| Software version control system +| GitHub +| Cloud-based service that hosts the aforementioned version control system, Git. +| Node.js +| Runtime environment for JavaScript that enables the development of scalable server-side applications. +| Express +| Framework for building web applications in Node.js. +| React +| JavaScript library that allows us to create interactive user interfaces easily. It is based on components. +| Docker +| Tool that simplifies the creation, deployment, and execution of applications using containers. Containers allow you to package an application with all its required components, such as libraries and other dependencies, and deploy it as a single package. +| Puppeteer +| Test automation tool for web browsers developed by Google. It allows control of the browser through an API. +|=== + +=== Decisions about the top-level decomposition of the system +A microservices architecture has been chosen, with distinct modules assigned to each functionality. This approach allows for better scalability, maintainability, and flexibility. + +=== Decisions on how to achieve quality goals +[cols="1,2", options="header"] +|=== +| Quality Goal | Implementation +| Usability +| The team will focus on designing a clear and accessible interface for all users. To achieve this, we will adhere to web usability standards and perform usability tests. +| Testability +| Unit tests and end-to-end (E2E) integration tests will be created to ensure the software is reliable, robust, and free of errors. +| Performance +| We will focus on optimizing the application's performance to ensure fast response times and efficient resource usage. This includes implementing performance best practices and monitoring the system to address any potential bottlenecks. +| Reliability +| Our goal is to ensure that the application operates consistently and without interruptions. This involves implementing robust error-handling mechanisms, conducting regular system tests, and designing the system to recover gracefully from failures. +| Security +| We will implement all necessary measures to secure our application. +|=== + +=== Relevant organizational decisions +The team will follow an agile development methodology to ensure flexibility and adaptability throughout the project. diff --git a/docs/src/05_building_block_view.adoc b/docs/src/05_building_block_view.adoc index df5c29c..5d9d47c 100644 --- a/docs/src/05_building_block_view.adoc +++ b/docs/src/05_building_block_view.adoc @@ -1,212 +1,126 @@ -ifndef::imagesdir[:imagesdir: ../images] - [[section-building-block-view]] - == 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. - +=== Whitebox of the Overall System +[plantuml, "whitebox_overall_system", svg] +---- +actor user +component wiq as "wiq" +component wikidata as "wikidata" -.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. - -**** - -_****_ +user -right-> wiq: interact +wiq <-right-> wikidata: query +---- Motivation:: - -__ - +WIQ is a web application where users can register and start playing. The game consists of answering a series of questions of various types and topics, with a reward for each correct answer. An important aspect of the system is that the questions will be automatically generated from Wikidata data (https://www.wikidata.org/). Contained Building Blocks:: -__ - -Important Interfaces:: -__ - -[role="arc42help"] -**** -Insert your explanations of black boxes from level 1: - -If you use tabular form you will only describe your black boxes with name and -responsibility according to the following schema: - [cols="1,2" options="header"] |=== -| **Name** | **Responsibility** -| __ | __ -| __ | __ +| Name | Responsibility +| User | The user interacts with the application. +| WIQ | The application is used by the user and communicates with Wikidata to generate questions automatically. +| Wikidata | Collaborative database of free knowledge that stores structured data. |=== +=== Level 1 +[plantuml, "level_1", svg] +---- +actor user as "user" +component web as "WebApp" { + component front as "Frontend" + component back as "Backend" + database mongo as "MongDB" +} -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>_ - - - - -==== - -__ +Component wikidata as "wikidata" -==== - -__ - - -==== - -... - -==== +user <-right-> front: interact +front <-right-> back: interact +back <-right-> mongo: read/write +back <-down-> wikidata: query +---- +Motivation:: +The main components of WIQ are shown here. +Contained Building Blocks:: +[cols="1,2" options="header"] +|=== +| Name | Responsibility +| User | The user interacts with the application. +| Frontend Web | Component responsible for the system's user interface. It provides access to the system's functionalities through a web browser. +| Backend | It contains the business logic and data management of the system. It exposes endpoints to interact with clients through an API. +| MongoDB | NoSQL database management system that uses a flexible data model based on JSON documents with dynamic schemas. +| Wikidata | Collaborative database of free knowledge that stores structured data. +|=== === Level 2 +[plantuml, "level_2", svg] +---- +left to right direction + +actor user as "user" +component web as "webApp" { + component front as "Frontend" + component "Services" { + component gw as "Gateway" + component userserv as "User service" + component authserv as "Authentication service" + component statsserv as "Statistic service" + component questionserv as "Question service" + } +database mongo as "MongDB" +} +component wikidata as "wikidata" + +user <--> front: interact +front <--> gw: interact + +gw <--> userserv: register +gw <--> authserv: login +gw <--> statsserv: generate stats +gw <--> questionserv: generate questions + +userserv <--> mongo: read/write +authserv <--> mongo: read/write +statsserv <--> mongo: read/write +questionserv <--> mongo: read/write +questionserv <-l-> wikidata: query + +userserv -[hidden]l- authserv +authserv -[hidden]l- statsserv +statsserv -[hidden]l- questionserv +---- -[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_. -**** - -__ - -==== White Box __ - - -__ - -... - -==== White Box __ - - -__ - - - -=== Level 3 - -[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. -**** - - -==== White Box <_building block x.1_> - -[role="arc42help"] -**** -Specifies the internal structure of _building block x.1_. -**** - - -__ - - -==== White Box <_building block x.2_> - -__ - - - -==== White Box <_building block y.1_> +Motivation:: +A detailed breakdown of the WIQ microservices is presented. -__ +Contained Building Blocks:: +[cols="1,2" options="header"] +|=== +| Name | Responsibility +| User +| The user who plays the game. +| WebApp +| The application is used by players and interacts with Wikidata to automatically generate questions. +| Frontend +| The user interface of the application. +| Gateway +| The entry point of the application. +| User service +| Manages user registration. +| Authentication service +| Manages user authentication. +| Statistic service +| Manages game statistics. +| Question service +| Handles the generation and formulation of game questions. +| MongoDB +| Database used to store the data of the application. +| Wikidata +| Collaborative database of free knowledge that stores structured data (https://www.wikidata.org/). +|=== diff --git a/docs/src/06_runtime_view.adoc b/docs/src/06_runtime_view.adoc index e10f375..6d90487 100644 --- a/docs/src/06_runtime_view.adoc +++ b/docs/src/06_runtime_view.adoc @@ -1,65 +1,94 @@ -ifndef::imagesdir[:imagesdir: ../images] - [[section-runtime-view]] -== Runtime View - - -[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: - -* 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 - -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. - -.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). -.Form -There are many notations for describing scenarios, e.g. +== Runtime View -* numbered list of steps (in natural language) -* activity diagrams or flow charts -* sequence diagrams -* BPMN or EPCs (event process chains) -* state machines -* ... +=== User Registration +User registration in the application is managed through the user microservice (userservice). The user enters a username and password, and if the user is created successfully, a confirmation message is displayed. Otherwise, an error message is shown. -.Further Information +[plantuml, "user_registration", svg] +---- +actor user +participant webapp as "webApp" +participant gw as "gateway" +participant userserv as "user serv" +participant mongo as "MongoDB" + +user --> webapp: fill registration form +webapp -> gw: post request +gw -> userserv: post request +userserv -> mongo: create user +mongo -> userserv: 200 +userserv -> gw: 200 +gw -> webapp: 200 +webapp --> user: confirmation message -See https://docs.arc42.org/section-6/[Runtime View] in the arc42 documentation. +---- -**** +=== Login -=== +The application's login is managed through the authentication microservice (authservice). The user enters their credentials, and if the information is correct, a view of the application with the available options is displayed. +[plantuml, "login", svg] +---- +actor user +participant webapp as "webApp" +participant gw as "gateway" +participant authserv as "auth serv" +participant mongo as "MongoDB" + +user --> webapp: enter credentials +webapp -> gw: get request +gw -> authserv: get request +authserv -> mongo: find user +mongo -> authserv: 200 +authserv -> gw: 200 +gw -> webapp: 200 +webapp --> user: confirmation message +---- -* __ -* __ +=== Play -It is possible to use a sequence diagram: +The quiz game is managed through the authentication microservice (questionservice). The user starts a new game, and a new question with its corresponding answers is displayed. -[plantuml,"Sequence diagram",png] +[plantuml, "play", svg] ---- -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 +actor user +participant webapp as "webApp" +participant gw as "gateway" +participant qserv as "question serv" +participant mongo as "MongoDB" + +user --> webapp: start game +webapp -> gw: get request +gw -> qserv: get request +qserv -> mongo: find question +mongo -> qserv: 200 +qserv -> gw: 200 +gw -> webapp: 200 +webapp --> user: ask question +user --> webapp: answer question +webapp --> user: give feedback ---- -=== +=== Statistics -=== ... +The application's statistics module is handled by the statistics microservice (statsservice). Upon user request, the game statistics are presented in a view. -=== +[plantuml, "stats", svg] +---- +actor user +participant webapp as "webApp" +participant gw as "gateway" +participant statsserv as "stats serv" +participant mongo as "MongoDB" + +user --> webapp: enter stats page +webapp -> gw: get request +gw -> statsserv: get request +statsserv -> mongo: get stats +mongo -> statsserv: 200 +statsserv -> gw: 200 +gw -> webapp: 200 +webapp --> user: show stats view +---- diff --git a/docs/src/07_deployment_view.adoc b/docs/src/07_deployment_view.adoc index 22b45c2..0a56760 100644 --- a/docs/src/07_deployment_view.adoc +++ b/docs/src/07_deployment_view.adoc @@ -1,94 +1,70 @@ -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. - -**** - -=== 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:: - -__ - -Quality and/or Performance Features:: - -__ - -Mapping of Building Blocks to Infrastructure:: -__ - - -=== Infrastructure Level 2 - -[role="arc42help"] -**** -Here you can include the internal structure of (some) infrastructure elements from level 1. - -Please copy the structure from level 1 for each selected element. -**** - -==== __ - -__ - -==== __ - -__ - -... - -==== __ - -__ +[plantuml, "deployment_view", svg] +---- +actor User +left to right direction + +node "Ubuntu Azure VM" { + node "Docker" { + rectangle "WebApp" { + rectangle "Frontend" + rectangle "Gateway" + rectangle "User Service" + rectangle "Authentication Service" + rectangle "Statistic Service" + rectangle "Question Service" + } + database "MongoDB" + } +} + +rectangle "Wikidata" + +User <--> Frontend : interact +Frontend <--> Gateway + +Gateway <--> "User Service" +Gateway <--> "Authentication Service" +Gateway <--> "Statistic Service" +Gateway <--> "Question Service" + +"User Service" <--> MongoDB +"Authentication Service" <--> MongoDB +"Statistic Service" <--> MongoDB +"Question Service" <--> MongoDB +"Question Service" <-l-> Wikidata : query +---- + +[cols="1,2" options="header"] +|=== +| Element | Description +| User +| The actor who interacts with the application, representing the players. +| Azure +| The cloud platform where the application is deployed. +| Ubuntu +| The virtual machine on Azure running the Ubuntu operating system. +| Docker +| Technology used to containerize and deploy the microservices and the database. +| WebApp +| The main component of the web application, including the frontend and backend services. +| Frontend +| The user interface of the application, which the users directly interact with. +| Gateway +| The service that acts as an intermediary between the frontend and other backend services. +| User Service +| The service that handles user registration and management. +| Authentication Service +| The service responsible for user authentication. +| Statistic Service +| The service responsible for generating and managing user statistics. +| Question Service +| The service responsible for generating and managing the game questions. +| MongoDB +| The database where the application data is stored. +| Wikidata +| An external component that is queried to obtain additional data for the game questions. +|=== diff --git a/docs/src/08_concepts.adoc b/docs/src/08_concepts.adoc index 591ccf1..b9cbd11 100644 --- a/docs/src/08_concepts.adoc +++ b/docs/src/08_concepts.adoc @@ -1,73 +1,83 @@ -ifndef::imagesdir[:imagesdir: ../images] - [[section-concepts]] -== Cross-cutting Concepts +== Cross-cutting Concepts +This section describes overall, principal regulations and solution ideas that are relevant in multiple parts (= cross-cutting) of the system. -[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 +=== Domain concepts +**- Domain model**: The domain model, including the key classes and their most important attributes, is illustrated in the following diagram. -* 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 +[plantuml, "domain_model", svg] +---- +!define rectangle class +rectangle User { + +userId: String + +name: String + +email: String + +passwordHash: String +} -.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. +rectangle Game { + +gameId: String + +userId: String + +startTime: Date + +endTime: Date + +score: Int +} -Some of these concepts cannot be assigned to individual building blocks, e.g. security or safety. +rectangle Question { + +questionId: String + +text: String + +options: List + +correctAnswer: String +} +rectangle Statistic { + +statId: String + +userId: String + +totalGames: Int + +totalScore: Int + +averageScore: Float +} -.Form -The form can be varied: +User "1" -- "0..*" Game : participates in +User "1" -- "0..*" Statistic : has +Game "1" -- "0..*" Question : includes +Game "1" -- "0..1" Statistic : generates +---- -* 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) +=== User Experience Concepts (UX) -.Structure -A potential (but not mandatory) structure for this section could be: +**- Usability tests**: Usability tests will be conducted to ensure a pleasant user experience. -* Domain concepts -* User Experience concepts (UX) -* Safety and security concepts -* Architecture and design patterns -* "Under-the-hood" -* development concepts -* operational concepts +=== Safety and Security Concepts -Note: it might be difficult to assign individual concepts to one specific topic -on this list. +**- Password Hashing**: During the registration process, user passwords will be hashed using a secure algorithm on the frontend before being sent and stored in the database. +Later, during the login process, passwords are retrieved hashed from the database and decrypted on the frontend. -image::08-Crosscutting-Concepts-Structure-EN.png["Possible topics for crosscutting concepts"] +=== Architecture and Design Patterns +**- Microservices**: The system will be designed as a set of microservices, each responsible for a specific domain or functionality. -.Further Information +=== "Under-the-hood" -See https://docs.arc42.org/section-8/[Concepts] in the arc42 documentation. -**** +**- Persistency**: The system will use a nosql database (Mongo DB) to store data. +**- Transaction handling**: (todo) -=== __ +**- Session handling**: The system will use JWT tokens for session handling. -__ +**- Exception and error handling**: A server-side validation layer will be develop to catch and handle exceptions and errors effectively. +=== Development Concepts -=== __ +**- CI/CD**: The system will be developed using GitHub Actions for continuous integration and continuous deployment (CI/CD). -__ +=== Operational Concepts +**- Administration**: The system will provide an administration interface to manage users, roles, and other system settings. -... +**- Scalability**: The system will be deployed on an Azure virtual machine, which allows for easy scaling. -=== __ +**- Monitoring**: The system will be monitored using Prometheus and Grafana. Prometheus is an open-source monitoring and alerting toolkit. Grafana is a visualization tool that allows you to create dashboards and graphs. -__ diff --git a/docs/src/09_architecture_decisions.adoc b/docs/src/09_architecture_decisions.adoc index 51e9aad..87c9726 100644 --- a/docs/src/09_architecture_decisions.adoc +++ b/docs/src/09_architecture_decisions.adoc @@ -1,35 +1,26 @@ -ifndef::imagesdir[:imagesdir: ../images] - [[section-design-decisions]] -== Architecture Decisions +== 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. +This section describes the architecture decisions that were made during the development of the project. -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). +=== Technology Decisions: -Avoid redundancy. -Refer to section 4, where you already captured the most important decisions of your architecture. +**- Decision 1 - Use of Microservices**: +The system is designed as a set of microservices, each responsible for a specific domain or functionality. This architecture allows for better scalability, maintainability, and flexibility. -.Motivation -Stakeholders of your system should be able to comprehend and retrace your decisions. +**- Decision 2 - Use of node.js for Backend Services**: +The backend services of the system are built using node.js, a JavaScript runtime. Node.js was chosen for its performance, scalability, and ease of use. -.Form -Various options: +**- Decision 3 - Use of a NoSQL Database**: +A NoSQL database was chosen for the system due to its flexibility and scalability. The system uses MongoDB as its primary database. -* 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 +**- Decision 4 - Use of a React Frontend**: +The frontend of the system is built using React, a JavaScript library for building user interfaces. React was chosen for its performance, flexibility, and ease of use. -.Further Information +**- Decision 5 - Use of Docker Containers**: +The system is deployed using Docker containers. This architecture allows for better portability, scalability, and isolation of services. -See https://docs.arc42.org/section-9/[Architecture Decisions] in the arc42 documentation. -There you will find links and examples about ADR. +**- Decision 6 - Use of a RESTful API**: +The system exposes a RESTful API for communication between the frontend and the microservices. This architecture allows for better decoupling between the frontend and backend components. -**** diff --git a/docs/src/10_quality_requirements.adoc b/docs/src/10_quality_requirements.adoc index 68475e8..8192ce8 100644 --- a/docs/src/10_quality_requirements.adoc +++ b/docs/src/10_quality_requirements.adoc @@ -1,73 +1,77 @@ -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) +== Quality Requirements -Here you can also capture quality requirements with lesser priority, -which will not create high risks when they are not fully achieved. +As described in https://angelalvaigle.github.io/wiq_uo17919/#section-introduction-and-goals[section 1: Introduction and Goals], the quality requirements that were identified for the project are: -.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. +**- Usability**: the application should be user-friendly and intuitive, allowing users to easily navigate and interact with its features. +**- Testability**: The application should undergo thorough testing, ensuring a clear separation between its logic and presentation layers. -.Further Information +**- Performance**: The application should be able to handle a reasonable number of users and requests without compromising its performance. -See https://docs.arc42.org/section-10/[Quality Requirements] in the arc42 documentation. +**- Reliability**: The application should be reliable, ensuring that it is available and responsive to users at all times. -**** +**- Security**: The application should be secure, protecting users' data and preventing unauthorized access to its features. === Quality Tree -[role="arc42help"] -**** -.Content -The quality tree (as defined in ATAM – Architecture Tradeoff Analysis Method) with quality/evaluation scenarios as leafs. - -.Motivation -The tree structure with priorities provides an overview for a sometimes large number of quality requirements. - -.Form -The quality tree is a high-level overview of the quality goals and requirements: - -* tree-like refinement of the term "quality". Use "quality" or "usefulness" as a root -* a mind map with quality categories as main branches - -In any case the tree should include links to the scenarios of the following section. - - -**** +[plantuml, "quality_tree", svg] +---- +rectangle Usefulness +rectangle Usability +rectangle Testability +rectangle Performance +rectangle Reliability +rectangle Security +rectangle HomogeneousDesign as "Homogeneous Design" +rectangle SimpleExperience as "Simple Experience" +rectangle ThoroughTesting as "Thorough Testing" +rectangle ResourceOptimization as "Resource Optimization" +rectangle StablePerformance as "Stable Performance" +rectangle ErrorHandling as "Error Handling" +rectangle DataPrivacy as "Data Privacy" +rectangle BlockUnauthorizedAccess as "Block Unauthorized Access" + +Usefulness -- Usability +Usefulness -- Testability +Usefulness -- Performance +Usefulness -- Reliability +Usefulness -- Security + +Usability -- HomogeneousDesign +Usability -- SimpleExperience + +Testability -- ThoroughTesting + +Performance -- ResourceOptimization +Performance -- StablePerformance + +Reliability -- ErrorHandling + +Security -- DataPrivacy +Security -- BlockUnauthorizedAccess +---- === 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. -**** +==== Usage Scenarios + +[cols="1,2" options="header"] +|=== +| Usage Scenario | System Reaction +| A new user registers in the application. | The system should add the user data to the database and show a confirmation message. +| The user logs into the application. | The system should verify the user's credentials and grant access to the application. +| The user starts a new game. | The system should start a new game and display the first question. +| An authenticated user accesses the statistics section of the website. | The system should display the user's statistics. +|=== + +==== Change Scenarios + +[cols="1,2" options="header"] +|=== +| Change Scenario | System Reaction +| A new game mode is added to the application. | The system should update the game modes list and display the new mode to the users. +| A new user role is created. | The system should update the user roles list and grant the new role to the users. +| 2FA authentication is implemented. | The system should add the 2FA authentication feature and require users to enable it. +|=== diff --git a/docs/src/11_technical_risks.adoc b/docs/src/11_technical_risks.adoc index dc5575f..a95833f 100644 --- a/docs/src/11_technical_risks.adoc +++ b/docs/src/11_technical_risks.adoc @@ -1,25 +1,15 @@ -ifndef::imagesdir[:imagesdir: ../images] - [[section-technical-risks]] -== Risks and Technical Debts - - -[role="arc42help"] -**** -.Contents -A list of identified technical risks or technical debts, ordered by priority - -.Motivation -“Risk management is project management for grown-ups” (Tim Lister, Atlantic Systems Guild.) -This should be your motto for systematic detection and evaluation of risks and technical debts in the architecture, which will be needed by management stakeholders (e.g. project managers, product owners) as part of the overall risk analysis and measurement planning. - -.Form -List of risks and/or technical debts, probably including suggested measures to minimize, mitigate or avoid risks or reduce technical debts. - - -.Further Information - -See https://docs.arc42.org/section-11/[Risks and Technical Debt] in the arc42 documentation. +== Risks and Technical Debts -**** +Below is a table presenting the risks and potential technical debts considered by the development team. + +[cols="1,2,2" options="header"] +|=== +| Risk | Description | Preventive Measure +| Inexperience with the technologies used | Due to potential inexperience with the technologies used in the project, technical debts may arise. | To minimize the impact, it is recommended to research and test the technologies to achieve a basic level of proficiency with them. +| Dependency on wikidata | The project relies on the Wikidata API to retrieve data. If the API is unavailable, the project may not function as expected. | To mitigate this risk, it is recommended to implement a fallback mechanism that uses a local database to store data. +| Code loss | The project may suffer from code loss due to a lack of proper version control. | To prevent this, Git will be used as the version control system for managing the code and storing it in a remote repository. +| Loss of code quality | The project may suffer from a loss of code quality due to the lack of experience with the technologies used. | To prevent this, it is recommended to use code quality tools and to follow best practices. +| Planning issues | The project may suffer from planning issues due to a lack of experience with project management. | To prevent this, It is recommended to divide the project into activities and tasks, estimate their duration, and allow for potential deviations. +|=== diff --git a/docs/src/12_glossary.adoc b/docs/src/12_glossary.adoc index 192b235..d214ceb 100644 --- a/docs/src/12_glossary.adoc +++ b/docs/src/12_glossary.adoc @@ -1,42 +1,22 @@ -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. - -**** +== Glossary -[cols="e,2e" options="header"] +[cols="1,4" options="header"] |=== -|Term |Definition - -| -| - -| -| +|Term | Definition +| API | Application Programming Interface, which is a set of rules and protocols that allows different software applications to communicate with each other. +| Backend | Internal part of the application's architecture, which is responsible for processing requests and generating responses. +| CI/CD | Continuous Integration and Continuous Deployment, which is a set of practices that automate the integration of code changes and the deployment of applications. +| Container | Standardized unit of software that packages up code and all its dependencies so that the application runs quickly and reliably from one computing environment to another. +| Database | Collection of information that is organized so that it can be easily accessed, managed, and updated. +| Frontend | External part of the application's architecture, which is visible to the user and interacts with the backend. +| JSON | Data format that is easy to read and write for humans and easy to parse and generate for machines. +| Microservice | Architectural style that structures an application as a collection of small services, each running in its own process and communicating with lightweight mechanisms. +| Performance | Ability of a software system to provide a certain level of service in terms of throughput, response time, and resource utilization. +| Reliability | Ability of a system to perform and maintain its functions in routine circumstances, as well as hostile or unexpected circumstances. +| Scalability | Ability of a software system to handle a growing amount of work or its potential to accommodate growth. +| Security | Ability of a software system to protect data and functionality from unauthorized access and malicious attacks. +| Testability | Ability of a software system to be tested. +| Usability | Degree to which a software can be used by specified consumers to achieve quantified objectives with effectiveness, efficiency, and satisfaction in a quantified context of use. |=== diff --git a/package-lock.json b/package-lock.json new file mode 100644 index 0000000..17d3809 --- /dev/null +++ b/package-lock.json @@ -0,0 +1,6 @@ +{ + "name": "wiq_7", + "lockfileVersion": 3, + "requires": true, + "packages": {} +}