Cards game for developers

Intro

Goal of the demonstrator

The DestinE Earth Pulse demonstrator aims to illustrate the capabilities of the DestinE Platform environment through an interactive game that combines local climate, socio-economic, and satellite information. Designed for non-expert users, the game allows players to explore data and create their own customised versions without any coding skills. By leveraging DestinE Platform services to access and process Climate Digital Twin data, Eurostat statistics, and Copernicus satellite imagery at NUTS-3 level, the demonstrator showcases how complex information can be transformed into engaging, accessible experiences. Packaged as a mobile-friendly game that can be easily shared and played, Earth Pulse serves as an entry point for new audiences, raising awareness and visibility of the Destination Earth initiative beyond its traditional user community.

Game architecture

Components overview

  • Frontend: Nuxt 3 web application, user interface, game client.

  • Dashboard: Vite web application, game stats monitoring.

  • Backend: FastAPI server, database, game logic, API endpoints.

  • Database: PostgreSQL, stores game data, city stats, and indicators.

Structure overview

cards-game/
├── apiserver/           # Backend API and logic
├── frontend/            # Frontend UI, the "Game App"
├── frontend-dashboard/  # Frontend dashboard app
├── .gitlab-ci.yml       # GitLab CI configuration
├── docker-compose.yml   # Sets up the database using Docker container

Prerequisites

Installed tools

  • Docker (for containerized setup)

  • Python 3.9+ (for backend)

  • Node.js 18+ (for frontend)

  • PostgreSQL (for database)

  • See .env.template and .env.example for environment variables

Accounts

  • DestinE platform: An account on the DestinE platform is necessary, which is authorized to access the Climate Digital Twin data.

  • OpenStreetMap: To make requests via OverPass API & Nominatim API, it is not necessary to create an account.

Installation & Run

Local deployment (development)

ℹ️ You need to ensure a connection to the database

cd frontend
npm install
npm run dev
# Visit http://localhost:3000

cd apiserver
pip install -r requirements.txt
uvicorn main:app --host localhost --reload --port 8000
# API available at http://localhost:8000
# Swagger available at http://localhost:8000/docs

cd frontend-dashboard
npm install
npm run dev
# Visit http://localhost:5173

Development

Environment

Game app

  • Located in the frontend/ directory.

  • Built with Nuxt 3, Vue 3, Tailwind CSS, PrimeVue, TypeScript.

Server

  • Located in the apiserver/ directory.

  • Built with FastAPI, SQLAlchemy/SQLModel, asyncpg, Boto3 (S3 integration).

Dashboard

  • Located in the frontend-dashboard/ directory.

  • Template for a dashboard application, built with Vite, Vue 3, and Tailwind CSS.

Game app code structure

  • components/: Vue components (UI, cards, modals, etc.)

  • pages/: Nuxt pages (routes)

  • composables/: Reusable logic (websocket game logic)

  • assets/: Static assets (images, styles)

  • public/: Static assets (images, video, favicon, etc.)

  • const/: Constants and configuration

  • api/: API client logic

  • types/: TypeScript interfaces

  • store/: Pinia store for state management

Cards creation

  • Card data is generated from open datasets (see frontend/pages/data-information.vue).

  • Each card represents a location, enriched with climate indicators and demographic data.

Bounding Box Calculation

  • We use OpenStreetMap’s Nominatim/Overpass APIs (via our bbox.py service) to determine each city’s administrative boundary.

  • Process:

    1. Query Nominatim by city name (and optionally country) to get a place ID or polygon geometry.

    2. If needed, fetch the full boundary via Overpass with that place ID.

    3. Compute the axis-aligned bounding box: .. code-block:: python

      lats = [pt[1] for pt in polygon_coords] lons = [pt[0] for pt in polygon_coords] lat_min, lat_max = min(lats), max(lats) lon_min, lon_max = min(lons), max(lons)

      Note: The bbox is only used for creating the satellite image.

