Merge pull request #11 from Arquisoft/develop

Documentation parts 1-4

docs/src/01_introduction_and_goals.adoc

@@ -2,6 +2,14 @@ ifndef::imagesdir[:imagesdir: ../images]
 
 [[section-introduction-and-goals]]
 == Introduction and Goals
+WIQ is the project of the current course of the Software Architecture course, which will be developed by the ES2B team composed by:
+
+* Raymond Debasa Peralta
+* Coral Izquierdo Muñiz
+* Carlos Sánchez Rodríguez
+* Pablo Fernando Urones Clavera
+
+It consists of an application in which users can register and enter to play the quiz game.
 
 [role="arc42help"]
 ****
@@ -17,6 +25,15 @@ These include
 
 === Requirements Overview
 
+.Requisitos de alto nivel
+* The system will have at least one web frontend deployed and access will be through the Web.
+* Users will be able to register in the system and consult the history of their participation in the system: number of games, number of correct/failed questions, times, etc.
+* Questions will be automatically generated from Wikidata data.
+* Questions must be answered within a given time limit.
+* Each question will have one correct answer and several incorrect or distracting answers. Both the correct and incorrect answers will be generated automatically.
+* The system will allow access to user information through an API.
+* The system will allow access to the information of the questions generated through an API.
+
 [role="arc42help"]
 ****
 .Contents
@@ -63,6 +80,15 @@ If you as an architect do not know how the quality of your work will be judged..
 A table with quality goals and concrete scenarios, ordered by priorities
 ****
 
+[options="header",cols="1,2"]
+|===
+|Goals|Details
+| _Privacity_ | _The data of registered users will be saved, ensuring their security_ 
+| _Usability_ | _The use of the application must be an intuitive and simple process for the client user_
+| _Maintainability_ | _We will try to take care of the architecture of the application so that functionality can be added, modified or removed with as few changes as possible_
+| _Testeability_| _Our application may also be testable, that is, it will be subjected to a series of unit tests that we will perform to ensure proper operation of the system, in addition to identifying small errors and being able to correct them in such a case_
+|===
+
 === Stakeholders
 
 [role="arc42help"]
@@ -88,6 +114,8 @@ Table with role names, person names, and their expectations with respect to the
 [options="header",cols="1,2,2"]
 |===
 |Role/Name|Contact|Expectations
-| _<Role-1>_ | _<Contact-1>_ | _<Expectation-1>_
-| _<Role-2>_ | _<Contact-2>_ | _<Expectation-2>_
+| _Client_ | _RTVE_ | _An application that emulates a quiz show and meets the requirements of section 1.1_
+| _Contrated Company_ | _HappySw_ | _Generic software development_
+| _Development Staff_ | _Raymond Debasa Peralta, Coral Izquierdo Muñiz, Carlos Sánchez Rodríguez and Pablo Fernando Urones Clavera_ | _Successfully develop the application based on the documentation in a way that reflects the architectural knowledge acquired_
+| _Users_ | _Future users of the application_ | _A usable and simple application that allows them to play quiz games_
 |===

docs/src/02_architecture_constraints.adoc

@@ -13,15 +13,64 @@ Any requirement that constraints software architects in their freedom of design
 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)
 
+=== 2.1 Technical Constraints
+[cols="1,1", options="header"]
+|===
+| Constraint | Description
+| Application Server Version | Usage of version X.X of the application server is required.
+| Compatibility with Operating Systems | The application must be compatible with Windows .
+|===
 
-.Further Information
+=== 2.2 Legal and Regulatory Constraints
+[cols="1,1", options="header"]
+|===
+| Constraint | Description
+| Compliance with Privacy Regulations | The application must comply with privacy regulations in country Spain.
+|===
+
+=== 2.3 Development Constraints
+[cols="1,1", options="header"]
+|===
+| Constraint | Description
+| Development Methodology | The team will follow an agile development methodology.
+| Build Tool | The Z build tool will be used for the compilation process.
+|===
+
+=== 2.4 Organizational Constraints
+[cols="1,1", options="header"]
+|===
+| Constraint | Description
+| Internal Security Policies | Internal security policies of the organization will be adhered to.
+|===
+
+=== 2.5 Interoperability Constraints
+[cols="1,1", options="header"]
+|===
+| Constraint | Description
+| Communication Standard | The application must be compatible with communication standard ABC.
+|===
+
+=== 2.6 Security Constraints
+[cols="1,1", options="header"]
+|===
+| Constraint | Description
+| Two-Factor Authentication | Two-factor authentication is mandatory for all users.
+|===
+
+=== 2.7 Performance Constraints
+[cols="1,1", options="header"]
+|===
+| Constraint | Description
+| Response Time | The application's response time should not exceed 2 seconds.
+|===
+
+=== 2.8 Maintenance and Scalability Constraints
+[cols="1,1", options="header"]
+|===
+| Constraint | Description
+| Scalability | The application is expected to be scalable to handle a 20% increase in workload.
+|===
 
-See https://docs.arc42.org/section-2/[Architecture Constraints] in the arc42 documentation.
 
 ****

docs/src/03_system_scope_and_context.adoc

