About arc42
arc42, the template for documentation of software and system architecture.
Template Version 8.2 EN. (based upon AsciiDoc version), January 2023
Created, maintained and © by Dr. Peter Hruschka, Dr. Gernot Starke and contributors. See https://arc42.org.
1. Introduction and Goals
WIChat is an interactive web-based quiz game where users guess locations from images, earning rewards for correct answers. The system generates questions and hints using Wikidata and an external LLM, enhancing user experience through conversational clues. The platform includes user registration, game history tracking, and various gameplay modes.
1.1. Requirements Overview
1.1.1. Business Goals
-
Enhance audience engagement through an interactive online quiz.
-
Automate question and hint generation using AI and Wikidata.
-
Provide a scalable and accessible web-based trivia game.
1.1.2. Essential Features
-
User registration, authentication, and game history tracking.
-
Quiz system with image-based multiple-choice questions.
-
AI-powered hint system via an external LLM API.
-
Timed responses, scoring, and rewards.
-
API access for user data and question generation.
1.1.3. Essential Functional Requirements
-
Automatic question and answer generation from Wikidata.
-
Conversational AI hints for user assistance.
-
Fair play enforcement with time constraints.
-
User performance tracking and leaderboard system.
1.2. Quality Goals
| Priority | Quality Goal | Motivation |
|---|---|---|
High |
Scalability |
Ensure the system can support a growing number of users and future feature expansions. |
High |
Performance |
Provide low-latency interactions for real-time quiz gameplay. |
High |
Security |
Protect user data and prevent cheating or unauthorized access. |
High |
Usability |
Ensure that users can easily navigate and interact with the application. |
Medium |
Availability |
Guarantee uptime and reliability for a seamless user experience. |
Medium |
Maintainability |
Use a modular architecture to facilitate updates and future improvements. |
Low |
Internationalization |
Ensure the system supports multiple languages and cultural adaptations for a global audience. |
1.3. Stakeholders
| Role/Name | Contact | Expectations |
|---|---|---|
RTVE |
RTVE Team |
Ensure an engaging and well-integrated quiz experience aligned with their brand. |
Users |
Players |
Enjoy a fun, challenging, and fair gameplay experience. |
Developers |
Dev Team |
Work with a clear architecture and maintainable codebase. |
System Administrators |
Ops Team |
Maintain reliable deployment, monitoring, and observability. |
LLM API Providers |
Third-party LLM Providers |
Ensure access to the language model API. |
Hosting Provider |
Microsoft Azure |
Provide reliable and scalable hosting solutions for the application. |
2. Architecture Constraints
2.1. Organizational Constraints
| Constraints | Explanations |
|---|---|
Fixed data source |
Questions, images, and hints must be generated exclusively from Wikidata data. |
External language model |
A LLM accessed through a predefined API will be used, limiting the choice of models, customization options, and potential for fine-tuning or adaptation to specific application needs. |
2.2. Technical Constraints
| Constraints | Explanations |
|---|---|
Mandatory web platform |
The application must be accessible via web browsers and deployed online. |
Conversational hints logic |
Hints must be generated while mitigating hallucinations using specific techniques. |
Docker for containerization |
Docker must be used for application containerization, as the solution’s architecture requires that all components be packaged into containers to ensure portability, isolation, and compatibility across environments |
GitHub Actions for CI/CD |
GitHub Actions must be used for automating the CI/CD pipeline, ensuring seamless integration, testing, and deployment processes. |
2.3. Legal and Regulatory Constraints
| Constraints | Explanations |
|---|---|
Privacy compliance |
User data must comply with regulations like GDPR. |
Data licensing |
Images and data used must adhere to Wikidata licensing policies and ensure proper usage. |
2.4. Product Constraints
| Constraints | Explanations |
|---|---|
Fixed question format |
Each question must have one correct answer and several incorrect ones generated automatically, with balanced and coherent options. |
User registration |
The system must include functionalities for registration, participation history, and statistics. |
Mandatory interaction |
Users must interact with the system to obtain conversational hints about the questions. |
Time-limited answers |
Each question must be answered within a set time, necessitating efficient interaction and time management design. |
Automatic generation |
Both the questions and distractors must be generated automatically, restricting manual design to ensure consistency and scalability. |
2.5. Operational Constraints
| Constraints | Explanations |
|---|---|
Scalability |
The system must support multiple simultaneous users. |
Monitoring and deployment |
Observability and deployment automation are required. The deployment must maintain high availability, meaning the infrastructure must be capable of handling potential failures with minimal service disruption, ensuring maximum uptime. Due to this, an online virtual machine provider must be selected for deployment. |
Docker for deployment |
Docker is also used in the deployment process to ensure efficient management of production, testing, and development environments. This facilitates scalability and maintenance by allowing more precise control over dependencies and configurations. |
3. Context and Scope
3.1. Business Context
WIChat is an interactive web-based quiz game application, inspired by "Saber y Ganar". Users can register, log in, and play the game, where they are presented with images and have to guess the associated place or object. The novelty lies in the integration of a conversational language model (LLM), which allows users to interact with the game and get hints for the answers dynamically. The questions and images are generated from Wikidata, providing an automated, real-time experience.
3.1.2. Involved Actors
-
User: Person who accesses the application to play one of the multiple games, review their history, manage their data, etc.
-
Administrator: Responsible for managing system infrastructure and security.
-
WebApp:Main interface of the system that connects with internal services.
-
Database: MySQL used to store user information, game history, and question data.
-
External APIs: External service used to retrieve image and metadata for question generation and AI-generated quiz hints.
-
External developers: Developers who interact with the API to retrieve and retrieve player and questions data.
3.1.3. Business Context Table
| Communication Partner | Inputs | Outputs |
|---|---|---|
User |
Login credentials, game interactions, answer selections |
Quiz questions, score updates, hints, rewards |
Admin |
System configurations, user management requests |
System status updates, logs, user management responses |
Database |
User data, game records, question storage |
Stored authentication, game history, retrieved player and question data |
WebApp |
User actions, API requests to internal services |
UI responses, game content, interaction processing |
ExternalAPIService (LLM, Wikidata, etc.) |
Quiz prompts, data requests for images and metadata |
AI-generated questions, retrieved images, metadata, and hints |
LLM Provider |
Quiz prompts, hint generation requests |
AI-generated questions, answers, and hints |
WikiData |
Data requests for images and metadata |
Retrieved images and metadata for questions |
External Developers |
API requests for player and question data |
Retrieved player information, question lists, game history |
3.2. Technical Context
The system consists of several services developed in Java using Spring Boot, utilizing Spring Security for authentication and authorization. The frontend is developed using HTML, and the backend communicates through direct method calls for internal service interactions, while external communication is handled via REST API over HTTPS. A relational database (MySQL) is used for data persistence
3.2.1. Technical Interfaces
-
User Interface (Web Application): Provides access to the game and player interactions.
-
Spring Security: Manages authentication and authorization for user access.
-
User Service: Handles user authentication, history retrieval, and profile management.
-
Question Service: Manages question generation, retrieval, and displays images.
-
LLM Service: External API providing dynamically generated hints based on input data.
-
WikiData Service: External API fetching metadata and images for questions.
-
Database (MySQL): Stores user data, game history, and question information.
-
External API: Provides access for third-party developers to retrieve question data.
3.2.2. Mapping Input/Output to Channels
| Participants | Input/Output | Channel/Protocol |
|---|---|---|
User |
Login credentials, game interactions, answer selections |
HTTPS (WebApp) |
Admin |
System configurations, user management requests |
HTTPS (WebApp) |
Web Application |
User actions, API requests to services |
Direct Method Calls |
Spring Security |
Authentication requests, authorization checks |
Direct Method Calls |
User Service |
Authentication requests, history retrieval |
Direct Method Calls |
Question Service |
Question retrieval, image requests |
Direct Method Calls |
LLM Service |
Hint generation requests, AI responses |
REST API (HTTPS) |
WikiData Service |
Data requests for metadata and images |
REST API (HTTPS) |
Database (MySQL) |
Stores user data, game history, and questions |
SQL Connection |
External Developers |
API requests for player and question data |
HTTP (ExtAPI) |
4. Solution Strategy
4.1. Introduction and Purpose
We chose to build upon last year’s base application, selecting technologies that we were most comfortable with and that aligned well with the project requirements. The application consists of a web-based platform where users can register, compete against others, and answer questions. Additionally, it integrates a Large Language Model (LLM) to provide hints and assist users in responding to quiz questions.
This section outlines the key architectural decisions and strategies that shape the system, including technology choices, architectural patterns, and approaches to achieving the system’s quality goals.
4.2. Technology Decisions
-
Architecture: Model-View-Controller (MVC) pattern.
-
Backend: Spring Boot for API development and business logic.
-
Frontend: Thymeleaf for dynamic rendering within the MVC framework.
-
Database: HSQLDB for structured data storage.
-
Authentication: Spring Security with JWT for secure access control.
-
Hosting & Deployment: Docker and Docker Compose to ensure scalable, consistent, and efficient application deployment across environments.
-
Integration: Wikidata API for question generation and an external LLM API for hints.
4.3. System Decomposition
The application follows an MVC architecture with clearly defined layers:
-
Model Layer: Represents the data and business logic.
-
View Layer: Uses Thymeleaf templates for rendering dynamic content.
-
Controller Layer: Manages requests and responses, handling business logic with Spring Boot.
-
Database: Stores user data, questions, and game history in PostgreSQL.
-
LLM Integration: Provides AI-generated hints via an external API.
-
External APIs: Wikidata for question data and third-party services for deployment.
4.4. Strategies for Quality Goals
| Priority | Quality Goal | Strategy |
|---|---|---|
Medium |
Scalability |
Load balancing, database connection pooling, and optimized queries. |
High |
Performance |
Asynchronous processing with Spring Boot and caching mechanisms. |
High |
Security |
Spring Security, encrypted storage, and role-based access control. |
Medium |
Availability |
Deployment of the server on Azure Cloud Services for easy distribution over the internet, with control over when the server is active. |
Medium |
Maintainability |
Modular architecture with well-documented Spring Boot services. |
4.5. Organizational Decisions
-
Development Process: Agile methodology with Scrum.
-
Collaboration Tools: GitHub for version control and GitHub kanban for work distribution.
-
Testing Strategy: Unit tests with JUnit and integration tests with Selenium + Cucumber.
4.6. Justification
These decisions ensure that the system is scalable, secure, and maintainable, leveraging Spring Boot’s powerful ecosystem for enterprise-grade applications while integrating AI-powered hints and automated question generation.
5. Building Block View
The Building Block View elaborates on the static structure of the system. It decomposes the system into building blocks like modules, components, subsystems, and others, detailing their responsibilities and relationships.
5.1. Whitebox Overall System
This section provides an overview of the main components of the system and their interactions. The core of the system is the WIChat (WIChatEs04bApplication) component, which interfaces with Users, Wikidata for question generation, a LLM API for hint generation, a Database for persistence, and offers a REST API for External Developers.
5.1.1. Motivation
The decomposition provides a clear, high-level overview of how the WIChat system interacts with users, external services (Wikidata), stores data (Database), and interfaces with external developers through the REST API. This modularity supports scalability and maintainability.
5.1.2. Contained Building Blocks
| Name | Description |
|---|---|
User |
Represents the end users of the WIChat application, interacting with the system to play games and view their history. |
WIChat (WIChatEs04bApplication) |
The central component that manages gameplay logic, user interactions, and integrates external data for question generation. |
Wikidata |
An external service utilized by the WIChat system to retrieve data for dynamically generating quiz questions. |
Database |
Maintains persistent storage for user data, game history, and generated questions, ensuring data integrity and availability. |
External Developers |
Developers or systems that interact with the WIChat system via the REST API to access or modify player and question data. |
LLM API |
An external service employed by the WIChat system to retrieve data for generating hints for questions. |
5.2. Level 2
For Level 2 of the Building Block View, the WIChat (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.
-
GameService: This component acts as the core of the QuestionGame, orchestrating the flow of games, managing question selection, enforcing game rules, and tracking scores. It ensures that gameplay proceeds smoothly and according to the predefined logic, offering a seamless experience for the user.
-
PlayerService: Responsible for handling user accounts, this component manages registration, authentication, and profile management. It safeguards user data while providing a personalized experience through game history tracking and preference settings.
-
QuestionService: This component interacts directly with the Wikidata service to fetch data for question generation. It processes and curates content to produce relevant, challenging questions for the game, thereby ensuring a varied and educational experience.
-
RestApiService: Serving as the gateway for external developers, this component exposes a set of RESTful APIs that allow access to player information and question data. It handles request processing, authentication, and data delivery, facilitating third-party integrations and extensions of the WIChat platform.
-
LLMService: This component interacts directly with the LLM API to fetch data for question generation. It processes and curates content to produce relevant, challenging questions for the game, thereby ensuring a varied and educational experience.
5.3. Level 3
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.
-
Player Information API: This API serves as the gateway for external applications to access and manage player data. It allows for operations such as retrieving player profiles, updating personal information, and viewing game history. The design prioritizes data security, ensuring safe and secure access to sensitive information. The interface is straightforward, designed for ease of use while maintaining comprehensive functionality.
-
Question Information API: Dedicated to the dynamic world of quiz questions, this API facilitates the retrieval of questions and submission of answers. It stands as a bridge between the system’s vast question repository and external applications, enabling a seamless flow of information. The API adheres to clear and logical request and response structures, ensuring efficient and effective communication. Security measures are in place to protect the integrity of the question data and the fairness of the game.
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.
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
6.7. User Interacts with the Game and Requests a Hint
6.7.1. Error Handling (During Gameplay)
If any data retrieval fails (game state, questions, hint, etc.), the Backend will send an error response, and the Frontend will display an appropriate message to the User, such as "Could not retrieve hint" or "Game error occurred."
7. Deployment View
The deployment strategy for our game, which uses the Wikidata API to dynamically generate questions, is built around a Docker-based infrastructure. This approach enables a consistent and scalable deployment across various environments (development, testing, production) by encapsulating the Java Spring Boot application within a Docker container.
7.1. Infrastructure Level 1
The system is containerized using Docker, allowing the entire stack to be deployed as a single .jar file, which includes the Java Spring Boot application and an embedded web server. This architecture reduces environment-specific discrepancies and facilitates easy scalability.
Overview Diagram: The infrastructure features a Docker container running the Java Spring Boot application, which communicates with external services like the Wikidata API for real-time data fetching and dynamic question generation. Additionally, the game will connect to an external Large Language Model (LLM) API to handle text-based queries for generating hints when the user is struggling with answering questions.
Docker was chosen to simplify the development and deployment processes, enabling consistent behavior across environments. The integration with the LLM API is aimed at enhancing the user experience by providing hints when needed, making the game more interactive and user-friendly.
-
Portability: Docker containers ensure the application runs consistently across different systems.
-
Scalability: Docker Compose or Docker Swarm can be used to scale the containers as needed for increased load.
-
Efficiency: Docker reduces overhead compared to traditional virtual machines, providing faster startup times and resource-efficient execution.
-
Enhanced User Support: The LLM API assists users by generating dynamic hints when they need help selecting the correct answer.
-
Web Server/Application (.jar file): This is the core application packaged into a Docker container that runs on any Docker-supported platform.
-
External APIs (e.g., Wikidata API): The application retrieves dynamic content for the game from external APIs over the network.
-
LLM API: The application communicates with an external LLM API, sending text-based queries to generate hints when users request help with answering a question.
-
Grafana: A tool for monitoring the application’s health and performance, visualizing metrics.
-
Prometheus: Used to collect performance and health metrics from the application and infrastructure, which are then visualized in Grafana.
7.2. Infrastructure Level 2
At this level, we describe the configuration of the Docker containers that encapsulate the application and its dependencies.
7.2.1. Docker Container
The application runs within a Docker container that uses a Java base image, with the Spring Boot .jar file layered on top. Additionally, the infrastructure includes:
-
MySQL Server: The official MySQL Docker image is used to run the database, which stores game-related data, such as user scores and questions.
-
Prometheus and Grafana: These monitoring tools are contained in separate Docker containers. Prometheus collects metrics from the application, while Grafana visualizes those metrics in real time.
-
LLM Integration: The game communicates with an external LLM API for processing user queries and generating hints when struggling to select the correct answer. This API is accessible over the network, and the application sends requests to it for content generation based on user inputs (user questions).
This Docker-based setup encapsulates the entire runtime environment, minimizing the need for complex configuration and external dependencies.
7.3. GitHub Deployment Workflows
To ensure a smooth development cycle and keep the team informed of project progress, we utilize GitHub for continuous integration and deployment. The following GitHub Actions workflows are configured to automate various stages of the project lifecycle:
-
Application Tests: Runs automated tests to verify that the application behaves as expected, ensuring no regressions are introduced.
-
Dependabot Updates: Automatically checks for and proposes updates to project dependencies, keeping the application up to date with the latest stable versions.
-
Deploy on Release: Automatically deploys the application to production whenever a new release is created. This ensures that the production environment is always running the latest stable version.
-
Deploy Pages: Deploys the project’s front-end (such as documentation or static assets) to GitHub Pages, ensuring that the team has easy access to the latest information.
-
pages-build-deployment: Used to trigger the deployment of the static content built by GitHub Pages, ensuring that the content is always up to date and available to the team.
These workflows help maintain the project’s quality, ensure that the team remains up to date, and automate routine tasks, allowing the team to focus more on development and less on manual processes.
This diagram illustrates the structure of the application’s Docker containers. The Java Spring Boot application, with its embedded web server, interacts with the MySQL database for persistent data and external APIs, such as the Wikidata API, for dynamic game content.
The application also communicates with an external LLM API to process text queries for hint generation during gameplay. The system’s performance is monitored by Prometheus, with the collected metrics being visualized in Grafana.
By using Docker to encapsulate all services, the deployment remains consistent, portable, and scalable across various platforms.
8. Cross-cutting Concepts
8.1. Domain Concepts
-
User: Handles registration, authentication, and game history tracking
-
Question: Image-based multiple-choice items generated from Wikidata
-
GameSession: Timed quiz session with score tracking
-
LeaderboardEntry: Aggregates user performance metrics
-
Question generation pipeline (Wikidata integration)
-
Real-time answer validation
-
Score calculation (accuracy + speed)
-
Hint generation via LLM API integration
8.2. User Experience (UX) Concepts
-
Responsive design using Bootstrap grid system
-
Progressive disclosure of complex features
-
Immediate visual feedback for user actions
-
Consistent cross-device experience
8.2.1. Internationalization & Accessibility
-
Multi-language support (EN/ES/DE/FR) with resource bundles
-
Screen reader compatibility
-
Color contrast compliance (WCAG 2.1)
-
Keyboard navigation support
8.3. Security Concepts
-
JWT-based stateless authentication
-
Spring Security role management (ROLE_USER, ROLE_ADMIN)
-
Bcrypt password hashing (work factor 12)
-
TLS 1.3 for data in transit
-
Secure HTTP headers (CSP, HSTS)
-
Rate limiting (Bucket4j integration)
-
Input validation (Spring Validation)
-
OWASP Top 10 protections
8.4. Architectural Concepts
-
MVC pattern implementation
-
Three-layer architecture:
-
Presentation Layer (Thymeleaf + Bootstrap)
-
Service Layer (business logic)
-
Repository Layer (Spring Data JPA)
-
-
RESTful APIs for internal communication
-
Async communication for hint generation
-
Circuit breakers for external API calls
8.5. Development Concepts
-
Unit testing (JUnit 5, Mockito)
-
E2E testing (Selenium, Cucumber)
-
Load testing (Gatling)
-
GitHub Actions workflow:
-
SonarQube quality gate
-
Docker image build/push
-
8.6. Operational Concepts
-
Prometheus metrics exporter
-
Grafana dashboard:
-
Key metrics: response times, error rates, system load
-
Custom game metrics: questions served, active sessions
-
-
Docker compose orchestration
-
Testing/production deployments
-
MySQL 8 without backups or data integrity between active server sessions.
-
SpringBoot AutoConfiguration
-
Security-first design
-
Maintainable codebase through SOLID principles
-
Scalable infrastructure via containerization
-
Engaging UX through performance optimization
9. Architecture Decisions
This section records the key architectural decisions made during the development of the project, ranked by importance. Each decision includes justifications, impacts and evaluated alternatives.
9.1. Decision Table - Index
| ID | Issue | Importance |
|---|---|---|
Inheriting the Project from Last Year |
Very High |
|
Data Base Management System to use |
Medium |
|
LLM for hint generation |
Medium |
|
Note
|
Although these are the architectural decisions directly made by our team, we have reviewed and agreed to inherit all architectural decisions taken by the original project team. These inherited decisions are documented here. |
10. Quality Requirements
10.1. Quality Tree
| Quality Requirement | Description |
|---|---|
The system should ensure fast user access, smooth navigation, quick game interactions, optimized image loading, and efficient generation of questions, LLM responses, and API data to provide a seamless experience. |
|
The application should be intuitive and accessible to a broad audience, supporting seamless navigation and interaction. |
|
The system must allow easy extension and modification to accommodate new features and improvements. |
|
The system should maintain at least 95% uptime, ensuring users can access the application reliably. |
|
The system should minimize errors or failures and provide consistent and accurate results to users. |
|
The application should support multiple languages and cultural adaptations for a global audience. |
|
The system should be capable of handling increasing loads efficiently. |
|
The system should support automated testing to facilitate quality assurance and reduce errors. |
|
The application should include monitoring and logging mechanisms to track performance and troubleshoot issues. |
|
The system ensures that only registered users can access their data. API keys are private and user-specific. Personal data is protected, ensuring only authorized users can view their private information. |
10.1.1. Usage Scenarios
| Scenario Category | Scenario | System Response |
|---|---|---|
The user selects a game mode from the main page. |
The system retrieves and presents the relevant questions and answers efficiently. |
|
A new user starts using the application. |
Due to the intuitive design, they quickly understand how to register and navigate. |
|
Users attempt to access the system during peak hours. |
The system remains accessible with minimal latency. |
|
The system processes a high volume of requests simultaneously. |
The application maintains stability and processes requests accurately. |
|
A server fails during operation. |
The system automatically redirects traffic and continues operation with minimal impact. |
|
A user selects a different language preference. |
The interface updates accordingly, including translated content and localized settings. |
|
A user logs in to the system. |
The system ensures the user is authenticated before granting access to private data and API keys. |
10.1.2. Change Scenarios
| Scenario Category | Scenario | System Response |
|---|---|---|
Developers add a new game mode. |
Existing game modes remain unaffected, and the new mode integrates seamlessly. |
|
Developers implement automated tests. |
The system supports comprehensive unit and integration testing. |
|
System logs errors and performance metrics. |
Logs provide real-time monitoring and facilitate troubleshooting. |
11. Risks and Technical Debts
The risks and technical debts section outlines the potential challenges and issues that could affect the successful completion, timeline, and long-term viability of the project. These risks and debts must be carefully managed to ensure smooth development and delivery.
11.1. Technical Risks
A technical risk is a potential event that could threaten the success of the project, delay timelines, increase costs, or even lead to failure if not properly managed. Below are the identified internal and external technical risks:
11.1.1. Internal Risks
| Description | Priority | Considerations |
|---|---|---|
Poor knowledge of core technologies |
High |
The team may struggle with unfamiliar tools, delaying development. To mitigate, consider training sessions. |
Incomplete system planning |
Medium |
Lack of detailed planning can lead to inefficiencies. A clear infrastructure plan is crucial from the start. |
Uneven workload distribution |
Medium |
Poor task management could lead to delays and inefficiency. Regular monitoring and clear task assignment are key. |
Lack of experience with internationalization |
Low |
Without internationalization, the system may limit its global audience. Plan for future multilingual support. |
Spring Boot unfamiliarity |
High |
The architecture will use Spring Boot, a framework unfamiliar to some team members, potentially delaying development. |
Wikidata integration |
Medium |
The project will use Wikidata as a data source, which is new to the team, requiring time to learn and implement. |
IDE configuration |
Medium |
Compatibility issues across IDE versions, extensions, and preferences may lead to development delays. |
Docker familiarity |
High |
The team may not be fully familiar with Docker, leading to delays in deployment and environment setup. |
11.1.2. External Risks
| Description | Priority | Considerations |
|---|---|---|
Third-party API failure (Wikidata) |
High |
Dependency on external APIs (e.g., Wikidata) could introduce service disruptions. Plan for fallbacks and caching. |
Third-party API failure (LLM) |
High |
Dependency on the LLM API for dynamic responses could lead to downtime. Ensure proper error handling and retries. |
11.2. Technical Debts
Technical debt refers to suboptimal development practices or decisions that could slow down future work or introduce issues later. Below are identified technical debts:
| Description | Priority | Considerations |
|---|---|---|
Lack of scalability |
High |
The current architecture may not support future growth. Implement load balancing and auto-scaling to ensure performance under increased load. |
Code quality issues |
Medium |
The codebase may contain duplication or poor documentation. Regular code reviews and refactoring are necessary to maintain quality. |
Incomplete internationalization |
Low |
Currently, the application is available in Spanish, English, German, and French. However, the full internationalization for all supported languages may not be completed in time. |
Database selection |
Low |
The choice of database is not based on familiarity but on suitability for the project. This may introduce challenges during implementation. |
Documentation in parallel |
Medium |
Documentation will be created alongside development, which may cause delays or incomplete documentation in the final stages. |
Testing coverage |
Medium |
Testing will cover most of the code, but some parts may not be fully covered due to not being essential for the current coverage objectives, as full coverage is not required and a minimum of 80% has been deemed sufficient. |
Security constraints |
Low |
Standard security measures will be applied, but advanced security features may be delayed due to performance concerns and correct integration. |
12. Glossary
| Term | Definition |
|---|---|
Wikidata |
A free and open knowledge base that provides structured data to support various applications, including WIChat’s question generation. |
LLM (Large Language Model) |
An advanced AI model capable of understanding and generating human-like text, used in WIChat to provide interactive hints. |
API (Application Programming Interface) |
A set of protocols and tools that allow different software components to communicate, enabling external access to user and question data. |
ApiKey |
A unique identifier used to authenticate and authorize requests to an API. |
Gamification |
The integration of game-like elements, such as rewards and leaderboards, to enhance user engagement and motivation. |
Scalability |
The ability of the system to handle increased load and users without significant performance degradation. |
Observability |
The capability to monitor, log, and analyze system performance and behavior to ensure reliability and quick issue resolution. |
Technical Risk |
A potential event or issue that could threaten the successful completion of the project, delay timelines, or increase costs if not properly managed. |
Technical Debt |
Suboptimal development practices or decisions that could lead to additional work or issues in the future, such as poor code quality or incomplete features. |
Spring Boot |
A Java-based framework used for building web applications and microservices, which may introduce a learning curve for the development team. |
Docker |
A platform for developing, shipping, and running applications inside containers, enabling consistent environments across different systems. |
Internationalization |
The process of designing a system to support multiple languages and regions, enabling global accessibility. |
13. Annex I - Testing
To ensure reliable and frequent software releases, comprehensive testing is essential. Robust test coverage enables safe code refactoring, instills confidence in deployments, and maintains high standards of software quality.
13.1. Unit Test
The project utilizes JUnit 5 for isolated testing of individual application components, complemented by Spring Boot Test utilities to simulate the application’s runtime behavior. The test classes are organized in the src/test/java/com/uniovi directory, with Wichat_UnitTests.java serving as the primary test suite for the service and repository layers.
13.2. Integration testing (E2E)
Behavior-Driven Development (BDD) principles guide our integration tests through Cucumber’s Gherkin syntax, creating executable specifications in plain language. Selenium WebDriver automates browser interactions to simulate real user workflows. Feature definitions are stored in src/test/resources/features, with their implementations in src/test/java/com/uniovi/steps. The CucumberRunnerTests.java orchestrates these scenario validations.
13.3. Load test
We have implemented load tests to evaluate the performance of our website under extreme conditions. For this purpose, we utilize the Gatling application, which enables us to simulate a specified number of users making web requests simultaneously.
The load tests have been conducted with user loads of 10 and 1,000 users simultaneously, as well as ramping up to 200 users over 20 seconds and 2,000 users over 60 seconds. The following use cases were evaluated during these tests:
-
Login: Assessing the performance and response time during user authentication.
-
Show Profile: Evaluating the loading speed and responsiveness when users access their profiles.
-
Show API Key: Testing the retrieval of API keys and ensuring secure access.
-
Play an Image Game: Measuring performance while users engage with interactive content.
-
Show Global Image Ranking: Analyzing the system’s ability to display rankings under heavy load.
-
Change Language: Testing the responsiveness of the application when users switch languages.
-
Log Out: Assessing the efficiency of the logout process.
These load tests have been executed against both the locally deployed environment and the production-like environment hosted in a virtual machine on Microsoft Azure. This dual testing approach allows us to compare performance under controlled conditions and in a cloud-hosted infrastructure more similar to a real-world deployment.
By conducting these load tests, we aim to identify potential bottlenecks and ensure that our website can handle high traffic volumes effectively, providing a seamless experience for all users.
13.3.1. Login
Local deployment
Cloud deployment
13.3.2. Show Profile
Cloud deployment
13.3.3. Show API Key
Local deployment
Cloud deployment
13.3.4. Play an Image Game
Local deployment
Cloud deployment
13.3.5. Show Global Image Ranking
Cloud deployment
13.3.6. Change Language
Cloud deployment
13.3.7. Log Out
Cloud deployment
13.3.8. Conclusions
After executing the load tests, we observed that the application performs significantly better in a local environment than when deployed on the Azure virtual machine. This outcome is expected, as local deployments benefit from minimal latency and faster resource access compared to cloud environments, which introduce additional network delays and potential resource contention.
In high-load scenarios—such as tests with 1,000 or 2,000 simulated users—the response times in the cloud setup were noticeably higher, and some endpoints occasionally experienced timeouts. This highlights the limitations of the current single-server architecture when handling large-scale concurrent traffic.
A potential solution to improve scalability and performance would involve deploying multiple application servers behind a load balancer, distributing incoming user traffic more efficiently. However, such an architecture would also require a distributed MySQL setup, with techniques like replication or clustering, to avoid the database becoming a bottleneck under increased load. The coordination between multiple app servers and a distributed SQL backend introduces significant architectural complexity.
Although technically feasible, implementing a horizontally scaled architecture with both load-balanced servers and a distributed MySQL database goes far beyond the scope and budget of this course. This includes added challenges in consistency, fault tolerance, and deployment orchestration.
As an alternative, integrating a Content Delivery Network (CDN) could help reduce the load on the application by caching static assets closer to end users. While this approach is simpler than deploying a distributed system, it still introduces architectural complexity that goes beyond the intended learning scope of the project.
In conclusion, while the tests demonstrate that the application behaves correctly under load, they also highlight the performance limitations of a single-instance deployment. More advanced scaling strategies such as load balancing and distributed SQL databases could improve performance, but their implementation would require infrastructure and financial resources not available within the constraints of this assignment. We ultimately considered it more productive and cost-effective to focus on improving the deployment setup itself rather than attempting to scale the application code, given the constraints of the project.