Indicators Calculation

  • Population and area figures are retrieved from OpenStreetMap via the osm-cities dataset.

  • These indicators are retrieved via CacheB service in DestinE plateform, they are computed from DestinE datasets via xarray/zarr. Unless noted, values are computed for year 2039.

  • Tropical Nights (count)

    • Formula: days where (daily min > 20)

    • Unit: count

    • Mapping: IndicatorTypeEnum.TROPICAL_NIGHT

  • Mean Temperature (°C)

    • Formula: annual mean of t2m (Kelvin) converted to Celsius.

    • Unit: °C

    • Mapping: IndicatorTypeEnum.MEAN_TEMP

  • Total Precipitation (mm)

    • Formula: sum of tp over the period; meters → millimeters (× 1000).

    • Unit: mm

    • Mapping: IndicatorTypeEnum.PRECIPITATION

  • Cloud Cover (%)

    • Formula: mean of tcc over the period; fraction → percent (× 100).

    • Unit: %

    • Mapping: IndicatorTypeEnum.CLOUD_COVER

  • Wind Speed (km/h)

    • Formula: sqrt(mean(u10)^2 + mean(v10)^2) then m/s → km/h (× 3.6).

    • Unit: km/h

    • Mapping: IndicatorTypeEnum.WIND_SPEED

  • Total Snowfall (cm)

    • Formula: sum of sf over the period; meters → centimeters (× 100).

    • Unit: cm

    • Mapping: IndicatorTypeEnum.SNOWFALL

  • Dry days (days)

    • Formula: count of days where daily max of tp equals 0.

    • Unit: days

    • Mapping: IndicatorTypeEnum.DAYS_WITHOUT_RAIN

  • Rainy days (days)

    • Formula: count of days where daily sum tp × 1000 > 1 mm

    • Unit: days

    • Mapping: IndicatorTypeEnum.DAYS_WITH_RAIN

  • Sunny days (days)

    • Formula: days where (daily max tp == 0) AND (daily mean tcc × 100 < 20%).

    • Unit: days

    • Mapping: IndicatorTypeEnum.SUNNY_DAYS

  • Snowy days (days)

    • Formula: days where daily min of sf > 0.

    • Unit: days

    • Mapping: IndicatorTypeEnum.SNOWY_DAYS

  • Stormy days (days)

    • Formula: days where (daily mean wind magnitude^2 > 10) AND (daily sum tp × 1000 > 5 mm).

    • Unit: days

    • Mapping: IndicatorTypeEnum.STORMY_DAYS

  • Heatwaves (count)

    • Formula: number of heatwave events where (daily min t2m ≥ 20°C) AND (daily max t2m ≥ 35°C) for ≥ 3 consecutive days.

    • Unit: count

    • Mapping: IndicatorTypeEnum.HEATWAVES

  • Heavy precipitation days (days)

    • Formula: number of Heavy precipitation where (daily min tp ≥ 20mm)

    • Unit: days

    • Mapping: IndicatorTypeEnum.HEAVY_PRECIP_DAYS

  • Frost days (days)

    • Formula: number of Frost days where (daily min t2m < 0°C)

    • Unit: days

    • Mapping: IndicatorTypeEnum.FROST_DAYS

  • July 2039 temperature (°C)

    • Formula: mean of t2m (Kelvin) converted to Celsius in July 2039.

    • Unit: °C

    • Mapping: IndicatorTypeEnum.MEAN_TEMP_JULY

Notes

  • All computations are idempotent at the value level: existing non‑null values are not recomputed during personalized harvest unless missing.

  • OSM population is intentionally excluded from default gameplay indicators (see “Hide population”).

Workflow

  1. Open the full-year 2039 Zarr with xarray + dask (chunked by time).

  2. Subset by each city’s position (lat, lon).

  3. Compute annually:

    • Tropical Nights: count of days where the nightly minimum temperature > 20 °C (293.15 K)

    • Total Precipitation: sum of tp (in m, converted to mm)

    • Mean Temperature: annual mean of t2m (in K, converted to °C)

  4. Return the results as simple integers/floats for the game logic.

Optimization

CacheB handles global data aggregation and caching, so no local downloads or heavy processing are required.

Satellite images sources

Card creation by players

Players can create a new city card from the UI (Create Card screen). This triggers a protected backend endpoint that validates the requested OpenStreetMap place, creates the card row and indicator placeholders, starts an asynchronous climate‑indicator harvest, generates a satellite photo, and immediately returns a preliminary card payload.

  • Endpoint: POST /cards