@@ -6,70 +6,112 @@ ifndef::imagesdir[:imagesdir: ../images]
 
 [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:
+=== Business Context
 
-* Context diagrams
-* Lists of communication partners and their interfaces.
+[role="arc42help"]
+****
 
+.Business Context Diagram
 
-.Further Information
+:imagesdir: ../images
+image::03-BusinessContextDiagram-Lucidchart.png[Business Context Diagram]
 
-See https://docs.arc42.org/section-3/[Context and Scope] in the arc42 documentation.
 
-****
 
 
-=== Business Context
+.WIQ
+[cols="1,2,3"]
+|===
 
-[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.
+|*Comunication Partner*
+|*Inputs*
+|*Outputs*
 
-.Motivation
-All stakeholders should understand which data are exchanged with the environment of the system.
+| User
+| Registration and participation in the competition
+| Quiz results, correct and wrong questions, times and statistics
 
-.Form
-All kinds of diagrams that show the system as a black box and specify the domain interfaces to communication partners.
+| Database
+| Queries and user-related writing and questions
+| System-related results, questions and users
 
-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.
+| Wikidata
+| Requesting data for question generation from properties and categories
+| Data to generate questions and answers
 
-****
+| User's API
+| Request user information
+| User data, history and game statistics
+
+| Question's API
+| Request generated questions
+| History of generated questions and answers
+|===
+
+The agents involved in the WIQ system environment are the following:
+
+* *User*: interacts directly with the WIQ system through its web Frontend being able to register, participate in a game by answering questions and consult its history and statistics.
+
+* *Wikidata*: provides data that will be used in the automatic creation of questions.
+
+* *Database*: stores relevant WIQ data such as user information, game histories and the questions that have been generated. It also communicates directly with the system to manage and retrieve data.
 
-**<Diagram or Table>**
+* *User's API*: is given by the system to provide user information such as user histories and statistics.
+
+* *Question's API*: is given by the system to provide information about the questions generated.
+
+
+
+****
 
-**<optionally: Explanation of external domain interfaces>**
 
 === 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.
+.Technical Context Diagram
 
-.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.
+:imagesdir: ../images
+image::03-TechnicalContextDiagram-Lucidchart.png[Technical Context Diagram]
 
-.Form
-E.g. UML deployment diagram describing channels to neighboring systems,
-together with a mapping table showing the relationships between channels and input/output.
 
-****
+.WIQ
+[cols="1,2,3"]
+|===
+
+| Channels
+| Type
+| Input/Output
+
+| SSH
+| Input
+| User -> Frontend Web
+
+| HTTP/REST
+| Output
+| WIQ -> User's API
+
+| HTTP/REST
+| Output
+| WIQ -> Question's API
+
+| HTTP/REST
+| Input
+| Database -> Wikidata
+
+| HTTP
+| Input
+| Database -> WIQ
+
+| HTTP
+| Output
+| WIQ -> Database
+
+|===
 
-**<Diagram or Table>**
 
-**<optionally: Explanation of technical interfaces>**
 
-**<Mapping Input/Output to Channels>**

docs/src/04_solution_strategy.adoc

@@ -3,6 +3,40 @@ ifndef::imagesdir[:imagesdir: ../images]
 [[section-solution-strategy]]
 == Solution Strategy
 
+.Technology decisions
+
+|===
+|Technology|Description
+| _Git_ | _Software version control system_ 
+| _GitHub_ | _Cloud-based service that hosts the aforementioned version control system, Git._ 
+| _React_ | _JavaScript library that allows us to create interactive user interfaces in a simple way. It is based on components._ 
+| _MongoDB_ | _Open source, document-oriented database system_ 
+| _Docker_ | _A tool that makes it easy to create, deploy and run applications using containers. Containers allow you to package an application with all the parts you need, such as libraries and other dependencies, and deploy it as a single package._ 
+| _API_ | _Se usará una API externa para mostrar el mapa_ 
+| _Javascript_ | _An interpreted programming language based on prototypes, imperative and dynamic. We will use it on both frontend and backend._
+| _CSS_ | _A graphic programming language oriented to define the repesentation of a document._
+|===
+
+.Decisions on how to achieve key quality goals
+
+* Usability: the team will take care to design a clear and accessible interface for any user. This will be based on web usability standards.
+
+* Privacy: users' private information will be stored in such a way that it will not be accessible to external factors.
+
+* Security: we will take care to implement all the measures we deem appropriate to secure our application.
+
+* Testability: this is an important quality objective to ensure that the software is reliable, robust and error-free. It is important to implement appropriate software development practices, such as separation of concerns and modular design.
+
+.Relevant Organizational Decisions
+
+Regarding the organization within the team, we have taken the following decisions:
+
+* Extraordinary meetings, we do them through Discord or Microsoft Teams, because all team members are familiar with that tool.
+
+* Communication between team members occurs mainly through a WhatsApp group, but any problem that arises is also reflected as an issue in Github.
+
+* We use a Kanban board within github to have well organized and in a very clear way the tasks that each team member has to perform/is performing.
+
 
 [role="arc42help"]
 ****