Merge pull request #26 from Arquisoft/docs

Docs

docs/src/01_introduction_and_goals.adoc

@@ -2,22 +2,52 @@ ifndef::imagesdir[:imagesdir: ../images]
 
 [[section-introduction-and-goals]]
 == Introduction and Goals
+This project was created and developed by a development team composed of students from the Software Architecture course
+at the School of Computer Engineering of the University of Oviedo.
 
-ifdef::arc42help[]
-[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
-****
-endif::arc42help[]
+Last year, the company HappySw launched a project aimed at updating an experimental online version of a quiz
+competition similar to "Saber y Ganar" for the RTVE network.
+
+This year, the company ChattySw wants to expand its functionality so that contestants can interact with the application by
+receiving hints about the answers.
+
+This is the development team:
+
+* **Enol Rodríguez Hevia**: _UO287935_
+* **Alberto Fernández Azcoaga**: _UO179637_
+* **David González González**: _UO291047_
+* **Zinedine Álvarez Sais**: _UO294258_
+* **Alejandro Vega García**: _UO294615_
+* **Ignacio Llaneza Aller**: _UO294914_
+* **Daniel Uría Edroso**: _UO282813_
 
 === Requirements Overview
+* The system will include at least a web frontend that will display images and answers, as well as a hint system
+that will allow users to receive clues about the images.
+
+* 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.
+
+* The website must be deployed and accessible via the web.
+
+* The question data will be automatically generated from Wikidata API.
+
+* Users will be able to interact with the application for each question to obtain hints. This will be achieved through
+a language model (LLM) accessed via a provided API.
+
+* There will be a time limit to answer each question.
+
+* The system will provide API access to user information, which must be properly documented.
+
+* The system will also provide API access to the generated questions.
+
+* Each question will have one correct answer and several incorrect (distracting) answers. All answers will be genereated
+automatically.
+
+* A technique must be implemented to generate hints from Wikidata data while mitigating incorrect
+answers and hallucinations during interactions.
+
+
 
 ifdef::arc42help[]
 [role="arc42help"]
@@ -47,6 +77,20 @@ endif::arc42help[]
 
 === Quality Goals
 
+[options="header",cols="1,2,2"]
+|===
+|Priority|Quality Goal|Expectations
+| _1_ | _Usability_ | _All people should be able to enjoy and finish with success the application within a reasonable
+limit of time_
+| _2_ | _Maintainability_ | _The application should be easy to maintain, with clear, well-documented code and modular
+design that allows for future updates._
+| _3_ | _Accessibility_ | _The application should be usable by people with various disabilities, meeting common
+accessibility standards_
+| _4_ | _Availability_ | _The application should be available with minimal downtime, aiming for 99.9% uptime or better,
+and should be scalable to handle user demand_
+| _5_ | _Reliability_ | _The application should operate consistently and recover quickly from failures_
+|===
+
 ifdef::arc42help[]
 [role="arc42help"]
 ****
@@ -96,6 +140,13 @@ endif::arc42help[]
 [options="header",cols="1,2,2"]
 |===
 |Role/Name|Contact|Expectations
-| _<Role-1>_ | _<Contact-1>_ | _<Expectation-1>_
-| _<Role-2>_ | _<Contact-2>_ | _<Expectation-2>_
+| _Teachers_ | _Jose Emilio Labra, Pablo González, Irene Cid, Diego Martín_ | The teachers are the supervisors of the
+team and will help the team and should be accessible if the team needs them.
+| _Students_ | _Enol Rodríguez, Alberto Fernández, David González, Zinedine Álvarez, Alejandro Vega
+Ignacio Llaneza, Daniel Uría_ | _They are the development team. They should develop the application with success and
+learn through the process of the subject_
+| _Users_ | _Anyone who interacts with the application_ | They should be able to use the application without any
+problems and enjoy the experience.
+| _RTVE_ | _RTVE_ | They are the primary stakeholders in the application, as they commissioned it to allow their
+viewers to use it.
 |===

docs/src/02_architecture_constraints.adoc

@@ -3,6 +3,32 @@ ifndef::imagesdir[:imagesdir: ../images]
 [[section-architecture-constraints]]
 == Architecture Constraints
 
+=== Technical Constraints
+
+[options="header",cols="1,2"]
+|===
+|Constraint|Description
+|Wikidata|The application must interact with Wikidata to generate the questions and answers.
+|Git and GitHub|The project will have version control through Git. The repository will be in GitHub, where issues, "project" and wiki will be useful for project tracking.
+|LLM|The application must have a bot chat to interact with it. The chat have to be made by an LLM.
+|===
+
+=== Convention Constraints
+[options="header",cols="1,2"]
+|===
+|Constraint|Description
+|Arc42|The project documentation will be done following the Arc42 template. Arc42 is a framework for documenting software architecture that provides a clear and structured approach to communicate architectural decisions, components, and requirements.
+|Time|The project deadline is May 5th, but there will be sprints during the process. Important dates are February 24th for the first verion of de documentation, March 17th for a prototype of the application, and April 7th for an almost finished application.
+|===
+
+=== Organizational Constraints
+
+[options="header",cols="1,2"]
+|===
+|Constraint|Description
+|Team|The team is made up of seven members who never worked together. The members will reunite at least one time per week to catch up on work and establish next objectives.  
+|Time|The project deadline is May 5th, but there will be sprints during the process. Important dates are February 24th for the first verion of de documentation, March 17th for a prototype of the application, and April 7th for an almost finished application.
+|===
 
 ifdef::arc42help[]
 [role="arc42help"]

docs/src/09_architecture_decisions.adoc

@@ -3,6 +3,52 @@ ifndef::imagesdir[:imagesdir: ../images]
 [[section-design-decisions]]
 == Architecture Decisions
 
+[cols="3,5,3", options="header"]
+|===
+| Decision | Description | Status
+
+| *JavaScript*
+|*Decision:* We will use the JavaScript language to build both the front-end and the back-end of the application.
+
+
+*Justification:*
+We have chosen this technology because it comes from the initial project, and the whole team felt it was the right decision to continue using it.
+
+*Consequences:*
+Information about how the language works should be researched.
+
+| *Approved*
+
+| *React*
+|*Decision:* We have decided to use ReactJS for the front-end of our project.
+
+*Justification:*
+The decision was made because the base project provided to us already used ReactJS, and we considered this a great advantage to get started, as well as an opportunity to familiarize ourselves with a framework that is unfamiliar to many of us.
+
+*Consequences:*
+As a consequence, at the beginning, we will have to familiarize ourselves with this new technology for most of us, but we will be able to use the base project as an example.
+
+| *Approved*
+
+|*NodeJs*
+|*Decision:* We will use the Node.js framework to develop the application's backend.
+
+*Justification:* This technology was chosen because it is the default in the initial project and the ones we will use
+as a reference. The entire team agreed that it was appropriate to continue using it.
+
+*Consequences:* The team members will need to gain more knowledge about how this library works.
+|*Approved*
+
+| *MongoDB*
+|*Decision:* We have decided to use MongoDB for the development of our project's backend.
+
+
+*Justification:* The decision was made because the base project and other projects from the previous year used MongoDB. We see this as a great advantage to start with, as well as an opportunity to deepen our knowledge of a database management system that is less common for us compared to MySQL.
+
+
+*Consequences:* As a result, the learning curve will be steeper at first, but we will be able to take advantage of its benefits as we progress.
+| *Approved*
+|===
 
 ifdef::arc42help[]
 [role="arc42help"]

docs/src/10_quality_requirements.adoc

@@ -2,78 +2,42 @@ ifndef::imagesdir[:imagesdir: ../images]
 
 [[section-quality-scenarios]]
 == Quality Requirements
+In order to make Wichat a satisfactory final product, we find it crucial to set some quality requirements to live up with. These aspects are to influence architectural decisions and hence include some measurable features:
 
+- **Usability:** Intuitive and easy interfaces, reducing the volume of help needed in order to use the application.
+- **Mantainability:** Long-term enhancement support requiring minimal effort.
+- **Accesibility:** Make the application usable to people with diverse disabilities.
+- **Reliability:** Contistency and easy recovering.
+- **Availability:** Handling increased traffic without compromising performance.
 
-ifdef::arc42help[]
-[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)
+Moreover, some other non-functional requirements, while less prioritary, are still relevant:
 
-Here you can also capture quality requirements with lesser priority,
-which will not create high risks when they are not fully achieved.
-
-.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.
-
-
-.Further Information
-
-See https://docs.arc42.org/section-10/[Quality Requirements] in the arc42 documentation.
-
-****
-endif::arc42help[]
+- **Performance:** A smooth user experience, ensuring responsiveness and minimal delays.
+- **Security:** Basic measures, even if sensitive data is not handled.
+- **Compatibility:** Accesibility across diferent devices and screen sizes. 
 
 === Quality Tree
 
-ifdef::arc42help[]
-[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.
-
-
-****
-endif::arc42help[]
+image::../images/diagrama_escenarios_calidad.jpg[Diagrama de escenarios de calidad, primera versión]
 
 === Quality Scenarios
-
-ifdef::arc42help[]
-[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.
-****
-endif::arc42help[]
+[cols="3,3,5,2"]
+|===
+|**ID** | **QA** | **Scenario** | **Priority**
+| Q1.1 | Usability | The system must allow a player to start and quit a game without external help, within 3 minutes of opening the app, thanks to clear and simple interfaces. | High
+| Q1.2 | Usability | Users must be able to navigate between different game sections (settings, chat, etc.) in no more than 2 taps. It should take under 10 seconds for an average user. | High
+| Q2.1 | Mantainability | The addition of new questions must be quick and simple without interrupting the application flow. It should take approximately 5 minutes, this entailing no downtime for the application. | High
+| Q2.2 | Mantainability | The system must allow the implementation of new game models with minimal changes to the existing codebase, which should not take more than 1 hour. There should not be any regression in existing game functionality. | Low
+| Q3.1 | Accessibility | The application must support screen readers for users with visual impairments, guaranteeing as well buttons and answers that are simple to read. All interactive elements must have alternative text, and the screen reader should process the entire game in under 30 seconds for each screen. | High
+| Q3.2 | Accessibility | An option for high-contrast mode for users with daltonism or another visual disability must be provided. The color contrast between text and background must have a contrast radio of at least 4.5:1 | High
+| Q4.1 | Reliability | If the system fails during a game, it should allow the user to resume the game from the last saved state. No more than 1 minute of progess should be lost. | Medium
+| Q5.1 | Availability | The system must mantain 99.9% uptime over a month, including the peak usage period. Downtime must not overcome 45 minutes/month. | High
+| P1.1 | Performance | The product must respond to a player's request in less than 0.5s. | High
+| P1.2 | Performance | The application should give support to approximately 100 simultaneous request without significant downgrade in performance | Medium
+| S1.1 | Security | It must be ensured that player personal data (especially credentials) is encrypted, even if no sensitive data is handled. 0 data breaches must be admitted | Medium
+| S1.2 | Security | The system must log all user actions related to account creation and gameplay. Unauthorized attempts to read private account information should trigger an alarm within 5 minutes | Low
+| C1.1 | Compatibility | The game should work correctly on both mobile and desktop devices, adjusting the dessign for different screen sizes, at least between 4"-27". | Medium
+| C1.2 | Compatibility | The system must support the latest versions of popular browsers (Chrome, Safari, Firefox, etc.). It should be completely functional, with 0 visual/functional issues. | Medium
+
+|===

docs/src/11_technical_risks.adoc

@@ -4,24 +4,38 @@ ifndef::imagesdir[:imagesdir: ../images]
 == Risks and Technical Debts
 
 
-ifdef::arc42help[]
+
 [role="arc42help"]
-****
-.Contents
+
+== Contents
 A list of identified technical risks or technical debts, ordered by priority
 
-.Motivation
+== 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
+== Form
 List of risks and/or technical debts, probably including suggested measures to minimize, mitigate or avoid risks or reduce technical debts.
 
+[cols="1,1,3", options="header"]
+|===
+| Risk | Relevance | Considerations
+| Limited expertise in specific tools or programming languages | 2 | The team may encounter difficulties due to varying levels of familiarity with required tools and languages. To address this, we will prioritize the use of well-known technologies within the team while encouraging knowledge-sharing and individual learning efforts.
+| Lack of prior collaboration within the team | 1 | Since the team has not worked together before, there is a risk of inefficiencies in coordination. Establishing clear communication channels and regularly updating each other on progress will mitigate this issue.
+| Large team size | 1 | A higher number of contributors can complicate communication and workflow synchronization. Implementing structured meetings and documentation processes should help maintain efficiency.
+| Potential delays in integrating external APIs | 2 | Depending on external data sources, such as Wikidata, might introduce latency or downtime risks. Developing fallback mechanisms and caching strategies can help mitigate disruptions.
+| Knowledge disparity among team members | 2 | Some team members have prior experience, either from retaking the course or external knowledge, while others are learning these concepts for the first time. This can lead to uneven task distribution and communication gaps. Encouraging mentoring and pairing experienced members with those less familiar can help balance the workload and improve overall team efficiency.
+|===
+
 
-.Further Information
+=== Technical Debts
+[cols="1,3", options="header"]
+|===
+| Technical Debt | Considerations
+|===
 
+
+== Further Information
 See https://docs.arc42.org/section-11/[Risks and Technical Debt] in the arc42 documentation.
 
-****
-endif::arc42help[]
+
+

docs/src/12_glossary.adoc

@@ -36,9 +36,21 @@ endif::arc42help[]
 |===
 |Term |Definition
 
-|<Term-1>
-|<definition-1>
+|LLM
+|Large Language Model, a type of AI model that can generate human-like text.
 
-|<Term-2>
-|<definition-2>
+|Chatbot
+|It's a computer programme that simulates human conversation with an end-user.
+
+|Framework
+|A framework is an outline that provides a basic structure for developing a project with specific objectives, a kind of template that serves as a starting point for the organisation and development of software.
+
+|Front-end
+|Front-end includes drop-down menus, images, icons, colours, graphic elements, animations and everything related to improving the user's browsing experience.
+
+|Back-end
+|Back-end is responsible for the server, database and application logic.
+
+|API
+|APIs are mechanisms that allow two software components to communicate with each other through a set of definitions and protocols.
 |===