Request body

  • osmid (string, required): OpenStreetMap ID of the place

  • osm_type (string, required): One of R (relation), W (way), N (node)

  • name (string, optional): City name hint; enables province‑aware flow when paired with countrycode

  • countrycode (string, optional): ISO 3166‑1 alpha‑2 code used with name to locate the province via GISCO

  • latitude (number, optional) and longitude (number, optional): Geographic center used for satellite image generation and, when province mode is enabled, for province lookup

Notes

  • If osm_type is not one of R | W | N, the request is rejected (400).

Workflow (backend)

  1. Auth & validation: Token is validated; osmid and osm_type are required; osm_type must be R|W|N.

  2. De‑duplication: If a card with the same place_id (osm_type + osmid) already exists, a 400 error is returned.

  3. OSM fetch: City metadata and bounding box are fetched from OpenStreetMap (OSMService).

  4. Province mode (optional): If both name and countrycode are provided, the province is resolved via GISCO. If another card already exists in that province, its stored values can be reused to speed up initialization.

  5. Persistence: A new Card row is created. Indicator rows are created for the supported types; population is skipped in province mode.

  6. Image: A satellite image is generated via Copernicus WMS (download_wms) using the provided center, uploaded to S3, and a presigned URL is returned.

  7. Background task: A task is enqueued to compute the 2039 climate indicators with Dask/xarray (harvest_indicators_and_save). This can take up to ~10 minutes.

  8. Notification: When computation finishes, the card’s updated_at is set and a user notification is sent via the notifications channel.

Operational notes

  • While the background computation runs, the API returns a card with a valid image and indicator metadata; most indicator values are null until the task finishes.

  • Environment variables required: COPERNICUS_API_KEY for WMS image, DESTINE_USERNAME and DESTINE_PASSWORD for DestinE data access.

  • You can poll GET /cards?latest=true or subscribe to notifications to know when the card is fully ready.

Deck creation & usage

Backend behavior (on deck creation)

  • Name validation: must be alphanumeric, 3..100 chars. Reserved names tutorial and Default are rejected.

  • Uniqueness per owner: the same user cannot create two decks with the same name.

  • Ownership: the authenticated user is stored on the deck (owner_id, owner_name).

  • Persistence: the server inserts a Deck row with

    • name and public as provided,

    • completed = false,

    • timestamps (created_at, updated_at).

  • Initial content: no cards and no deck indicators are created at this stage; the deck is empty by design.

  • Side effects: no background computation, no notifications, no S3 operations are triggered during creation.

Operational notes

  • A deck becomes usable for games only after later updates add cards and default indicators; the deck is marked complete when it has 32 cards and ≥ 4 deck indicators.

  • Indicator values are computed asynchronously after updates (not on creation). A background job fills or updates values for the deck’s selected indicators across all its cards, and a notification is sent when finished.

  • Room creation validates deck usage: non‑tutorial games require a complete deck; private decks can only be used by their owner.

  • System decks tutorial and Default are immutable: you cannot create, rename, or delete decks with these names, and those decks cannot be modified.

Personalized indicators creation

Backend behavior (when computing personalized indicators for a deck)

  • Trigger: occurs after a deck update (PUT /decks/{id}) that changes cards, indicators, or default indicators. A background task is queued for that deck.

  • Data sources: DestinE CacheB Zarr dataset for climate variables, accessed via xarray/dask; city coordinates resolved from OSM metadata and date.

  • Selection scope: for each card in the deck and each deck indicator (by type, year, month), compute the missing value only; existing non‑null values are reused.

  • Computation pipeline: 1) Open Zarr dataset once per deck job and select relevant variables per indicator type. 2) Time slice using the indicator’s month/year or full year for annual metrics. 3) Spatial selection by nearest point at the city’s lat/lon. 4) Apply the indicator‑specific aggregation (e.g., mean temperature, total precipitation, wind speed magnitude, count thresholds like tropical nights, frost days, etc.). 5) Upsert the result into the database by creating/finding the Indicator row and creating/updating its IndicatorValue.

  • Idempotency: if an indicator already has a stored non‑null value, it is skipped; missing or null values are recalculated.

  • Performance: uses dask for lazy loading and chunked computation; reuses a single opened dataset for the full deck job.

  • Side effects:

    • Updates updated_at for the card when card‑level harvest runs; for deck jobs, checks deck completeness (32 cards and ≥ 4 indicators) and flips completed=true accordingly.

    • Sends a notification when all cards in the deck are processed; if < 32 cards, informs that the deck isn’t complete yet though values are updated.

  • Errors & resilience: any computation error for a given indicator rolls back that indicator’s transaction but continues the deck job for other indicators/cards.

