Merge pull request #45 from Arquisoft/Documentation

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
-| _<Role-1>_ | _<Contact-1>_ | _<Expectation-1>_
-| _<Role-2>_ | _<Contact-2>_ | _<Expectation-2>_
+| 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")
 |===

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.
-
-****

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
 
-****
+|===
 
-**<Diagram or Table>**
+---
 
-**<optionally: Explanation of external domain interfaces>**
+### 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.
 
-**<Diagram or Table>**
+---
 
-**<optionally: Explanation of technical interfaces>**
+### 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
 
-**<Mapping Input/Output to Channels>**
+app - db
+app -- w
+app -- i
+----