Videogame Library Analytics Service

This microservice is part of the Videogame Library ecosystem. Its responsibility is to consume domain events, process information, and generate analytics about user preferences (favorite genres, most used platforms, preferred release years).

🚀 Features

• Hexagonal Architecture: Decoupled and maintainable code.
• Event-Driven: Consumes FavoriteGameEvent from Kafka in real-time.
• Reactive: Uses WebClient to communicate non-blocking with the Main Backend.
• Persistence: Stores aggregated statistics in a persistent H2 database (file-based).
• REST API: Exposes endpoints for the frontend to consume analytics.
• Dockerized: Ready for container deployment.

🛠️ Technologies

• Java 25
• Spring Boot 3.x / 4.x
• Spring Kafka
• Spring Data JPA
• H2 Database (File mode)
• Docker
• Maven

⚙️ Architecture and Flow

1. Listen: The service listens to the favorite-games-topic in Kafka.
2. Enrichment: When an event is received (user marks/unmarks favorite), it queries the Main Backend (http://localhost:8080) to get game details (genres, platforms, year).
3. Processing: Calculates and updates counters in its local database.
4. Query: The Frontend queries this service's REST API to display charts and statistics.

📋 Prerequisites

• Java 25 (or compatible with the Docker image)
• Maven
• Docker (optional)
• A Kafka instance running on localhost:9092
• The Main Backend running on localhost:8080

🚀 Execution

Local (Development)

mvn spring-boot:run

The application will start on port 8081. The H2 database will be saved in ~/data/videogame-analytics.mv.db.

With Docker

1. Build the image:

   docker build -t videogame-analytics-service .

2. Run the container:

   docker run -p 8081:8081 --network host videogame-analytics-service

   (Note: --network host is used on Linux to access localhost. On Mac/Windows, additional configuration may be required to connect to Kafka on the host).

🔌 API Reference

All endpoints are prefixed with /analytics.

1. Get Analytics by Genre

Returns the user's favorite genres sorted by frequency.

• URL: GET /analytics/{userId}/genres
• Response:

  [
    {
      "id": 1,
      "userId": "uuid...",
      "genre": "RPG",
      "count": 5
    },
    {
      "id": 2,
      "userId": "uuid...",
      "genre": "Adventure",
      "count": 3
    }
  ]

2. Get Analytics by Platform

Returns the most used platforms.

• URL: GET /analytics/{userId}/platforms
• Response:

  [
    {
      "id": 1,
      "userId": "uuid...",
      "platform": "PC",
      "count": 10
    }
  ]

3. Get Analytics by Release Year

Returns the distribution of games by release year.

• URL: GET /analytics/{userId}/release-years
• Response:

  [
    {
      "id": 1,
      "userId": "uuid...",
      "releaseYear": 2023,
      "count": 8
    }
  ]

🧪 Testing

The project includes:

• Unit Tests: For business logic (AnalyticsService).
• Integration Tests: For the web layer and persistence (AnalyticsController).

Run tests:

mvn test