Operational notes

  • Personalized indicators are not computed at deck creation time, only on deck updates that alter indicator configuration or card membership.

  • The job runs asynchronously; consumers should wait for the completion notification before sharing/playing with updated values.

  • Year and month are stored per deck indicator; when month is null, annual metrics are computed.

Notifications

Backend behavior

  • Channel: WebSocket at /notify/connect?token=<access_token>.

  • Authentication: token is decoded server‑side; if the user is unknown, it is created, and the socket is registered in an in‑memory connections map keyed by internal user.id.

  • On connect: server loads unseen notifications for the user and pushes them one‑by‑one as JSON { id, message }.

  • Produce: services call notify_user(user, message) to persist (notifications table) and, if connected, push to the user’s socket immediately.

  • Persistence: each notification row stores user_id, message, seen (0/1), and timestamps.

  • Mark as read: the client sends a JSON message on the socket { "action": "read", "id": [<id1>, <id2>, ...] }; backend sets seen=1 and updates updated_at.

When notifications are sent

  • Card creation background completes (city indicators harvested): user receives “The city card ready to played”.

  • Deck personalized indicators complete: user receives either “The deck is ready to played” (32 cards) or a partial‑update message if fewer than 32 cards.

Operational notes

  • The notification socket is separate from game WebSockets; reconnect with the same token to resume and fetch any unseen notifications.

  • Notifications are stored server‑side; on reconnect, any seen=0 entries are replayed to the client.

  • Ensure the client acknowledges reads to prevent repeated delivery on subsequent connects.

Users storage in database

Backend behavior

  • Source of truth: users are derived from the OIDC token (Keycloak). The backend does not implement password auth.

  • Persistence model: table users with

    • id (PK, autoincrement),

    • preferred_username (string, indexed),

    • sub (string, unique, indexed) — the stable subject identifier from the token.

  • Creation & lookup: whenever a feature needs a DB user (e.g., notifications), the backend resolves the current user by sub. If absent, it inserts a new row with the current preferred_username.

  • Relationships: one‑to‑many with notifications (users.id → notifications.user_id).

Operational notes

  • Username changes in the IdP: future logins keep the same sub so the same DB user is reused; preferred_username is not auto‑updated unless you add that logic.

  • No roles/permissions are stored in the users table; authorization is enforced from the JWT claims at request time.

  • If you later extend the profile (e.g., avatar, locale), add nullable columns or a separate profile table keyed by users.id.

CacheB requests/Queue

Backend behavior

  • Purpose: serialize and offload heavy DestinE CacheB requests (Zarr opens, array computations) from the request path.

  • Queue: an in‑process asyncio.Queue holds tasks; each task is (task_id, func, args, kwargs) with status tracked in tasks_status.

  • Worker: a background coroutine started at app startup continuously pulls tasks and executes them; it awaits async functions or runs sync ones in a thread pool.

  • Enqueue: producers call add_task_in_queue(func, **payload) and receive a task_id; for card creation, the system enqueues harvest_indicators_and_save(card_id, city, bbox, user).

  • Introspection: GET /tasks returns the live tasks_status map for observability.

Task lifecycle

  • pending → running → finished | failed: the worker updates tasks_status accordingly; errors are captured into the failed status string.

  • Side effects: indicator values are computed and persisted; upon completion, user notifications are sent (card ready, deck ready/partial).

Operational notes

  • This lightweight queue avoids blocking API responses; it is suitable for a single‑process deployment. For multi‑replica or long‑running workloads, consider a durable queue (Redis/Celery/RQ/Arq) and idempotent tasks.

  • Ensure tight timeouts and retries inside background functions when calling external services (CacheB, WMS, OSM). Re‑enqueue or mark failed with diagnostics on repeated errors.

NUTS‑3 regions

