- - -
1. Introduction and Goals
-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
-
-
1.1. Requirements Overview
- -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.
--
-
-
-
The player must register with a name.
-
- -
-
The player must answer the question within a time limit.
-
- -
-
If the player does not answer, it will be counted as an incorrect response.
-
- -
-
Each correct answer earns points.
-
- -
-
Optionally, the score can be saved in a ranking.
-
-
For all those "Saber y ganar" viewers who wanted to participate in the show, this application is ideal for testing their knowledge.
-The application automatically generates questions with the help of Wikidata (the page that supports Wikipedia and many other wikis) -to constantly update the questions instead of storing them in a database.
-1.2. Quality Goals
-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):
-
-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…
-A table with quality goals and concrete scenarios, ordered by priorities
-| 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. |
-
1.3. Stakeholders
- -| Role/Name | -Expectations | -
|---|---|
HappySw |
-A company developing the application aiming to earn money through its development and recognition at the Spanish level. |
-
RTVE |
-A Spanish television network that hired the development to promote its program. |
-
Uniovi students |
-The application developers who want to pass the subject. |
-
ArquiSoft teachers |
-The evaluators of the program development and final version who want their students to pass. |
-
2. Architecture Constraints
--
-
-
-
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.
-
- -
-
Web Frontend Requirement: -The system must include at least one web frontend, and it is mandatory for deployment.
-
-
-Users log in and game history: - The users will be able to register in the system and consult their participation history in the system.
--Limited time in questions: - 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.
--System API: - System will allow accessing user information and the information of the generated questions through an API.
-3. System Scope and Context
-3.1. Business Context
- -
--
-
-
-
User: 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.
-
-
3.2. Technical Context
- -
--
-
-
-
User Agent: Represents the web or mobile interface used by users.
-
- -
-
QuestionGame server: The server-side components, including the Frontend, QuestionGame logic, User’s API, and Question’s API.
-
- -
-
HTTPS: Represents the communication channels, with HTTPS being the protocol used for secure communication.
-
- -
-
Question Generation: Represents the means used for question and answers generation.
-
- -
-
Database: Represents whichever system used for data persistence.
-
- -
-
To be decided: Indicates that specific details about the channels and protocols are yet to be determined.
-
-
3.2.1. Input/Output Mapping Table
-| Component | -Input/Output | -Channel/Protocol | -
|---|---|---|
User’s API |
-User registration, game history |
-HTTPS |
-
Question’s API |
-Question data retrieval |
-HTTPS |
-
Frontend |
-User interactions, game display |
-HTTPS |
-
Database |
-User data, game history, questions |
-Specific database driver |
-
WikiData |
-Data for question generation |
-HTTP |
-
4. Solution Strategy
-There are some placeholders for the decisions yet to be taken.
-4.1. 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: [Database] was selected as the storage engine due to [reasons].
-
-
4.2. 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.
-4.3. 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.
-
-
4.4. Organizational Decisions
-Development Methodology: GitFlow will be adopted for project management, facilitating collaboration and iterative delivery.
-5. Building Block View
-The building block view shows the static decomposition of the system into building blocks (modules, components, subsystems, classes, interfaces, packages, libraries, frameworks, layers, partitions, tiers, functions, macros, operations, data structures, …) as well as their dependencies (relationships, associations, …)
-This view is mandatory for every architecture documentation. -In analogy to a house this is the floor plan.
-Maintain an overview of your source code by making its structure understandable through -abstraction.
-This allows you to communicate with your stakeholder on an abstract level without disclosing implementation details.
-The building block view is a hierarchical collection of black boxes and white boxes -(see figure below) and their descriptions.
-
-Level 1 is the white box description of the overall system together with black -box descriptions of all contained building blocks.
-Level 2 zooms into some building blocks of level 1. -Thus it contains the white box description of selected building blocks of level 1, together with black box descriptions of their internal building blocks.
-Level 3 zooms into selected building blocks of level 2, and so on.
-See Building Block View in the arc42 documentation.
-5.1. Whitebox Overall System
- -
--
-
- Motivation -
-
-
The purpose of this whitebox is to provide a clear, simple overview without delving into details of how the WIQ system interacts -with the external Wikidata service to obtain the necessary data for question generation. By presenting this interaction clearly, -stakeholders can easily understand how the WIQ system integrates with external data sources and how that information is used to -fulfill system requirements related to the automatic generation of questions.
-
- - Contained Building Blocks -
| Name | -Description | -
|---|---|
User |
-It represents the user interacting with the WIQ application. |
-
WIQ |
-It represents the main WIQ application. |
-
Wikidata |
-External service used by WIQ to obtain data and generate questions. |
-
DataBase |
-The DataBase that save the accounts of the players and the games that they played. |
-
-
-
- In progress… -
-
-
We have yet to decide the precise composition of our system so we can´t fill the rest of this section yet.
-
- - Important Interfaces -
-
-
<Description of important interfaces>
-
-
5.1.1. <Name black box 1>
- -<Purpose/Responsibility>
-<Interface(s)>
-<(Optional) Quality/Performance Characteristics>
-<(Optional) Directory/File Location>
-<(Optional) Fulfilled Requirements>
-<(optional) Open Issues/Problems/Risks>
-5.1.2. <Name black box 2>
-<black box template>
-5.1.3. <Name black box n>
-<black box template>
-5.1.4. <Name interface 1>
-…
-5.1.5. <Name interface m>
- -5.2. Level 2
- -5.2.1. White Box <building block 1>
- -<white box template>
-5.2.2. White Box <building block 2>
-<white box template>
-…
-5.2.3. White Box <building block m>
-<white box template>
-5.3. Level 3
- -5.3.1. White Box <_building block x.1_>
- -<white box template>
-5.3.2. White Box <_building block x.2_>
-<white box template>
-5.3.3. White Box <_building block y.1_>
-<white box template>
-6. Runtime View
-6.1. User Authentication
-
-6.2. Question Generation
-
-6.3. User Responds to a Question
-
-6.4. User Checks their History
-
-6.5. Access to User Information via an API
-
-6.6. Access to Generated Questions Information via an API
-
-7. Deployment View
-The deployment strategy for our game, which leverages the Wikidata API to dynamically generate questions, is built around a Docker-based infrastructure. This approach allows for the encapsulation of our Java Spring Boot application within a Docker container, simplifying deployments across different environments (development, testing, and production) while ensuring consistency and isolation.
-7.1. Infrastructure Level 1
-Our application is containerized using Docker, enabling us to deploy the entire stack as a single .jar file that includes the web server. This method ensures that our application can be easily moved across environments or scaled up as needed without significant changes to the infrastructure.
Overview Diagram: -The infrastructure features a single Docker container that hosts the Java Spring Boot application. This container communicates with external services, such as the Wikidata API, to fetch data in real-time and generate game questions.
-The primary motivation behind using Docker for deployment is to streamline the development and deployment processes. By containerizing the application, we reduce discrepancies between environments, making it easier to develop, test, and deploy with confidence.
--
-
-
-
Portability: Docker containers can run on any system that has Docker installed, reducing environment-specific bugs.
-
- -
-
Scalability: While we start with a single container, the setup can be easily scaled using Docker Compose or Docker Swarm if the need arises.
-
- -
-
Efficiency: Docker utilizes resources more efficiently than traditional VMs, allowing for faster startup times and lower overhead.
-
-
-
-
-
-
Web Server/Application (.jar file): Packaged within a Docker container, it includes all necessary dependencies to run independently across any Docker-supported platform.
-
- -
-
External APIs (e.g., Wikidata API): Accessed over the network, these APIs provide dynamic content for the game.
-
-
7.2. Infrastructure Level 2
-At this level, we describe the Docker container configuration that encapsulates our application.
-7.2.1. Docker Container
-Our app’s Docker container is built from a Java base image, which is then layered with our application’s .jar file.
In addition to the Spring boot standalone file, we also use the official MySQL server docker container image brought by DockerHub. This is our database server and it is used to store the game data, such as user scores, questions, etc. and all the other persistent data.
This setup encapsulates the entire runtime environment required for our application, and does not require extensive configuration.
-
-This diagram illustrates the internal structure of our Docker containers structure. It shows the Java Spring Boot application, including the embedded web server, packaged as a .jar file and the MySQL server. The application interacts with external APIs, like the Wikidata API, to retrieve data necessary for generating game questions. The containerized approach ensures that the application can be deployed consistently across any environment that supports Docker.
8. Cross-cutting Concepts
-The following concepts provide a foundation for the design and implementation of the trivia game project, which utilizes the Wikidata API for dynamic question generation and employs a hexagonal architecture for its Java Spring Boot application.
-8.1. Domain Model
-The domain model for our game includes entities such as Question, Category, Player, Role, and GameSession. These are crucial for representing the game’s data and logic. The model serves as the basis for interactions within the application and between the application and the database.
-
-8.2. Hexagonal Architecture
-Our application is structured using hexagonal architecture principles, which prioritize the separation of core logic from peripheral concerns like user interface and external API interactions.
-This architecture facilitates the creation of a flexible and maintainable codebase. It allows for easy adaptation to changes in external services or user interface technologies without impacting the application’s core logic.
-8.3. Java Persistence API (JPA) for Data Management
-We use JPA for data persistence to abstract and handle all database operations, allowing for a more streamlined and object-oriented approach to data handling.
-JPA enables us to map our domain objects to the database schema with ease, providing a clear layer of abstraction that simplifies data persistence and retrieval while ensuring our application remains agnostic of the underlying database technology.
-8.4. Logging with Slf4j and System.out
-For monitoring runtime behavior and troubleshooting, the project utilizes Slf4j, bundled with Sprint Boot, and System.out for logging. While Slf4j offers more sophisticated logging capabilities, System.out is used for straightforward, immediate console output.
-Slf4j is configured to capture various levels of output, which can be directed to multiple destinations such as console, files, or even remote logging servers. For simplicity and immediacy during development or less complex deployment scenarios, System.out is employed for logging output directly to the console.
-8.5. Security
-Security is a key concern, ensuring that user data and game integrity are protected. We implement standard security practices at various levels within the application
-This includes securing the web layer with Spring Security, encrypting sensitive data, and protecting against common web vulnerabilities.
-8.6. Performance Optimization
-Performance optimization is considered in all aspects of the application, from the efficient design of the domain model to the configuration of the persistence layer.
-We ensure that database interactions are efficient through JPA’s caching and lazy loading. Queries are optimized to fetch only the necessary data, minimizing response times and resource utilization.
-8.7. Continuous Integration and Continuous Deployment (CI/CD)
-The project adheres to CI/CD practices, facilitating automated testing, building, and deployment processes which contribute to the robustness and reliability of the application.
-Our CI/CD pipeline automates the process of integrating code changes, building the application, running tests, and deploying the Dockerized application, ensuring consistent and reliable delivery of updates.
-8.8. Scalability
-Designing for scalability, the application can accommodate an increasing number of users and interactions without performance degradation. -.Explanation: -Scalable solutions such as Docker containers allow the application to be deployed in a distributed environment, where resources can be adjusted based on demand.
-9. Architecture Decisions
-The purpose of this section is to create an ordered list of architectural decisions that we will make as we develop the project. This list will be ordered according to the importance of the decision.
-10. Quality Requirements
-10.1. Quality Tree
- -Note: Items (1), (2), (3) in the table below repeat the higher-level quality requirements of Chapter 1.2.
-| Quality category | -Quality | -Description | -Scenario | -
|---|---|---|---|
Usability |
-Ease of use |
-The application shall be easy to use by the user, with intuitive functionality. |
-SC1 |
-
| - | Familiarity of the environment (2) |
-The application should appeal to all fans of the original programme and provide a wide variety of questions. |
-- |
Performance |
-Accuracy |
-The questions in the application must be accurate, both the question and the correct answer. |
-- |
| - | Efficiency (1) |
-Accessing, creating questions and moving between questions should be fast to ensure user satisfaction. |
-- |
| - | Robustness |
-The system shall function reliably in all specified environments and operating conditions. |
-SC2 |
-
Safety |
-Integrity |
-The application shall be user-friendly, with intuitive functionality. |
-- |
Maintainability and support |
-Maintenance (2) |
-The application shall ensure that it can be easily extended and modified to provide new features to users. |
-- |
Cultural and Regional |
-Multilingual |
-The user interface texts must be able to be converted by a translation file into different languages with an ASCII character set. |
-SC3 |
-
10.2. Quality Scenarios
- -| Identification | -Scenario | -
|---|---|
SC1 |
-A user who is not familiar with the application will know how to use it after a few minutes of instruction. |
-
SC2 |
-The application should be able to be run from any device, from a computer to a mobile phone, without losing formatting. |
-
CS3 |
-With the appropriate translation files replacing the default language (English), all displayed and printed texts now appear in this language. |
-
11. Risks and Technical Debts
-| Priority | -Risk | -Description | -
|---|---|---|
High |
-Migration to Java |
-
- Migration from the current project language, JavaScript (JS), to Java - |
-
Medium |
-IDE Configuration |
-
- Version compatibility, extensions and other preferences to work perfectly without conflicts - |
-
Medium |
-Database |
-
- Discuss which database is best for the project - |
-
Low |
-Docker |
-
- Know how docker works, what it is for, how it is used and what its alternatives could be. - |
-
| Priority | -Debt | -Description | -
|---|---|---|
Low |
-Microservices |
-
- Research about microservices and what they can contribute to the project - |
-
| Term | Definition
-|WikiData |A collaborative platform that provides structured data for Wikimedia projects, including Wikipedia.
-|Question | Entity that encapsulates details of the trivia questions.
-|Category | Classifies questions into various topics, each question can only belong to one category.
-|Player | Represents users and their interactions with the game
-|GameSession | Maintains the state of play, including scores and progress.
-