BoardHub

Connected D&D Board Platform

BoardHub è una piattaforma distribuita per sessioni di Dungeons & Dragons giocate su una plancia fisica connessa o simulata.

Il progetto collega un tavolo di gioco a componenti software di rete: una plancia o un simulatore genera eventi, un nodo edge li raccoglie, MQTT li trasporta verso il backend, PostgreSQL conserva lo storico e le API REST rendono i dati disponibili ad applicazioni client.

plancia fisica / simulatore
-> nodo edge
-> broker MQTT
-> event-service Java/Spring Boot
-> PostgreSQL
-> API REST
-> app mobile / dashboard

I dettagli di dominio, regole operative, dadi, movimento su griglia, ruolo del Dungeon Master e algoritmi previsti sono descritti in PROJECT_SCOPE.md.

Stato attuale

Area	Stato
Infrastruttura Docker	Implementata con Mosquitto MQTT e PostgreSQL.
Contratti REST/MQTT	Definiti in docs/CONTRATTI_DI_COMUNICAZIONE.md.
Simulatore Python	Implementato per pubblicare una mini-sessione D&D su MQTT.
Subscriber Python	Implementato per leggere gli eventi MQTT in forma comprensibile.
event-service	Implementato come microservizio Spring Boot che riceve eventi MQTT.
Persistenza eventi	Implementata su PostgreSQL tramite repository JDBC.
API REST eventi	Implementata con GET /api/v1/sessions/{sessionId}/events.
OpenAPI	Specifica iniziale disponibile in docs/openapi/event-service.openapi.yml.
Modello griglia	Implementato per posizioni, celle, terreno e richieste di movimento.
Algoritmo movimento	Implementato con Dijkstra semplificato.
API celle raggiungibili	Implementata con POST /api/v1/movement/reachable-cells.
App mobile / dashboard	Da implementare.

Struttura del repository

Percorso	Contenuto
docker/	Configurazione locale di Mosquitto e PostgreSQL.
docs/	Changelog pubblico, contratti di comunicazione e specifica OpenAPI.
services/event-service/	Microservizio Java/Spring Boot per ricezione, salvataggio e lettura degli eventi.
frontend/	Dashboard web per monitorare eventi e stato minimo di una sessione.
simulator/	Script Python per pubblicare e leggere eventi MQTT dimostrativi.

Avvio rapido

Avviare Mosquitto e PostgreSQL:

docker compose -f docker/docker-compose.yml up -d

Controllare lo stato dei container:

docker compose -f docker/docker-compose.yml ps

Avviare il backend:

cd services/event-service
mvn spring-boot:run

Verificare lo stato del servizio:

curl http://localhost:8082/actuator/health

In un altro terminale, pubblicare una mini-sessione D&D:

cd simulator
source .venv/bin/activate
python publish_event.py

Leggere gli eventi salvati:

curl http://localhost:8082/api/v1/sessions/session-20260630-001/events

Avviare la dashboard:

cd frontend
npm install
npm run dev

Aprire http://localhost:5173 e usare session-20260630-001 per leggere gli eventi della mini-sessione pubblicata dal simulatore.

Calcolare le celle raggiungibili:

curl -X POST http://localhost:8082/api/v1/movement/reachable-cells \
  -H "Content-Type: application/json" \
  -d '{"characterId":"adv-01","start":"A1","movementPoints":2,"grid":{"width":3,"height":3,"traps":[{"trapId":"trap-01","cell":"B1","visibility":"HIDDEN","armed":true}]}}'

Eseguire i test automatici:

cd services/event-service
mvn test

Documentazione

• Project Scope
• Contratti di comunicazione
• Specifica OpenAPI event-service
• Changelog

Note operative

Se il volume Docker di PostgreSQL esisteva già prima dell'aggiunta della tabella game_schema.game_events, lo script docker/postgres/init.sql potrebbe non essere rieseguito automaticamente. In quel caso occorre ricreare il volume o applicare manualmente lo schema aggiornato.