Backend behavior

  • Region resolution: when creating a card with both name (city) and countrycode, the backend resolves the administrative region (province‑level) using the EU GISCO service.

    • Primary method: reverse lookup with the city center (/reverse), extracting the L1 label as the province/region name.

    • Fallback: /provinces?country=<code>&city=<name> if reverse lookup fails.

  • Storage: the resolved province name is stored on the card (cards.province). No numeric NUTS code is persisted at this time.

  • Province reuse: if any card already exists with the same province, new cards for that province initialize their indicator values by reusing existing values (idempotent speed‑up). Background harvesting may still run later if needed.

  • Province bounding boxes: when province is known, the harvest area uses GISCO’s province bbox; otherwise, the area falls back to the city bbox derived from OSM.

Data & standards

  • GISCO endpoints used: /reverse, /provinces, /cities, /countries, and /bbox (service‑specific paths as implemented in GiscoService).

  • The L1 label from GISCO responses is used as a province/NUTS‑level name for storage and comparisons.

  • A reference dataset resources/nuts_3_population_2021.json is included for NUTS‑3 populations (ESTAT); it is not directly persisted but can support analytics.

Operational notes

  • Scope: GISCO NUTS coverage is Europe; non‑EU locations may skip province mode and use city‑level bbox only.

  • Disambiguation: reverse lookup uses the provided latitude/longitude to disambiguate homonymous city names.

  • Future improvements: consider persisting official NUTS codes alongside labels to avoid string comparison drift and enable robust joins with external datasets.

Population

Backend behavior

  • Card initialization response: OSM population is deliberately excluded from the returned indicator metadata. Implementation filters out IndicatorTypeEnum.POPULATION when building the initial indicators list.

  • Province cards: when a card is created in province mode, the population indicator row is not created for that card.

  • Personalized computations: population is not mapped for deck‑level personalized indicators and is never computed in the background job; deck indicator configuration must not include population.

  • Gameplay usage: population is not used for bounds computation or turn comparisons since gameplay relies on deck‑selected indicators (which should exclude population).

Operational notes

  • Keep population out of deck indicator selection. If included, the personalized harvest has no mapping for population and will not compute values for it.

  • Population may exist in the database for some cards, but it is not exposed in the initial creation response and is not used in gameplay logic.

Architecture/services — Optimization & refactoring

Backend-focused proposals to improve maintainability, performance, and reliability. The items below are actionable and scoped to existing modules.

  • Service boundaries & dependency injection

    • Split responsibilities in CardService (creation, WMS image, indicator bootstrapping) into smaller services (e.g., ImageService for WMS/S3; keep OSMService and IndicatorService dedicated).

    • Avoid opening DB sessions inside services that already operate within a session (e.g., CardService.download_wms_image calls get_db()); pass the session or isolate side effects behind a repository layer.

    • Standardize constructor injection for all external deps (S3, OSM, GISCO, Value/Indicator services) to simplify testing and mocking.

  • Transactions & database performance

    • Use a single atomic transaction per use‑case; minimize scattered flush() calls inside loops (batch inserts for indicators/values where safe).

    • Index hot paths (if not already): cards.place_id, (indicator.card_id, indicator.type_id, indicator.year, indicator.month), (deck_indicator.deck_id, indicator_type_id, year, month).

    • In DeckService._apply_cards_change, fix validation logic for unknown card IDs (raise only when missing is non‑empty) and reduce redundant queries by selecting once and building a map.

    • Prefer projection queries over loading full ORM rows when only IDs are needed; avoid N+1 where possible by eager loading.

  • Background compute & tasking

    • Create the Dask client lazily at startup and monitor health; avoid instantiating global clients at import‑time in request workers.

    • Keep heavy I/O/CPU (WMS download, Zarr reads) off the request path; for card creation, consider deferring WMS generation to background (with a temporary placeholder) to reduce tail latency.

    • Add bounded retries with backoff to external calls (Copernicus WMS, OSM/Nominatim, CacheB) and set strict timeouts.

    • Consider a dedicated task runner (RQ/Celery/Arq) for stronger reliability, visibility, and retry semantics; keep the current queue abstraction if you prefer minimal footprint.

  • Caching & reuse

    • Cache immutable reference data (indicator types list) within a request/job to avoid repeated queries.

    • Reuse a single opened Zarr dataset per deck job (already done); extend with an in‑process cache with eviction to avoid reopen on rapid successive jobs.

    • Memoize OSM lookups and bounding‑box computations for the lifetime of the job; persist short‑lived caches if rate limits are tight.

  • Model consistency & enums

    • Keep IndicatorTypeEnum and DB IndicatorType in a single source of truth; generate one from the other or validate at startup to prevent drift.

    • Centralize the mapping between IndicatorTypeEnum and IndicatorTypeForPersonnal to avoid name‑based coupling and runtime KeyErrors.

  • Observability

    • Replace print statements with structured logs; add request/task correlation IDs to tie logs across services and background jobs.

    • Emit metrics for task durations, retries, and cache hit‑rates (Prometheus counters/histograms).

  • Configuration & security

    • Move magic constants (e.g., year 2039) to typed config; make ranges selectable per deck/room when needed.

    • Centralize timeouts, retry budgets, and external URLs in config.py; validate at startup.

  • Error model & notifications

    • Prefer domain exceptions in services and translate once at router/controller boundaries; avoid raising HTTPException from deep layers.

    • Route user notifications through a small event bus (domain events) decoupled from services; keep side effects observable and testable.

