diff --git a/docs/images/10-Quality_Tree.png b/docs/images/10-Quality_Tree.png new file mode 100644 index 00000000..0e0ee967 Binary files /dev/null and b/docs/images/10-Quality_Tree.png differ diff --git a/docs/src/01_introduction_and_goals.adoc b/docs/src/01_introduction_and_goals.adoc index ddb2ae3d..af7820f1 100644 --- a/docs/src/01_introduction_and_goals.adoc +++ b/docs/src/01_introduction_and_goals.adoc @@ -1,93 +1,36 @@ -ifndef::imagesdir[:imagesdir: ../images] - [[section-introduction-and-goals]] == Introduction and Goals +WIQ is a web application developed by HappySw that allows users to play an online quiz game. -[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 -**** +The questions are automatically generated from Wikidata data and can be grouped by topic. Users can get a prize for each correctly answered question within a limited time and can also check their historical results in the game. === Requirements Overview +The main functional requirements to be met are: -[role="arc42help"] -**** -.Contents -Short description of the functional requirements, driving forces, extract (or abstract) -of requirements. Link to (hopefully existing) requirements documents -(with version number and information where to find it). - -.Motivation -From the point of view of the end users a system is created or modified to -improve support of a business activity and/or improve the quality. - -.Form -Short textual description, probably in tabular use-case format. -If requirements documents exist this overview should refer to these documents. - -Keep these excerpts as short as possible. Balance readability of this document with potential redundancy w.r.t to requirements documents. - - -.Further Information - -See https://docs.arc42.org/section-1/[Introduction and Goals] in the arc42 documentation. - -**** +* Users must be able to register +* Users must be able to consult their participation history +* Each question must have one correct answer and several incorrect answers. +* Questions must have a time limit to answer them +* Access to the user's data must be allowed through an API. +* Access to the information of the generated questions must be allowed through an API. === 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 -**** +The quality goals in order of priority are as follows: +[options="header",cols="1,2"] +|=== +|Quality goal|Description +|Usability|The application must be easy to understand and use +|Performance efficiency|Question generation must be efficient +|Security|The confidentiality and integrity of user data must be ensured +|Maintainability|The application must be testable and easily modifiable +|=== === 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"] |=== |Role/Name|Contact|Expectations -| __ | __ | __ -| __ | __ | __ +| Teachers | They interact with the development team and review the project to detect and correct errors| The application must meet all functional requirements and must follow the quality goals +| RTVE (client) | Company commissioning the development of the application | The company hopes that the application will be easy to use for all users and that it will be a good version of its "Saber y Ganar" programme +| Development Team| They are the creators of the project | They must develop an application that meets all the requirements and is attractive in order to attract as many users as possible +|Users|End-users who will interact with the application|They expect it to be user-friendly, attractive and similar to the programme it imitates ("Saber y Ganar") |=== diff --git a/docs/src/02_architecture_constraints.adoc b/docs/src/02_architecture_constraints.adoc index 226e501f..45c879ff 100644 --- a/docs/src/02_architecture_constraints.adoc +++ b/docs/src/02_architecture_constraints.adoc @@ -1,27 +1,27 @@ -ifndef::imagesdir[:imagesdir: ../images] - [[section-architecture-constraints]] == Architecture Constraints +=== Technical constraints +[options="header",cols="1,2"] +|=== +|Constraint|Description +|Wikidata|The generation of the questions should be done automatically with the data from Wikidata +|Web access|The application must be accessible via the web +|Git and GitHub|Version control and project tracking will be done using Git. GitHub is used to remotely store the repositories +|=== +=== Organizational constraints +[options="header",cols="1,2"] +|=== +|Constraint|Description +|Team|The development team is composed of 6 people +|Repository control|The repository has a "main" and a "develop" branch and numerous "feature" branches where new functionalities are developed +|Meetings|At least one weekly team meeting is held to maintain proper organisation +|=== +=== Conventions +[options="header",cols="1,2"] +|=== +|Convention|Description +|Arc42|The arc42 template is used in the documentation +|AsciiDoc|The documentation is done using AsciiDoc as markup language +|=== -[role="arc42help"] -**** -.Contents -Any requirement that constraints software architects in their freedom of design and implementation decisions or decision about the development process. These constraints sometimes go beyond individual systems and are valid for whole organizations and companies. - -.Motivation -Architects should know exactly where they are free in their design decisions and where they must adhere to constraints. -Constraints must always be dealt with; they may be negotiable, though. - -.Form -Simple tables of constraints with explanations. -If needed you can subdivide them into -technical constraints, organizational and political constraints and -conventions (e.g. programming or versioning guidelines, documentation or naming conventions) - - -.Further Information - -See https://docs.arc42.org/section-2/[Architecture Constraints] in the arc42 documentation. - -**** diff --git a/docs/src/03_system_scope_and_context.adoc b/docs/src/03_system_scope_and_context.adoc index c528e907..ec9a5198 100644 --- a/docs/src/03_system_scope_and_context.adoc +++ b/docs/src/03_system_scope_and_context.adoc @@ -1,75 +1,90 @@ ifndef::imagesdir[:imagesdir: ../images] [[section-system-scope-and-context]] -== 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). +## Contents +### Scope and context -.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. +This project aims to develop a quiz game. +The main constraints are developing the game as a web app and using Wikidata to obtain the questions and answers. -.Form -Various options: +--- -* Context diagrams -* Lists of communication partners and their interfaces. +## Business Context +[role="arc42help"] -.Further Information +### Contents -See https://docs.arc42.org/section-3/[Context and Scope] in the arc42 documentation. +* *Users:* They interact directly with the application through the user interface provided by the frontend using React, HTML, CSS, and JavaScript. +* *Wikidata API:* The application communicates with the Wikidata service to obtain questions and answers related to different topics. Requests are made using the HTTP protocol, and response data is received in JSON format. -**** +--- +### Motivation -=== Business Context +Regarding the information exchanged with the application, it will require having a registered account to play, and it will also exchange information with a MongoDB database and Wikidata itself to obtain the questions. -[role="arc42help"] -**** -.Contents -Specification of *all* communication partners (users, IT-systems, ...) with explanations of domain specific inputs and outputs or interfaces. -Optionally you can add domain specific formats or communication protocols. +--- -.Motivation -All stakeholders should understand which data are exchanged with the environment of the system. +### Form -.Form -All kinds of diagrams that show the system as a black box and specify the domain interfaces to communication partners. +|=== -Alternatively (or additionally) you can use a table. -The title of the table is the name of your system, the three columns contain the name of the communication partner, the inputs, and the outputs. +| *Quiz Game* | *Comunication Partners* | *Inputs* | *Outputs* +| Users | User Interface | User answers | Game questions +| Wikidata API | API Service | Question requests | JSON Responses -**** +|=== -**** +--- -**** +### Context diagram +[plantuml, "context", png] +---- +component "App" as app -=== Technical Context +:User: -> [app]: Answer question +[app] -> User: Return result -[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. +database DB +[app] -> DB: Ask for question +DB -> [app]: Return question + +component "WikiData" as wd +[app] --> wd: Ask for keyword +wd --> [app]: Return keyword +---- -.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. +--- + +## Technical Context + +[role="arc42help"] -.Form -E.g. UML deployment diagram describing channels to neighboring systems, -together with a mapping table showing the relationships between channels and input/output. +### Contents -**** +* *HTTP Channel:* The application uses the HTTP protocol to communicate with the Wikidata API service. +* *MongoDB Data Channel:* Interactions with the MongoDB database allow for storing and retrieving questions and answers. -**** +--- -**** +### Deployment diagram +[plantuml, "deployment", png] +---- +node "Aplication Server" as app +node "DB Server" as db { +artifact "MongoDB Server" +} +node Wikidata as w +node Interface as i -**** +app - db +app -- w +app -- i +---- diff --git a/docs/src/04_solution_strategy.adoc b/docs/src/04_solution_strategy.adoc index 7bf03f7a..97a4dd76 100644 --- a/docs/src/04_solution_strategy.adoc +++ b/docs/src/04_solution_strategy.adoc @@ -1,32 +1,85 @@ ifndef::imagesdir[:imagesdir: ../images] [[section-solution-strategy]] -== 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 +## Contents +This page contains a short summary and explanation of the fundamental decisions and solution strategies, that shape system architecture. + +--- + +### Technology Decisions +Below, all the technologies to be used in the development of the application are listed: + +* *JavaScript / React:* A JavaScript library designed to facilitate the development of web applications. +* *JavaScript / NodeJS:* An asynchronous runtime environment based on JavaScript. +* *MongoDB:* A document-oriented NoSQL database system. +* *Docker:* Used for deploying applications locally. +* *Azure:* Used for deploying applications on a server. + +--- + +### Top-Level Decisions +In this section, a summarized list of all decisions regarding the architecture of the application is included. + +|=== + +| *Architectural Pattern* | In this project, the pattern based on the Microservices model is used. +| *Frontend (Client)* | React: Building the user interface +| *Backend (Server)* | NodeJS: Building the server on the backend +| | Mongoose: Interaction with the database +| *Database* | MongoDB: NoSQL database storing data in BSON format +| *Deployment* | Azure cloud services + +|=== + +--- + +### Quality Goals +Next, several quality goals are established, along with the decisions made to achieve them. + +|=== +| *Quality Goal* | *Decisions* + +| Usability +| Creation of a responsive interface adaptable to all types of screens. + +| Accessibility +| Compliance with accessibility standards to ensure a usable application. + +| Maintainability +| A structured project that facilitates the maintainability of the application. + +| Testing +| Assurance of a fully functional and error-free application. + +|=== + +--- + +### Relevant Organizational +Regarding the organization of the team, we have decided to use agile methodologies for better and faster group work. In this project, we will follow the best practices of the SCRUM framework. -* 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. +Practices to be followed: -.Motivation -These decisions form the cornerstones for your architecture. They are the foundation for many other detailed decisions or implementation rules. +* Division of the project into *tasks*. +* Equitable *assignment* of tasks. +* Frequent *meetings* on the progress of the application. +* Construction of *"Alpha"* versions before the final release. -.Form -Keep the explanations of such key decisions short. +Additionally, "Issues" and the GitHub-provided Kanban (ToDo - In Progress - Done) are used for communication. -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. +--- +### Motivation +This section addresses the fundamental decisions for the project's architecture. -.Further Information +|=== -See https://docs.arc42.org/section-4/[Solution Strategy] in the arc42 documentation. +| *Data Management* | +| *Deployment* | +| *Security* | +| *Monitoring* | -**** +|=== diff --git a/docs/src/05_building_block_view.adoc b/docs/src/05_building_block_view.adoc index df5c29c8..9259f46d 100644 --- a/docs/src/05_building_block_view.adoc +++ b/docs/src/05_building_block_view.adoc @@ -2,211 +2,149 @@ 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. - - -.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. - -**** - -_****_ - -Motivation:: - -__ +=== Level 1: Whitebox of the Overall System +[plantuml, "level1", png] -Contained Building Blocks:: -__ +---- -Important Interfaces:: -__ +Actor User +Component WIQ +Component Wikidata +User -right-> WIQ: interacts with +WIQ -right-> Wikidata: receives data +Wikidata -right..> WIQ -[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: +==== Motivation -[cols="1,2" options="header"] -|=== -| **Name** | **Responsibility** -| __ | __ -| __ | __ -|=== +*_WIQ_* application is the general structure of a system in which users will have the possibility to play a game like _Saber y Ganar_ and compare their results with their friends. +==== Contained building blocks +[options="header",cols="1,2"] +|=== -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. -**** +| Name | Description +| *_User_* +| Client of the application which will interact with it. -==== +| *_WIQ_* +| System developed to be used by the users. -[role="arc42help"] -**** -Here you describe -according the the following black box template: +| *_WIKIDATA_* +| Aplication to generate the questions and answers. -* 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 +|=== -**** +=== Level 2 +[plantuml, "level2", png] +---- +Actor User +Component WIQ { + Component ui as "User Interface" + Component ms as "MicroService" + Database db as "MongoDB" +} -__ +Component wd as "WikiData" -__ +User -> ui: Interacts +ui -> ms: Sends requests +ms <-> db: Reads +wd -> ms: Gives data +---- +==== Motivation -_<(Optional) Quality/Performance Characteristics>_ +Shows how the application will work internally. The user, through the user interface, will use microservices to access the different modules with the help of the database. -_<(Optional) Directory/File Location>_ +==== Contained building blocks -_<(Optional) Fulfilled Requirements>_ +[options="header",cols="1,2"] +|=== -_<(optional) Open Issues/Problems/Risks>_ +| Name | Description +| *_User Interface_* +| The user will interact with the UI. +| *_Microservices_* +| It is the backend of the UI, formed by different modules. +| *_DataBase_* +| MongoDB is the chosen NoSQL database management system. It stores all the information necessary for the proper functioning of the application. -==== +|=== -__ +=== Level 3 +[plantuml, "level3", png] +---- +Component WIQ { -==== + Component ms as "MicroServices" { + Component users as "Users Service" + Component question as "Question Service" + Component game as "Game Service" + Component ranking as "ranking" + Component history as "History" + Database db as "MongoDB" + } -__ + Component ui as "User Interface" -==== + ui --> users + ui --> game + ui --> history + ui --> ranking -... -==== + users <-down-> db + game <-down-> db + ranking <-down-> db + history <-down-> db +} +Component wd as "Wikidata" -=== Level 2 +game --> question: generates question +question <-> wd: ask and answer the question +---- +==== Motivation -[role="arc42help"] -**** -Here you can specify the inner structure of (some) building blocks from level 1 as white boxes. +Detailed structure of the system. Focused on the components of the _User Interface_ and _Data Access_. -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 -**** +==== Contained Building Blocks -==== White Box __ +[options="header",cols="1,5"] +|=== -[role="arc42help"] -**** -...describes the internal structure of _building block 1_. -**** +| Name | Description -__ +| *_Game_* +| Game screen where the user can play the game. -==== White Box __ +| *_Ranking_* +| It contains the best scores recorded in the game, including the user's highest score and the scores of other users belonging to their group. +| *_History_* +| Contains all user participations with the number of games played, correct/incorrect answers, and times. -__ +| *_About_* +| Contains important information about the project, like the development method, the developers and how to contact them. -... +| *_Users Service_* +| Allows the client to create a new account for the application, log in and log out. -==== White Box __ +| *_Question service_* +| Allows to ask him questions and receive the answers of them. -__ - - - -=== 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_> - -__ diff --git a/docs/src/06_runtime_view.adoc b/docs/src/06_runtime_view.adoc index e10f375b..d6a953e1 100644 --- a/docs/src/06_runtime_view.adoc +++ b/docs/src/06_runtime_view.adoc @@ -2,64 +2,114 @@ ifndef::imagesdir[:imagesdir: ../images] [[section-runtime-view]] == Runtime View +=== Login +For the login, the app shows the login view, which asks the user for his username and his password. -[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: +Then, the app does a login request to the users microservice, which redirect the user to the identity provider, which handles the authentication. -* 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 +If the login is succesfully, the app shows the different options of the game. +In case the login isn't succesfully, a warning message is shown. -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. +[plantuml,"sequencediagram-login",png] +---- +actor User as u +participant "Web App" as w +participant "User Microservice" as um +activate w +w -> w: Show Login View +u -> w: Chooses Identity +w -> um: Requests login +deactivate w +activate um +um -> um: Redirects to the provider login form +um --> u: Asks for credentials +deactivate um +activate u +u -> um: Logs in +deactivate u +activate um +um --> um: Provides session information +um --> w: Provides session ID +deactivate um +activate w +w -> w: Show Game View +deactivate um +---- +=== Game -* numbered list of steps (in natural language) -* activity diagrams or flow charts -* sequence diagrams -* BPMN or EPCs (event process chains) -* state machines -* ... +When the user starts a game, the app generates a question and request the correct answer to the WikiData API. When the user choose a posible answer, the app checks if it is the correct answer. Then, this process is repeated until the end of the game. +[plantuml,"sequencediagram-game",png] +---- +actor User as user +participant WebApp as app +participant GameMS as gameMS +participant WikiDataAPI as api + +activate app + +user -> app: Start game +app -> gameMS: Generate question +gameMS -> api: Request correct answer\nfor the generated question +api --> gameMS: Correct answer +gameMS -> app: +app -> user: Show question and options + +loop Until end of the game + user -> app: Choose possible answer + app -> gameMS: Verify answer\nselected by the user + gameMS --> app: Correct or incorrect answer + app -> user: Show result\nand current score +end + +user -> app: Finish game +app --> user: Show final score + +deactivate app +---- +=== Ranking +In this view, the user can watch different rankings: -.Further Information +- Ordered by accuracy percentage +- Ordered by number of questions answered correctly +- Ordered by quantity of game rounds -See https://docs.arc42.org/section-6/[Runtime View] in the arc42 documentation. +[plantuml,"sequencediagram-ranking",png] +---- +actor User as user +participant RankingMS as MS +participant MongoDB as db -**** +activate MS -=== +user -> MS: Request ranking +MS -> db: Asks for the ranking +db -> MS: Gives the ranking with the best +MS -> user: Shows the ranking -* __ -* __ +deactivate MS +---- +=== History +In this view, the user can watch this options about his past games: -It is possible to use a sequence diagram: +- Number of games played +- Best times +- Correct/incorrect questions -[plantuml,"Sequence diagram",png] ----- -actor Alice -actor Bob -database Pod as "Bob's Pod" -Alice -> Bob: Authentication Request -Bob --> Alice: Authentication Response -Alice --> Pod: Store route -Alice -> Bob: Another authentication Request -Alice <-- Bob: another authentication Response +[plantuml,"sequencediagram-history",png] ---- +actor User as user +participant HistoryMS as MS +participant MongoDB as db -=== +activate MS -=== ... +user -> MS: Request history +MS -> db: Asks for the history +db -> MS: Gives the user's history +MS -> user: Shows the history -=== +deactivate MS +---- diff --git a/docs/src/07_deployment_view.adoc b/docs/src/07_deployment_view.adoc index 22b45c27..0bb43d13 100644 --- a/docs/src/07_deployment_view.adoc +++ b/docs/src/07_deployment_view.adoc @@ -7,88 +7,34 @@ ifndef::imagesdir[:imagesdir: ../images] [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. -**** - -_****_ +image::Diag_Comp.jpg[align="center",title="Deployment Diagram",link="Diag_Comp.jpg] Motivation:: -__ +The system is based in microservices architecture with three independent services, each responsible for a specific aspect of the functionality. One service is the Graphic interface, this service handles the presentation layer of a web application. Another service is tasked with managing user-related functionalities. MongoDB, a NoSQL database, is used to store and manage user data efficiently. The third service utilizes Wikidata, a free open base, to automatically generate questions. Quality and/or Performance Features:: -__ +The main reason we have chosen a microservices architecture is to achieve a fast and efficient application.. The availability and efficiency of the application will be affected by Wikidata's availability, but just in the question generation moment. 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. -**** - -==== __ - -__ - -==== __ - -__ +[cols="1,2" options="header"] +|=== +| **Element** | **Description** +| _Browser_ | _The browser on the user's device where they can access to the application._ +| _WebApp_ | _The graphical interface through which users can interact._ +| _API Gateway_ | _The API that comunicates the rest of the microservices with the graphical interface._ +| _Question_Generator_ | _The microservice responsible for generating questions through Wikidata._ +| _Wikidata_ | _The Wikidata API that allows us to access its information._ +| _Users_ | _The microservice responsible for managing users._ +| _MongoDB_ | _A NoSQL based database where we can save the user's data._ +|=== -... -==== __ -__ diff --git a/docs/src/08_concepts.adoc b/docs/src/08_concepts.adoc index 591ccf1f..9df6060e 100644 --- a/docs/src/08_concepts.adoc +++ b/docs/src/08_concepts.adoc @@ -6,65 +6,19 @@ ifndef::imagesdir[:imagesdir: ../images] [role="arc42help"] **** -.Content -This section describes overall, principal regulations and solution ideas that are relevant in multiple parts (= cross-cutting) of your system. -Such concepts are often related to multiple building blocks. -They can include many different topics, such as - -* models, especially domain models -* architecture or design patterns -* rules for using specific technology -* principal, often technical decisions of an overarching (= cross-cutting) nature -* implementation rules - - -.Motivation -Concepts form the basis for _conceptual integrity_ (consistency, homogeneity) of the architecture. -Thus, they are an important contribution to achieve inner qualities of your system. - -Some of these concepts cannot be assigned to individual building blocks, e.g. security or safety. - - -.Form -The form can be varied: - -* concept papers with any kind of structure -* cross-cutting model excerpts or scenarios using notations of the architecture views -* sample implementations, especially for technical concepts -* reference to typical usage of standard frameworks (e.g. using Hibernate for object/relational mapping) - -.Structure -A potential (but not mandatory) structure for this section could be: - -* Domain concepts -* User Experience concepts (UX) -* Safety and security concepts -* Architecture and design patterns -* "Under-the-hood" -* development concepts -* operational concepts - -Note: it might be difficult to assign individual concepts to one specific topic -on this list. - -image::08-Crosscutting-Concepts-Structure-EN.png["Possible topics for crosscutting concepts"] - - -.Further Information - -See https://docs.arc42.org/section-8/[Concepts] in the arc42 documentation. **** +=== _Domain Model_ -=== __ - -__ +_TBD_ +=== _Security_ +_The communication between the application's APIs will be through the secure mode of HTTP._ -=== __ +=== _Privacy_ -__ +_The user's data will be stored in a MongoDb database. That implies that the information is stored securely._ ... diff --git a/docs/src/09_architecture_decisions.adoc b/docs/src/09_architecture_decisions.adoc index 51e9aad9..061b39a5 100644 --- a/docs/src/09_architecture_decisions.adoc +++ b/docs/src/09_architecture_decisions.adoc @@ -33,3 +33,12 @@ See https://docs.arc42.org/section-9/[Architecture Decisions] in the arc42 docum There you will find links and examples about ADR. **** + +[options="header",cols="1,2"] +|=== +|Decision|Motivation +| Docker | It is decided to use Docker due to its popularity in the professional field and its ease of execution thanks to the configuration files provided by the subject's faculty. +| MongoDB | It is decided to use MongoDB based on the recommendation of the faculty, as it is one of the most popular NoSQL databases and because it fits perfectly with the application's needs. +| NodeJS | It is decided to use NodeJS since it is the recommended option by the subject's faculty and one of the most widely used technologies in this area of web applications, thus having extensive documentation and examples available on the Internet. +| React | It is decided to use React since it is the recommended option by the subject's faculty. +|=== \ No newline at end of file diff --git a/docs/src/10_quality_requirements.adoc b/docs/src/10_quality_requirements.adoc index 68475e80..48b77477 100644 --- a/docs/src/10_quality_requirements.adoc +++ b/docs/src/10_quality_requirements.adoc @@ -43,6 +43,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. +image::10-Quiality_Tree.png["Quality Tree"] **** @@ -71,3 +72,21 @@ 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,2,2"] +|=== +|Quality Goal|Scenario|Response +| Performance efficiency | The user wants to start answering questions. | The application generates a set of questions. This generation should be as fast as possible. +| Usability | A new user starts using the application. | User should be able to do it without difficulty. +| Security | The application must encript sensible data. | Data will be only accessible by its owner. +|=== + +* Change Scenarios + +[options="header",cols="1,2,2"] +|=== +|Quality Goal|Scenario|Response +| Maintainability | Introduce new functionality. | Reuse key components in order to easily add that new functionality. +|=== \ No newline at end of file diff --git a/docs/src/11_technical_risks.adoc b/docs/src/11_technical_risks.adoc index dc5575fc..db89625c 100644 --- a/docs/src/11_technical_risks.adoc +++ b/docs/src/11_technical_risks.adoc @@ -1,25 +1,24 @@ -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 +[options="header",cols="1,2"] +|=== +|Risk|Description +|Teamwork failures +|The distribution of tasks must be done effectively, so that if one member of the team does not perform an assigned task, it can be solved by another member. +|Version management problems +|Errors in version control can delay the project. Ignorance of the branches and their purpose can lead to code conflicts. +|Lack of time +|Not planning work well can result in difficulties meeting deadlines +|Use of unknown technologies +|The use of languages and technologies unknown to group members can make it difficult to perform assigned tasks +|=== + +=== Technical debts +[options="header",cols="1,2"] +|=== +|Risk|Description +|Insufficient documentation +|A lack of clear documentation about code and architecture can make it difficult to understand and maintain code, leading to additional work. +|=== **** diff --git a/docs/src/12_glossary.adoc b/docs/src/12_glossary.adoc index 192b2353..5fbfbc3a 100644 --- a/docs/src/12_glossary.adoc +++ b/docs/src/12_glossary.adoc @@ -2,41 +2,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. - -**** - [cols="e,2e" options="header"] |=== |Term |Definition -| -| +|React +|JavScript library, we make use of this User Interface library on the front-end + +|Docker +|We use it to deploy applications within virtual containers + +|Node.js +|JavaScript runtime environment, we make use of this on the back-end + +|GitHub +|Portal used to host the application code and documentation -| -| +|MongoDB +|NoSQL database management system used in the application |===