PaleoTwin - Sistema Museale Digitale Integrato

Sistema completo per la gestione e fruizione di contenuti museali digitali con supporto multi-dispositivo, realtà aumentata e interazione vocale.

📋 Indice

• Panoramica
• Architettura
• Funzionalità Principali
• Tecnologie
• Requisiti
• Installazione
• Configurazione
• Licenza

---

🎯 Panoramica

PaleoTwin è una piattaforma completa per musei che integra:

• Backend API RESTful - Gestione dati, autenticazione, analytics
• Backoffice Web - CMS per curatori museali
• Kiosk Multimediali - Postazioni interattive touchscreen dual-screen con avatar parlanti
• Viewer Web/Mobile/Tablet - Fruizione contenuti in mobilità
• Viewer AR - Visualizzazione modelli 3D in realtà aumentata
• Sistema Analytics - Tracciamento utilizzo e statistiche

Casi d'Uso

• Musei di Storia Naturale
• Esposizioni Paleontologiche
• Mostre Temporanee e Permanenti
• Percorsi Didattici Interattivi
• Esperienze Immersive AR/VR

---

🏗️ Architettura

Stack Tecnologico

┌─────────────────────────────────────────────────────┐
│                  Frontend Layer                      │
├──────────────┬──────────────┬──────────────────────┤
│ Backoffice   │ Kiosk NW.js  │ Mobile/AR Viewer     │
│ (EJS/jQuery) │ (Backbone.js)│ (React Native)       │
└──────────────┴──────────────┴──────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────┐
│              API Gateway (Express.js)                │
├─────────────────────────────────────────────────────┤
│ • REST API         • Authentication (JWT)           │
│ • File Upload      • Real-time (Socket.io)          │
│ • Rate Limiting    • CORS Management                │
└─────────────────────────────────────────────────────┘
                        ↓
┌──────────────┬──────────────┬──────────────────────┐
│  MongoDB     │   MySQL      │   Redis              │
│  (Analytics, │   (Tessere,  │   (Cache, Sessions)  │
│   Logs)      │   Viaggio)   │                      │
└──────────────┴──────────────┴──────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────┐
│              File Storage / CDN                      │
│  • Immagini (JPG, PNG, WEBP)                        │
│  • Modelli 3D (GLB, GLTF, OBJ)                      │
│  • Video (WEBM, MP4)                                │
└─────────────────────────────────────────────────────┘

Componenti Principali

Backend (Node.js/Express)

• Controllers: Business logic (auth, CRUD, analytics)
• Models: Mongoose schemas + MySQL ORM
• Routes: API endpoints con middleware
• Services: Email, logging, file processing
• Middleware: Auth JWT, CORS

Kiosk Application (NW.js)

• Applicazione desktop dual-screen
• Avatar parlanti con riconoscimento vocale
• Sistema di dialogo interattivo
• Applicazione per video immersivi
• Applicazione per visualizzazione schede interattive
• Slideshow e gallerie immagini
• Integrazione Socket.io per real-time

Backoffice

• CMS per gestione contenuti
• Upload file e immagini
• Gestione mostre ed exhibit
• Analytics dashboard

---

✨ Funzionalità Principali

🔐 Autenticazione e Autorizzazione

• Login JWT con refresh token
• Ruoli: Admin, Curatore
• Password recovery via email
• Session tracking e audit log

📦 Gestione Contenuti

• Oggetti Digitali: Catalogazione reperti con metadata
• Mostre: Gestione mostre temporanee/permanenti
• Exhibit: Configurazione display multi-layout
• Testi Narrativi: Multi-lingua (ITA, ENG) e multi-audience (standard, bambino)
• Classificazione Scientifica: Tassonomia Linneana
• Contesto Geologico: Datazione e provenienza

🎮 Giochi Interattivi

• Memory Game
• Puzzle Game
• Quiz Multi-risposta
• Aptic game
• Scratch Game
• Ordering

📊 Analytics Avanzate

• Tracking eventi utente (click, view, interaction)
• Heatmap oraria utilizzo
• User journey attraverso exhibit
• Statistiche per device e mostra
• Dashboard aggregazione dati