Game mechanics

  • Players create or join a room and receive cards.

  • Each turn, players select a statistic to compare.

  • The player with the highest or lowest value (choice of the active player) wins the round.

  • A score is calculated for each player at each round in function of played cards.

  • The player with the highest score wins the game.

Tutorial mode

  • Purpose

    • One-turn guided match against a bot to onboard new players.

  • Frontend flow

    • Entry: on Home → New game, if localStorage['tutorial-done'] is absent, the app creates a tutorial room (POST /create_room with mode: "tutorial", max_players: 2), instantiates a local Game, opens the standard game WebSocket, then navigates to /game-board.

    • Completion: when the tutorial game ends, the client sets localStorage['tutorial-done'] = 'true', resets the store, and redirects to / with ?endedtutorial=true to display a completion popup.

    • Restart: the side menu provides “Restart tutorial” which clears the flag and starts a new tutorial session.

  • Backend behavior

    • Deck: the tutorial room uses the tutorial deck (looked up by name); users cannot rename or delete the tutorial or Default decks.

    • On first WebSocket join in tutorial mode: a bot (LuckyBot) is auto-added, turn_duration is extended (≈ 1500 s), and max_turn is set to 1.

    • Turn order: the human player always starts in tutorial mode.

    • Persistence: tutorial games do not write scores to the leaderboard.

  • Notes

    • Authentication is not required to play the tutorial; a nickname (preferred_username) is sufficient.

    • The standard game WebSocket endpoint is used for tutorial sessions as well.

Solo mode

Backend behavior

  • Room startup: when a room is created with mode="solo" and the first human joins, a non‑interactive bot (LuckyBot) is auto‑added. Turn duration is extended (~1500 s).

  • Start and turns: on start, the current player is always the first human. For each turn, 4 candidate indicators are selected from the deck. The human chooses the indicator and direction; the bot does not make choices. The bot “turn” is skipped by design; the human drives the turn flow.

  • Dealing and values: the deck is split equally among the human and the bot. The bot always holds and draws a card; its indicator values come from precomputed deck indicators. Missing values are treated as 0 for comparisons.

  • Finish conditions: the game ends at the configured max_turn or when only one player remains (e.g., the bot or the human). If the human disconnects mid‑game, the room is closed.

  • Persistence: the persisted game record carries mode='solo'. On finish, only non‑bot players have their scores recorded in the leaderboard.

Operational notes

  • Solo mode starts immediately; no waiting for a second human.

  • Scoring and indicator bounds are computed exactly like multiplayer; the difference is only that indicator selection is human‑driven and the bot is passive.

  • The bot has no WebSocket and is not persisted as a user; it serves as an in‑memory opponent using the same deck data.

WebSocket

This project uses WebSockets to enable real-time, bidirectional communication between clients and the game server. When a player connects, a persistent WebSocket connection is established, allowing instant transmission of game events and state updates.

Typical WebSocket events

Below are common events exchanged between client and server:

Event

Description

card

Sends a card to the player.

error

Notifies about an error, with a message.

info

General informational message.

game_start

Indicates the game has started, with total number of turns.

game_finish

Signals the end of the game, including the reason, winner, and leaderboard.

player_join

A player has joined the game; includes the updated player list.

player_leave

A player has left the game.

player_eliminated

Notifies that a player has been eliminated.

turn_info

