La sfida
Una software house partner mi ha coinvolto su un progetto ambizioso: una piattaforma di gamification culturale per musei italiani, commissionata tramite il Ministero della Cultura. L'obiettivo era rendere l'esperienza museale più coinvolgente per i visitatori attraverso missioni, giochi e contenuti interattivi accessibili da smartphone.
Le sfide tecniche erano molteplici: l'app doveva funzionare offline (i musei spesso hanno connettività scarsa), essere multi-tenant (ogni museo è un'istanza indipendente con i propri contenuti), supportare più lingue e offrire un'esperienza mobile-first fluida e performante il tutto senza richiedere l'installazione di un'app nativa.
La soluzione: una PWA mobile-first
Ho scelto di realizzare MuseumPlay come Progressive Web App. Una PWA offre il meglio dei due mondi: si usa come un sito web (nessuna installazione richiesta, accessibile da QR code all'ingresso del museo) ma funziona come un'app nativa (funzionalità offline, notifiche, installazione opzionale sulla home screen).
Architettura multi-tenant
Ogni museo ha la propria istanza di MuseumPlay con contenuti, missioni, mappe e stili personalizzati. Ho progettato un'architettura multi-tenant dove la base di codice è unica, ma la configurazione per museo è completamente indipendente. Questo significa che aggiungere un nuovo museo al sistema richiede solo configurazione, non sviluppo.
Flusso di autenticazione progressivo
Ho implementato un flusso di autenticazione a tre livelli, pensato per non creare attrito:
- Guest: il visitatore inizia a esplorare senza registrarsi
- OTP: per sbloccare funzionalità avanzate, basta un codice via SMS
- Registrazione completa: per salvare i progressi e partecipare alle classifiche
Questo approccio progressivo massimizza il coinvolgimento: il visitatore non deve compilare un form prima ancora di capire cosa offre l'app.
Sistema di missioni e gamification
Il cuore di MuseumPlay è il sistema di missioni. Ogni museo configura percorsi tematici con tappe, giochi, quiz e contenuti multimediali. Ho implementato il progress tracking completo: il visitatore vede il suo avanzamento in tempo reale, sblocca reward e può confrontarsi con gli altri visitatori.
Le mappe interattive sono costruite con Leaflet, con layer personalizzati per ogni museo. Le animazioni di feedback (completamento missione, reward sbloccato) usano Motion.dev per un'esperienza fluida e soddisfacente.
Funzionalità offline con Service Worker
Ho configurato Workbox tramite vite-plugin-pwa per gestire il caching strategico delle risorse. I contenuti del museo vengono pre-cachati quando il visitatore ha connessione, così può continuare a esplorare anche quando perde il segnale. Le interazioni (risposte ai quiz, completamento missioni) vengono salvate localmente e sincronizzate appena la connessione torna disponibile.
Stack tecnico nel dettaglio
- Vue.js 3 con Composition API e Vite per un'esperienza di sviluppo velocissima
- Pinia per lo state management (sessione utente, progressi, dati museo)
- Tailwind CSS 4 per lo styling con design token personalizzabili per museo
- vue-i18n per l'internazionalizzazione (italiano, inglese, con struttura predisposta per altre lingue)
- Zod per la validazione dei dati in ingresso fondamentale per la robustezza di un'app multi-tenant
- GitLab CI/CD su istanza self-hosted, accessibile via VPN Tailscale
Processo di sviluppo
Il progetto ha richiesto un piano di sviluppo strutturato su 144-181 giorni, con milestone ben definite. La gestione è avvenuta interamente su GitLab self-hosted del partner, con accesso tramite VPN. Ho lavorato in sprint di 2 settimane con demo al termine di ciascuno, coinvolgendo sia il partner che i referenti istituzionali.
Lezioni apprese
La lezione più grande di MuseumPlay? La multicanalità come vincolo architetturale. Progettare un sistema multi-tenant non è solo una questione di database separati è una mentalità che permea ogni decisione, dallo stile CSS al routing, dalla gestione degli asset alla configurazione del Service Worker.
Ho anche imparato l'importanza di Zod come guardia in ingresso: in un sistema dove i dati arrivano da configurazioni diverse per ogni museo, avere una validazione rigorosa ha evitato decine di bug in produzione.