diff --git a/docs/src/01_introduction_and_goals.adoc b/docs/src/01_introduction_and_goals.adoc index 39d5d49..47aa6cf 100644 --- a/docs/src/01_introduction_and_goals.adoc +++ b/docs/src/01_introduction_and_goals.adoc @@ -1,95 +1,148 @@ -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. - -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. - -**** - -=== 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 -**** - -=== 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 -| *Students* | Andrés Cadenas Blanco, Christian Fernandez Noriega , Adrián González Guadalupe and Luis Salvador Ferrero | Are the ones in charge of web development. They will work together to make the application. -| *Teachers* | Pablo González | In charge of supervising the student's teamwork, ensuring the work accomplishes the goals in the best way possible and helping in the development and solving doubts. -| *Bussineses* | RTve has hired software development company HappySw | Emphasis the SOLID part of the web and have a high understanding of this area -| *Users* | Anyone that wants to use the web | They should be able to understand how to use and move around the web with ease -|=== + +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 +**** +In these points, the main goals and functional requirements will be explained. In order to give context on how the webapp will be developed. + +=== Requirements Overview + +[role="arc42help"] +**** +.Contents +Short description of the functional requirements, driving forces, extract (or abstract) +of requirements. Link to (hopefully existing) requirements documents +(with version number and information where to find it). + +.Motivation +From the point of view of the end users a system is created or modified to +improve support of a business activity and/or improve the quality. + +.Form +Short textual description, probably in tabular use-case format. +If requirements documents exist this overview should refer to these documents. + +Keep these excerpts as short as possible. Balance readability of this document with potential redundancy w.r.t to requirements documents. + + +.Further Information + +See https://docs.arc42.org/section-1/[Introduction and Goals] in the arc42 documentation. + +**** +The functional requirements have been grouped into the different microservices the web application will have. +==== User and Authorization Services +[decimal] +. The User service allows the user to +[arabic] +.. Register. +.. Delete the account. +.. Update the account. +.. Recover the password. +. The authorization service allows the user to +[arabic] +.. Log in. +.. Log out. +. A user can retrieve the following information from the User service +[arabic] +.. Name. +.. Email. +.. Profile picture. +.. Questions answered. +. The system must be able to manage the user's access to the system. + +==== Question Service +[decimal, start=5] +. The Question service retrieves questions generated from wikidata. +. A user can retrieve the following information from the Question service +[arabic] +.. Select a category. +.. Select a difficulty. +.. Select a question. +.. Select an answer. +. Questions must be stored in a database. +. The database used is MongoDB. +. Questions are classified by +[arabic] +.. Category. +.. Difficulty. +. The questions should be selected randomly. +=== Quality Goals + +[role="arc42help"] +**** +.Contents +The top three (max five) quality goals for the architecture whose fulfillment is of highest importance to the major stakeholders. +We really mean quality goals for the architecture. Don't confuse them with project goals. +They are not necessarily identical. + +Consider this overview of potential topics (based upon the ISO 25010 standard): + +image::01_2_iso-25010-topics-EN.drawio.png["Categories of Quality Requirements"] + +.Motivation +You should know the quality goals of your most important stakeholders, since they will influence fundamental architectural decisions. +Make sure to be very concrete about these qualities, avoid buzzwords. +If you as an architect do not know how the quality of your work will be judged... + +.Form +A table with quality goals and concrete scenarios, ordered by priorities +**** +[options="header", cols="1,1"] +|=== +| Goal | Description +| Testability |Test will be developed, so the application has a good quality. + +| Usability | The application has to be intuitive for its users. + +| Portability | The application works in different devices and browsers. With different screen sizes. + +| Performance | The application can handle a big number of users and give good response times. + + + +|=== + +=== 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 +| *Students* | Andrés Cadenas Blanco, Christian Fernandez Noriega , Adrián González Guadalupe and Luis Salvador Ferrero | Are the ones in charge of web development. They will work together to make the application. +| *Teachers* | Pablo González | In charge of supervising the student's teamwork, ensuring the work accomplishes the goals in the best way possible and helping in the development and solving doubts. +| *Bussineses* | RTve has hired software development company HappySw | Emphasis the SOLID part of the web and have a high understanding of this area +| *Users* | Anyone that wants to use the web | They should be able to understand how to use and move around the web with ease +|=== + diff --git a/docs/src/03_system_scope_and_context.adoc b/docs/src/03_system_scope_and_context.adoc index c528e90..9c79942 100644 --- a/docs/src/03_system_scope_and_context.adoc +++ b/docs/src/03_system_scope_and_context.adoc @@ -48,28 +48,44 @@ The title of the table is the name of your system, the three columns contain the **** -**** - -**** - -=== 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,"Context diagram",png] +---- +actor Player +actor Client +[Wikidata] <> + +[WIQ Game] <> +[UsersAPI] <> +[GeneratedQuestionsAPI] <> +Player ..> (WIQ Game) : register/login +Client ..> (WIQ Game) : view data +[GeneratedQuestionsAPI] ..> Wikidata +[WIQ Game] ..> UsersAPI +[WIQ Game] ..> GeneratedQuestionsAPI +---- + +[cols="e,2e" options="header"] +|=== +|Element |Description + +|Player +|Plays the game and can consult past scores + +|Client +|Can access the data about players and generated questions + +|WIQ Game +|Main system in which generated questions are shown and can be answered by players + +|Wikidata +|External data repository from which questions are generated using the WikidataAPI + +|MongoDB +|Database for storing generated questions, players' info and scores + +|Users Info API +|Allows clients to see the info about players stored in the database + +|Generated Questions API +|Allows clients to see the info about generated questions stored in the database +|=== \ No newline at end of file diff --git a/docs/src/04_solution_strategy.adoc b/docs/src/04_solution_strategy.adoc index 7bf03f7..68a269e 100644 --- a/docs/src/04_solution_strategy.adoc +++ b/docs/src/04_solution_strategy.adoc @@ -2,7 +2,17 @@ ifndef::imagesdir[:imagesdir: ../images] [[section-solution-strategy]] == Solution Strategy +The system will follow *MERN Stack* as they key technologies for its development. MERN Stack is composed of four technologies: MongoDB, Express, +React and Node. +* *MongoDB:* chosen technology for the persistance of the system, that provides a non-relational database approach. +* *Express and Node:* they make up the middle tier of the application, providing a powerful server platform. +* *React:* front-end framework that will solve the client interfaces of the application. + +Regarding the deployment of the application, the strategy chosen is a *cloud-based* system. This decision was motivated because of the nature of +the project, since a web application needs to be live and accesible at any moment. +The server will be an ARM *Linux VM on Oracle*, where some *containers* for different charasteristics of the system will be *deployed with +Docker* (MongoDB database for example) [role="arc42help"] **** diff --git a/docs/src/05_building_block_view.adoc b/docs/src/05_building_block_view.adoc index df5c29c..036ba49 100644 --- a/docs/src/05_building_block_view.adoc +++ b/docs/src/05_building_block_view.adoc @@ -63,18 +63,53 @@ In the best case you will get away with examples or simple signatures. **** -_****_ +[plantuml,"White box overall system",png] +---- +actor Player +actor Client +[Wikidata] + +rectangle "WIQ Game (Level 1)"{ +[WIQ Game GUI] +[Data View] +[UsersAPI] +[GeneratedQuestionsAPI] #BurlyWood +Player ..> (WIQ Game GUI) +Client ..> (Data View) +[GeneratedQuestionsAPI] ..> Wikidata +[WIQ Game GUI] ..> UsersAPI +[WIQ Game GUI] ..> GeneratedQuestionsAPI +[Data View] ..> UsersAPI +[Data View] ..> GeneratedQuestionsAPI +} +---- Motivation:: -__ +We made the decomposition separating the functionallities (The names are self explanatory but components will be described later) +Contained Black boxes:: -Contained Building Blocks:: -__ +[cols="e,2e" options="header"] +|=== +|Name |Responsibility + +|WIQ Game GUI +|Main window in which questions are shown and can be answered by the player. The latter can also see past scores. + +|Data View +|Access to data about users and generated questions for the client. + +|Generated Questions API +|In charge of generating the questions and storing their data + +|UsersAPI +|In charge of keeping track of the data of the users (registration and scores) + +|Wikidata +|External element used for the generation of questions -Important Interfaces:: -__ +|=== [role="arc42help"] **** @@ -97,8 +132,6 @@ Its headline is the name of the black box. **** -==== - [role="arc42help"] **** Here you describe @@ -113,37 +146,6 @@ according the the following black box template: **** -__ - -__ - -_<(Optional) Quality/Performance Characteristics>_ - -_<(Optional) Directory/File Location>_ - -_<(Optional) Fulfilled Requirements>_ - -_<(optional) Open Issues/Problems/Risks>_ - - - - -==== - -__ - -==== - -__ - - -==== - -... - -==== - - === Level 2 @@ -156,57 +158,59 @@ Please prefer relevance over completeness. Specify important, surprising, risky, Leave out normal, simple, boring or standardized parts of your system **** -==== White Box __ +==== Generated Questions API (White Box) [role="arc42help"] **** ...describes the internal structure of _building block 1_. **** -__ - -==== White Box __ - - -__ - -... - -==== White Box __ - - -__ - +[plantuml,"Generated Questions API (White Box)",png] +---- +[Wikidata] +[wikidatanpm] <> +[WIQ Game GUI] +[Data View] +database MongoDB +rectangle "GenedQuestsAPI (Level 2)"{ -=== Level 3 +[GenQuestsService] ..> wikidatanpm +[GenQuestsService] ..> Wikidata +[GenQuestsService] <--> MongoDB +[WIQ Game GUI] ..> GenQuestsService : new Question +[Data View] ..> GenQuestsService : get Questions +} +---- -[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. -**** +Motivation:: +We made the decomposition separating the functionallities. -==== White Box <_building block x.1_> - -[role="arc42help"] -**** -Specifies the internal structure of _building block x.1_. -**** +Contained Black boxes:: +[cols="e,2e" options="header"] +|=== +|Name |Responsibility -__ +|GenQuestsService +|Receives different petitions regarding the generation of questions or their retrieval and responds accordingly. +|wikidatanpm +|External library that facilitates and simplifies the use of wikidata for the generation of questions. -==== White Box <_building block x.2_> +|MongoDB +|The data of the generated questions is stored here for showing it later to the client. -__ +|=== +Additional explanation of relationships:: +The service is requested either the generation of a question or the retrieval of a subset (from WIQ Game GUI or +Data View respectively). -==== White Box <_building block y.1_> +For the first case, it makes use of the library to generate the question, retrieves it +for the interface to use and stores the pertinent data in the DB. -__ +In the other case, it just makes the query according to the client choosings and retrieves the data of the +questions for the Data View to show. \ No newline at end of file diff --git a/docs/src/06_runtime_view.adoc b/docs/src/06_runtime_view.adoc index e10f375..4c0850f 100644 --- a/docs/src/06_runtime_view.adoc +++ b/docs/src/06_runtime_view.adoc @@ -2,8 +2,48 @@ ifndef::imagesdir[:imagesdir: ../images] [[section-runtime-view]] == Runtime View +=== User authentication +* Users will log in through the web interface of the application. +* The system stores in database (MongoDB) the users of the application. Any data relative to them is accessed via the database of the system and displayed to them on the web interface. +=== Access to user data via API +* Clients access the users data through an API +[plantuml,"Sequence diagram",png] +---- +entity Client +database API as "Users API" +Client -> API: Data querying request +API --> Client: Retrieved data +---- + +=== Access to questions data via API +* Clients access the questions data through an API + +[plantuml,"Sequence diagram",png] +---- +entity Client +database API as "Questions API" +Client -> API: Data querying request +API --> Client: Retrieved data +---- + +=== Game +* Users can play a Q&A game + +[plantuml,"Sequence diagram",png] +---- +actor User +entity App +database QAPI as "Questions API" +database UAPI as "Users API" +User -> App: Start Game +App -> QAPI: Get Questions +QAPI --> App: Send Questions +App -> User: Show Question +User --> App: Answer Question +App -> UAPI: Update User Data +---- [role="arc42help"] **** .Contents diff --git a/docs/src/10_quality_requirements.adoc b/docs/src/10_quality_requirements.adoc index 68475e8..e81acbd 100644 --- a/docs/src/10_quality_requirements.adoc +++ b/docs/src/10_quality_requirements.adoc @@ -45,7 +45,13 @@ In any case the tree should include links to the scenarios of the following sect **** - +@startmindmap +* Quality +** Testability +** Usability +** Portability +** Performance +@endmindmap === Quality Scenarios [role="arc42help"] @@ -71,3 +77,46 @@ more precisely down to a level of scenarios that can be discussed and evaluated. .Form Tabular or free form text. **** +==== Usage Scenarios +[options="header", cols="1,1,1,1"] +|=== +| Quality goal | Motivation | Usage scenario | Priority + +| *Testability* +| Test will be developed, so the application has a good quality. +| The coverage should be higher than 70% and SonarCloud should give a pass in unit tests +| *High* + +| *Usability* +| The application has to be intuitive for its users. +| Users don't like to spend a lot of time trying to understand how to use an application. Therefore when they want to do something, they want to know where to go and what to do. +| *Very high* + +| *Portability* +| The application works in different devices and browsers. With different screen sizes. +| Users connect from different devices and browsers, we should ensure that the application works in all of them. +| *Medium* + +| *Performance* +| The application can handle a big number of users and give good response times. +| The application should be able to stand at least 10 users simultaneously and give a response time of less than 20 seconds. +| *High* + +|=== + +==== Change Scenarios + +[options="header", cols="1,1,1,1"] +|=== +| Quality goal | Motivation | Change scenario | Priority +| *Maintainability* +| An application should be easy to update and maintain by the dev team. Respecting the architecture of the web application and the continuous integration. +| If a developer wants to add a feauture or include a hotfix, he should be able to do it without major consequences on the system, always respecting the architecture of the web application. +| *High* + +| *Maintainability* +|An application should be easy to update and maintain by the dev team. Respecting the architecture of the web application. +| As there is continuous integration, when fixing a bug or adding a feature, if an error is found, the application won't be affected as changes won't be applied. +| *Very High* + +|=== \ No newline at end of file