Provides information about the current turn, including which player’s turn it is.

turn_result

Announces the result of a turn, including the winner and all players’ cards and scores.

game_context

Shares context about the game, such as the expected and current player.

turn_status

Gives the status of all players for the current turn (cards remaining, elimination status).

Each event typically includes a payload with relevant data (such as player ID, card details, or updated game state), allowing clients to update their UI and logic in real time.

Game progress

General

  • Game state managed on the backend.

  • Real-time updates via WebSocket.

Actions proposed

  • Create/join room

  • Play a card/statistic

  • View results and scores

Score computation

Points are awarded each turn based on the chosen indicator value relative to the deck. The calculation follows these steps:

  1. Indicator bounds
     Determine the minimum (minVal) and maximum (maxVal) values of the selected indicator across all active cards in deck.

  2. Logarithmic normalization

    Compute a raw score:

    ε = 1e-6 rel = val - minVal + ε span = maxVal - minVal + ε raw_score = math.log(rel) / math.log(span) * 100

  3. Direction adjustment

    If the direction is 1 use the raw score as is, if the direction is -1 invert the score:

    raw_score = 100 - raw_score

  4. Score adjustment

    If raw_score < 0, set raw_score = 0 and if raw_score > 100, set raw_score = 100.

Database MCD

Database

Server code structure

  • main.py: FastAPI entrypoint

  • routers/: API route definitions

  • models/: Database models

  • services/: Business logic

  • utils/: Utility functions

Server communication

Overview

Library

The backend relies on the following key Python libraries:

  • fastapi – high-performance ASGI web framework

  • uvicorn – lightning-fast ASGI server

  • pydantic – data validation and settings management

  • databases – async support for SQL databases

  • asyncpg – fast PostgreSQL client for asyncio

  • sqlalchemy – core ORM and SQL toolkit

  • sqlmodel – Pydantic + SQLAlchemy integration

  • python-jose – JSON Web Token implementation

  • websockets – WebSocket client/server library

  • requests – HTTP for humans (sync client)

  • python-dotenv – load environment variables from .env

  • psycopg2-binary – PostgreSQL driver (sync)

  • boto3 – AWS SDK for Python (S3 access)

  • python-multipart – support for form & file uploads

  • xarray – N-D labeled arrays & datasets

  • xarray[io] – I/O engines for netCDF, raster, Zarr, etc.

  • numpy – numerical computing library

  • zarr – chunked, compressed, mutable N-dim arrays

  • fsspec – Filesystem specification for local & remote

  • s3fs – S3 backend for fsspec

  • dask – parallel computing with task scheduling

  • aiohttp – async HTTP client/server framework

For adding dependencies, see requirements.txt.

Server endpoints

  • POST /create_room
     Create a new game room.
     Request body: JSON with room settings (e.g. maxPlayers, mode).
     Response: { "room_id": "...", "settings": { … } }

  • GET /rooms
     List all active game rooms with their current player counts and settings.

  • GET /playedGame
     List all played games with their results and player scores stored in the database.

  • GET /playedGame/now

    List today active games with their result and player stored in the database.

  • WebSocket /ws/{room_id}/{player}
     Real-time endpoint for game events: join notifications, turn submissions, results, game start/end.

  • GET /card/
     Retrieve metadata for all cards (including presigned image URLs).

  • GET /score/leaderboard
     Fetch the all-time high‐scores leaderboard.

  • GET /score/leaderboard/now
     Fetch today’s high‐scores leaderboard.

Development-Only Endpoints

  • GET /era5/era5 Retrieve metadata for one deck and assemble card data with climate indicators

  • POST /era5/era5
     Query climate indicators from ERA5/DEM Zarr for a given bounding box.

  • GET /s3/buckets
     Retrieve the names of all s3 buckets accessible by the application.

  • GET /s3/buckets/{bucket_name} Retrieve information about a specific S3 bucket, including its metadata and ACL.

  • GET /s3/buckets/{bucket_name}/all Retrieve a list of all object keys in the specified S3 bucket.

  • POST /s3/buckets/{bucket_name}/upload Upload a file to the specified S3 bucket.

  • GET /s3/buckets/{bucket_name}/url Generate a presigned URL to upload a file to the specified S3 bucket.

Configuration

  • Environment variables in .env (see .env.template)

  • Database and S3 credentials required

