Add WebSocket infrastructure for shared sessions with Azure deployment and persistence

[Copilot]

Implements complete WebSocket infrastructure to enable real-time collaboration across multiple clients with session persistence. The solution is opt-in via environment variables and falls back gracefully to localStorage when disabled.

Architecture

Server (server/)

• Node.js WebSocket server with session-based room management
• Broadcasts state changes to all clients in a session
• Session persistence with Azure Table Storage
• Configurable session expiration (default 24 hours)
• Automatic cleanup of expired sessions
• Auto-cleanup of stale connections, graceful shutdown handling
• Single required dependency: ws library (Azure SDK optional)

Client (src/)

• useWebSocket - Connection management with exponential backoff reconnection
• useSharedState - Drop-in replacement for existing useKV hook, syncs via WebSocket when connected
• sessionManager - Secure session ID generation and URL-based session sharing
• ConnectionStatus - Real-time connection status indicator with active user count

Session Persistence

Sessions are persisted to Azure Table Storage with configurable expiration:

• Durable: Session data survives server restarts
• Configurable: Set max duration via SESSION_MAX_DURATION_HOURS (default 24 hours)
• Automatic cleanup: Expired sessions cleaned up hourly
• Fallback: Memory storage for development/testing

Usage

// Replace localStorage-only state
const [teams, setTeams] = useKV("hackathon-teams", []);

// With synchronized state
const sessionId = getOrCreateSessionId();
const [teams, setTeams, syncStatus] = useSharedState("hackathon-teams", [], sessionId);

// Add connection status UI
<ConnectionStatus 
  isConnected={isConnected}
  connectionStatus={connectionStatus}
  activeClients={activeClients}
  sessionId={sessionId}
/>

Configuration

# Frontend .env
VITE_WEBSOCKET_URL=wss://your-server.azurewebsites.net
VITE_ENABLE_WEBSOCKET=true  # false to disable

# Server .env
PORT=8080
ENABLE_PERSISTENCE=true
STORAGE_TYPE=azure-table
AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;...
SESSION_MAX_DURATION_HOURS=24

Documentation

• AZURE_DEPLOYMENT.md - Azure deployment guide (recommended)
• WEBSOCKET_INVESTIGATION.md - Technical architecture and design decisions
• WEBSOCKET_SETUP.md - Deployment guide for all platforms (Azure/Railway/Render/Heroku)
• INTEGRATION_EXAMPLE.md - Code examples and migration patterns
• WEBSOCKET_SUMMARY.md - Complete feature overview

Deployment

Recommended: Azure - Both frontend and backend hosted on Azure App Service with Azure Table Storage for session persistence.

Alternative: Frontend on GitHub Pages, WebSocket server on Railway/Render/Heroku with memory-only sessions.

The app functions identically with WebSocket disabled - no breaking changes.

Original prompt

investigate required additions to allow shared sessions via websocket

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[aatmmr]

@copilot Consider:

• Both, front and backend are hosted on Azure
• Session data is persisted for a set and max duration

[Copilot]

@copilot Consider:

• Both, front and backend are hosted on Azure
• Session data is persisted for a set and max duration

Updated the implementation to support:

1. Azure hosting for both frontend and backend: Added comprehensive Azure deployment guide (AZURE_DEPLOYMENT.md) with options for Azure App Service, Static Web Apps, and Container Instances.

2. Session persistence with configurable duration:

   • Implemented Azure Table Storage integration for durable session data
   • Configurable max duration (default 24 hours) via SESSION_MAX_DURATION_HOURS
   • Automatic cleanup of expired sessions every hour
   • Fallback to memory storage for development

Server now supports:

• STORAGE_TYPE=azure-table for Azure Table Storage
• AZURE_STORAGE_CONNECTION_STRING for connection
• SESSION_MAX_DURATION_HOURS for expiration control

See commit 63cf63c for all changes.