WIQ es04b

The requirements of the application are as follows:

The overall goal of the application is to provide a fun and challenging experience for the user, while also providing a way to test their knowledge.

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.

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

This section provides an overview of the main components of the system and their interactions. The core of the system is the WIQ (WiqEs04bApplication) component, which interfaces with Users, Wikidata for question generation, a Database for persistence, and offers a REST API for External Developers.

For Level 2 of the Building Block View, the WIQ (QuestionGame) system is further decomposed into four primary components that define its operational structure. Each component is designed to fulfill specific roles within the architecture, ensuring the system’s functionality and responsiveness to user interactions.

In Level 3, we take a closer look at the API Management component, breaking it down into two essential services: the Player Information API and the Question Information API. These services are fundamental to the system’s ability to interact with external applications, providing necessary functionalities with a focus on usability and security.

This level of documentation provides a structured and clear view of the system’s architecture, particularly focusing on its integration points. By balancing formal language with accessibility, we aim to communicate effectively with a broad audience of stakeholders, ensuring understanding and transparency in the system’s design.

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.

At this level, we describe the Docker container configuration that encapsulates our application.

The domain model for our game includes entities such as Question, Category, Player, Role, or 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.

Source code

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.

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.

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.

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.

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.

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.

Designing for scalability, the application can accommodate an increasing number of users and interactions without performance degradation.

Scalable solutions such as Docker containers allow the application to be deployed in a distributed environment, where resources can be adjusted based on demand. Given that we use a monolithic approach, the application can be easily scaled horizontally by deploying multiple instances of the same service and connect them to a load balancer in order to distribute the load.

The two classes mentioned before use a JSON file that stores the question templates. These templates are used to generalize the question generation process. The JSON file is structured as follows:

Here’s an example of how you could use this JSON structure to query information:

To execute a query you just need to build a SPARQL query that retrieves the data you need. For example, to get the capital of a country, you could use the following query:

Once you have a query the next step is to add it to thr JSON file. Following the previous example, you should start declaring a new object inside the questions array of the Geography category. You should fill the type, statements, question, answer, and sparqlQuery properties with the appropriate values. For the type field you could add the value "capital", for the statements array you could add the statements in different languages also adding to them the placeholder that you used in the question_placeholder field. For the question field you should add the value "countryLabel", for the answer you should add the value "capitalLabel". For the sparqlQuery field you should replace in your original query every instance of "countryLabel" with the value of question_placeholder and "capitalLabel" with the value of answer_placeholder. The final object should look like the one showed in the JSON hierarchy example.

By following this approach, you can dynamically generate a wide variety of questions based on the structured data stored in your JSON file. This allows for flexibility and scalability in your question generation process.

Once we have the JSON file with the question templates, we can start generating questions. Each time the application starts the QuestionGeneratorService class reads the JSON file and stores the question templates in memory. This way, the application can generate questions without needing to read the file each time. These templates are stored in a synchronized stack, which allows for thread-safe access to the templates. When the application starts after reading the JSON file and storing the templates the QuestionGeneratorService class deletes all the questions that are stored in the database. After deleting the questions, the QuestionGeneratorService starts a cycle that generates all the questions in all the 3 main languages of the app for a specific type of question each two and a half minutes. This cycle is repeated until all the question types are generated. After this every 24 hours the cycle will start again with the parsing of the JSON, filling the Stack, emptying the database and generating the questions. All this process can be forced by an Admin user through the Admin panel in the app where an Admin can change the JSON (which will lead to the restart of the question generation process) or delete all questions.

In our project, we have implemented unit tests for various components of the application. The tests are written in Java and use the JUnit 5 framework for testing. We also use the Spring Boot Test framework for testing Spring Boot applications, which provides utilities and annotations to test the application in a way that is very close to its actual runtime behavior. The tests are located in the src/test/java/com/uniovi directory. The main test class is Wiq_UnitTests.java, which contains tests for various services and repositories in our application.

For the integration tests, we have implemented tests using the Cucumber framework. Cucumber is a tool that supports Behavior-Driven Development (BDD), which allows you to write tests in a human-readable format. The tests are written in Gherkin, a language that is easy to understand and write. To implement each one of the cucumber steps we have used the Selenium framework, which allows us to interact with the web browser and automate the tests mocking the user’s behavior. All the cucumber files are located in the src/test/resources/features directory. We’ve implemented all the cucumber steps in the src/test/java/com/uniovi/steps directory. The main test class is CucumberRunnerTests.java in src/test/java/com/uniovi, which you should run to execute the integration tests.

We have implemented load tests to evaluate the performance of our website under extreme situations. For this we use the "Gatling" application, which allows us to evaluate a set of web requests by simulating the number of users who make them simultaneously. All tests have been carried out with a load of 1, 250, 1000, 2000 and 5000 users, for the following use cases: login, show profile, show apikey, play a game, show personal ranking, show the global ranking, change the language, return to the index and log out.