Identity & Access Management (IAM)

Modes: visitor vs identified

  • Visitor (unauthenticated)

    • Access: home, rules, data information, leaderboard, and gameplay (solo/multi) without an account.

    • No access: create/edit deck and card screens, and “My decks”.

  • Identified user (authenticated via Keycloak OIDC)

    • Additional access: create/edit cards and decks, card library, “My decks”.

    • The session exposes username, roles and sub (user identifier) to associate actions on the API side.

Authentication overview

Frontend (Nuxt 3 + Auth.js)

  • Authentication handled by @sidebase/nuxt-auth with a Keycloak (OIDC) provider.

  • Protected routes use definePageMeta({ auth: true }) (e.g., create-card, create-deck, card-library, my-decks). Gameplay, home, rules, data information, and leaderboard remain publicly accessible.

  • Token handling:

    • Retrieves access_token/refresh_token at sign-in; extracts username and roles from the JWT.

    • Silent access_token refresh via the JWT callback; auto-refresh on window focus and periodically (~60 s).

  • Main environment variables: NUXT_PUBLIC_KEYCLOAK_ISSUER, NUXT_PUBLIC_KEYCLOAK_CLIENT_ID, NUXT_KEYCLOAK_CLIENT_SECRET, NUXT_AUTH_SECRET, NUXT_AUTH_ORIGIN.

Backend (FastAPI)

  • Validates Authorization: Bearer <access_token> against the Keycloak realm public keys.

  • Protected endpoints: Depends(get_current_user) (token required). Public or visitor-tolerant endpoints: Depends(get_optional_current_user) (token optional).

  • Game WebSocket: authentication not mandatory; a nickname ( preferred_username ) is enough to play. If a token is provided, events can be linked to an identified user.

  • Main environment variables: IAM_URL, IAM_REALM, ADDR_PUBLIC_KEY (optional; otherwise JWKs are fetched automatically).

Calling protected API from the frontend

  • Include Authorization: Bearer ${session.access_token} when calling protected routes.

  • Or WebSocket: ws(s)://<API_BASE>/notify?token=<access_token>

Cloud deployment (production)

Production environment run on dedicated Kubernetes cluster. Build and deployment are performed using a Gitlab pipeline (not supplied here) however, there’s nothing to prevent manual deployment.

ℹ️ You need to ensure a functional postgre database and a kubernetes cluster

Create a kubernetes namespace to isolate the application in your cluster :

kubectl create namespace climate-cards-game

Backend (apiserver)

You can adapt the file apiserver/deploy/production.yaml to fit your deployment goal.

cd apiserver

# STEP 1: Build docker image
docker build -t apiserver:latest .

# STEP 2: Create kuberntes ressources
kubectl -n climate-cards-game create secret generic apiserver-db \
      --from-literal=DB_HOST= \
      --from-literal=DB_PORT= \
      --from-literal=DB_NAME= \
      --from-literal=DB_USER= \
      --from-literal=DB_PASSWORD= \
      --dry-run=client -o yaml | kubectl apply -f -
kubectl -n climate-cards-game create secret generic apiserver-aws \
      --from-literal=AWS_ACCESS_KEY= \
      --from-literal=AWS_SECRET_KEY= \
      --dry-run=client -o yaml | kubectl apply -f -
kubectl -n climate-cards-game create secret generic apiserver-destine \
      --from-literal=EDH_API_KEY= \
      --dry-run=client -o yaml | kubectl apply -f -
kubectl -n climate-cards-game apply -f deploy/production.yaml

Frontend

You can adapt the file frontend/deploy/production.yaml to fit your deployment goal.

cd frontend

# STEP 1: Build docker image
docker build -t frontend:latest .

# STEP 2: Create kuberntes ressources
kubectl -n climate-cards-game apply -f deploy/production.yaml

Dashboard

You can adapt the file dashboard-frontend/deploy/production.yaml to fit your deployment goal.

cd frontend-dashboard

# STEP 1: Build docker image
docker build -t dashboard:latest -f Dockerfile.prod .

# STEP 2: Create kuberntes ressources
kubectl -n climate-cards-game apply -f deploy/production.yaml

License

This game is free software, developed by ATOS for ESA DestinE. Licensed under the Apache License, Version 2.0 (see LICENSE).