🎤 Karaoke Server

Un backend realtime scalabile costruito con NestJS, Socket.IO, Redis e MongoDB. Progettato per gestire sessioni di karaoke collaborative, code dinamiche e interazioni realtime a bassa latenza.

🌟 Features

• Realtime State: Gestione stato sessioni e code con latenza minima via WebSocket.
• Scalabile: Architettura stateless (eccetto Redis) pronta per il scaling orizzontale.
• Resiliente: Riconnessione automatica e gestione "graceful" delle disconnessioni (host/participant).
• Persistenza: Storico sessioni e utenti salvato su MongoDB.
• Docker Ready: Setup locale immediato con Docker Compose e Dockerfile ottimizzato per produzione.

🏗️ Architettura

Il sistema si basa su 3 componenti principali:

1. NestJS Server: Gestisce la logica di business e le connessioni WebSocket.
2. Redis: Memoria volatile per lo stato realtime (chiavi sessione, code, lock distribuiti).
3. MongoDB: Database persistente per storage a lungo termine (analitiche, storico).

🚀 Setup Locale

Prerequisiti

• Docker & Docker Compose
• Node.js 20+ (opzionale, per sviluppo locale senza container)

Avvio Veloce

1. Clona il repository

   git clone <repo-url>
   cd karaoke-server

2. Configura l'ambiente

   cp .env.example .env

3. Avvia con Docker

   docker-compose up --build

Il server sarà accessibile su http://localhost:3000. Socket.IO ascolta sul namespace /karaoke.

Sviluppo

Per sviluppare localmente senza containerizzare l'app Node:

1. Avvia solo i servizi di infrastruttura:

   docker-compose up -d mongodb redis redis-commander

2. Installa dipendenze e avvia server:

   npm install
   npm run start:dev

Redis Commander è disponibile su http://localhost:8081 per ispezionare lo stato Redis.

📦 Deployment Strategy

Il server è stateless e può essere deployato facilmente su piattaforme che supportano container.

Piattaforma Consigliata: Railway / Fly.io

Si consiglia l'uso di Railway per la sua semplicità nella gestione di volumi persistenti e servizi collegati.

1. Servizi Necessari:

   • 1x Node.js Service (dal Dockerfile).
   • 1x Redis Service.
   • 1x MongoDB Service.

2. Variabili d'ambiente (Produzione):

   • NODE_ENV=production
   • MONGO_URI: Stringa di connessione completa.
   • REDIS_HOST, REDIS_PORT, REDIS_PASSWORD.
   • ALLOWED_ORIGINS: Dominio del frontend (es. https://my-karaoke-app.com).
   • SOCKET_CORS_ORIGIN: Come sopra.

Sticky Sessions

L'architettura attuale NON richiede sticky sessions se si usa il transport websocket (default consigliato per i client moderni). Se si necessita di fallback a polling long-running, configurare il load balancer per sticky sessions basate su IP o cookie.

⚠️ Limiti Noti

• Persistenza Coda: La coda corrente risiede in Redis. Se Redis perde i dati (non persistente), la sessione attiva viene resettata (ma non persa in MongoDB se già salvata). Assicurarsi di usare Redis con AOF/RDB in produzione.
• Scaling: Per scalare oltre 1 istanza server, è necessario un Adapter Redis per Socket.IO (già predisposto ma da configurare se si usa cluster mode).

🤝 Contribuire

1. Fork del repository
2. Crea un branch (git checkout -b feature/amazing-feature)
3. Commit (git commit -m 'feat: Add amazing feature')
4. Push (git push origin feature/amazing-feature)
5. Apri una Pull Request