Skip to content

Commit

Permalink
Update some parts of the documentation. Finished section 5
Browse files Browse the repository at this point in the history
  • Loading branch information
@Pelayori
Pelayori committed Mar 11, 2024
1 parent 3cc4cad commit d45ed0c
Show file tree
Hide file tree
Showing 10 changed files with 113 additions and 609 deletions.
88 changes: 3 additions & 85 deletions docs/src/01_introduction_and_goals.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,49 +2,6 @@ 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
****
WIQ is a game developed by HappySw for:

* Challenging "Saber y ganar" fans
* Learning to perform teamwork
* Passing the "Software Architecture" subject
* Improving as software engineers

=== 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/[Introducdction and Goals] in the arc42 documentation.
****

This web application, inspired by the famous Spanish TV show "Saber y ganar," consists of a mini-game of questions and answers.
In this game, the player is asked a question and presented with four possible answers, of which only one is correct.

Expand All @@ -60,57 +17,18 @@ The application automatically generates questions with the help of Wikidata (the
to constantly update the questions instead of storing them in a database.

=== 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,2,2"]
|===
|Nº|Atributo|Motivacion
| 1 | Efficiency | Access, creation of questions, and navigation between them should be fast to ensure user satisfaction.
| 2 | Usability | The application should be appealing to all fans of the original program while also offering a wide variety of questions.
| 3 | Manteinence | The application should ensure easy expansion and modification to provide users with new features.
| 3 | Manteinance | The application should ensure easy expansion and modification to provide users with new features.
| 4 | Availability | Our goal is to achieve at least 95% availability, ensuring that the system is always available for users to play.
| 5 | Responsiveness | The system must be responsive, providing a good user experience for those in desktop and mobile environments.
|===

=== 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"]
|===
|Role/Name|Expectations
Expand Down
25 changes: 1 addition & 24 deletions docs/src/02_architecture_constraints.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,29 +3,6 @@ ifndef::imagesdir[:imagesdir: ../images]
[[section-architecture-constraints]]
== Architecture Constraints


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

- *Mandatory Usage of WikiData API:*
The WikiData API must be utilized as an integral part of the system, and interactions with WikiData are obligatory for data retrieval and integration.

Expand All @@ -39,7 +16,7 @@ See https://docs.arc42.org/section-2/[Architecture Constraints] in the arc42 doc
The questions must have a limited time to be responded.

- *Questions must have 4 posible answers*
Each question will have one correct answer and several incorrect or distractor answers. Both the correct and incorrect answers will be generated automatically.
Each question will have one correct answer and several incorrect answers. Both the correct and incorrect answers will be generated automatically.

- *System API:*
System will allow accessing user information and the information of the generated questions through an API.
90 changes: 18 additions & 72 deletions docs/src/03_system_scope_and_context.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,91 +3,37 @@ ifndef::imagesdir[:imagesdir: ../images]
[[section-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).
.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:
* Context diagrams
* Lists of communication partners and their interfaces.
.Further Information
See https://docs.arc42.org/section-3/[Context and Scope] in the arc42 documentation.
****


=== Business Context


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

[plantuml,"Deployment diagram",png]
----
actor user
component System[
<<System>>
QuestionGame
]
component WikiData
database Database
@startuml
actor Player as user
actor "External Developers" as developers
component System [
<<System>>
QuestionGame
]
component WikiData as wikidata
database Database
user -down-> System : Uses
System -right-> Database : Stores/Fetches\nData
System -left-> wikidata : Retrieves\nInformation
developers -down-> System : Accesses via\nREST API
System -----> developers : Provides\nPlayer &\n Question Data
@enduml
user --> System
System --> Database
System --> WikiData
----

* **User:** Represents users who interact with the application to play games or view their history.
* **Player:** Represents users who interact with the application to play games or view their history.
* **System (QuestionGame):** The main system that hosts the game logic and manages user interactions.
* **WikiData:** Component used to retrieve data from Wikidata and automatically generate questions.
* **Database:** Stores system information, such as user data, generated questions, game history, etc.
* **External Developers:** Represents developers who access the system's REST API to retrieve player and question data.

=== 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,"Technical Context Diagram",png]
----
actor user
person developer
database Database
Expand Down
44 changes: 11 additions & 33 deletions docs/src/04_solution_strategy.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,47 +3,25 @@ ifndef::imagesdir[:imagesdir: ../images]
[[section-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
* 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.
.Motivation
These decisions form the cornerstones for your architecture. They are the foundation for many other detailed decisions or implementation rules.
.Form
Keep the explanations of such key decisions short.
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.
.Further Information
See https://docs.arc42.org/section-4/[Solution Strategy] in the arc42 documentation.
****

There are some placeholders for the decisions yet to be taken.

=== Technological Decisions
* Programming Language: Java will be used for system development because all team members are familiar with it, and we believe we can perform better using this language.
* Frontend Framework: SpringBoot will be adopted for frontend development because it allows us to deploy a web application using Java and provides numerous functionalities that greatly facilitate the implementation of project requirements, such as user authentication.
* Database: HSQLDB for local tests and MySQL for production were selected as the storages engines due to Java being the chosen language.
* Database: A relational database will be used. HSQLDB for local tests and MySQL for production were selected as the storages engines due to the modeled entities having a strong, fixed structure and the multiple relationships between them. Besides that, the team has experience with these databases and will allow an easier flow of development.

=== System Decomposition
The Model-View-Controler architecture pattern will be followed for structuring the system, dividing it into modules/classes responsible for the managment of the players, questions, answers and game, and the viiews of the frontend.
The Model-View-Controler architecture pattern will be followed for structuring the system, dividing it into modules/classes responsible for the managment of the players, questions, answers and game, and the views of the frontend.

=== Quality Goals
* Performance: A quick system response will be sought, especially during question generation and gameplay.
* Security: Security measures will be implemented to protect user information and ensure the integrity of generated questions.
* Availability:
* Responsiveness:
* Usability: The system must be easy to use, with a simple and intuitive interface.

=== Organizational Decisions
Development Methodology: GitFlow will be adopted for project management, facilitating collaboration and iterative delivery.
Development Methodology: GitFlow will be adopted for project management, facilitating collaboration and iterative delivery.

* The default branch: master. This branch will only be used to create new releases and will contain the most stable version of the system.
* The development branch: develop. This branch will be used to integrate the features developed by the team and will be the basis for creating new releases. This will have the largest commit amount, and will also have a stable version that could be deployed at any time.
* Feature branches: These branches will be used to develop new features, and will be created from the develop branch. After the feature is developed, it will be merged into the develop branch and branch can be deleted, although we will not usually delete branches.
* Fix branches: These branches will be used to fix bugs, and will be created from the develop branch. After the bug is fixed, it will be merged into the develop branch and branch can be deleted, although we will not usually delete branches.
Loading

0 comments on commit d45ed0c

Please sign in to comment.