🖼️ Gestione Media

• Upload immagini (drag & drop)
• Processing modelli 3D (GLB, GLTF)
• Ottimizzazione automatica
• Generazione QR Code per exhibit
• HDR environment maps

📱 Multi-Device Support

• Kiosk: Touchscreen dual-screen, avatar parlanti
• Mobile: Viewer responsive
• Tablet: Interfaccia ottimizzata
• AR: Realtà aumentata con marker
• Web: Viewer responsive

---

🛠️ Tecnologie

Backend

• Runtime: Node.js
• Framework: Express.js 4.x
• Database: MongoDB
• Cache: Redis 6.x
• ODM/ORM: Mongoose, mysql2
• Auth: JWT (jsonwebtoken), bcryptjs
• Email: Nodemailer
• File Upload: Multer
• WebSocket: Socket.io
• Logging: Winston

Frontend Backoffice

• JavaScript: jQuery 3.7.1
• UI Framework: Bootstrap 5
• Date Picker: Moment.js, DateTimePicker

Kiosk Application

• Framework: NW.js (Chromium + Node.js)
• UI Library: jQuery
• Slideshow: Swiper.js
• Voice: RecordRTC, Web Speech API
• Icons: Now-UI Kit

AR

• AR.js / 8th Wall

---

📋 Requisiti

Sviluppo

• Node.js >= 16.0.0
• npm >= 8.0.0
• MongoDB >= 5.0

Produzione

• Server Linux (Ubuntu 20.04+ raccomandato)
• Nginx (reverse proxy)
• PM2 (process manager)
• SSL Certificate (Let's Encrypt)
• 8GB RAM minimo
• 50GB storage (+ media storage)

Kiosk Hardware

• PC Windows 10+ / Linux
• Dual monitor setup
• Touchscreen
• Microfono
• 8GB RAM
• SSD 256GB

---

🚀 Installazione

1. Clone Repository

git clone https://github.com/your-org/paleotwin.git
cd paleotwin

2. Install Dependencies

# web_viewer
cd web_viewer
npm install

# Backoffice
cd ../backoffice
npm install

# Kiosk
cd ../app_kiosk
npm install

# Video
cd ../app_video
npm install

# Avatar
cd ../applicazione-client-avatar
npm install

# Games
cd ../app_games
npm install

3. Database Setup

MongoDB:

mongosh
use paleotwin
db.createUser({
  user: "paleotwin",
  pwd: "secure_password",
  roles: ["readWrite"]
})

4. Environment Configuration

backend/.env:

NODE_ENV=development
PORT=3000

# MongoDB
MONGODB_URI=mongodb://paleotwin:password@localhost:27017/paleotwin

# JWT
JWT_SECRET=your-super-secret-jwt-key-change-in-production
JWT_EXPIRES_IN=8h

# Email (SMTP)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=noreply@museo.it
SMTP_PASS=app-specific-password
SMTP_FROM=noreply@museo.it

# Frontend URLs
FRONTEND_URL=https://admin.museo.it

# Storage
IMAGE_PATH=/var/www/paleotwin/uploads

# Viewer URLs
VIEWER_URL=https://viewer.museo.it/?
VIEWER_AR_URL=https://ar.museo.it/?

# Redis (optional)
REDIS_URL=redis://localhost:6379

# App
APP_NAME=PaleoTwin

5. Run Migrations

cd backend
npm run migrate

6. Seed Database (optional)

npm run seed

7. Start Development

# Backoffice (separate terminal)
cd backoffice
npm run dev

---

⚙️ Configurazione

Seguire le indicazioni presenti nei file di configurazione della cartella Documentazione

---

📝 Licenza

AGPLv3 (dettagli https://www.gnu.org/licenses/agpl-3.0.html)

---

👥 Team

• UniBo (soggetto Attuatore)
• Mediasfot srl (https://www.mediasoftonline.com/) (soggetto beneficiario)
• Energicamente (www.enme.it) (soggetto beneficiario)

---