llm-monitor/docs/WEB_WORKERS.md

# LLM Monitor - Architettura Web Worker

## 📊 Architettura Moderna con Web Workers

Questa versione della dashboard utilizza **Web Workers** per un'esperienza utente ottimale senza blocchi dell'UI.

## 🏗️ Componenti

### 1. **data-sync.worker.js** (Web Worker)
Thread separato che:
- Effettua le richieste HTTP all'API (`/api/v1/health`, `/api/v1/models`)
- Aggiorna **localStorage** periodicamente (ogni 30 secondi)
- Invia messaggi al main thread con i dati aggiornati
- **NON blocca mai l'interfaccia utente**

### 2. **app.js** (Main Thread)
File principale che:
- Inizializza il Web Worker
- Carica dati da **localStorage** al boot
- Riceve messaggi dal Worker e aggiorna il DOM
- Aggiorna solo gli elementi DOM che sono effettivamente cambiati
- Fornisce fallback se Web Workers non sono supportati

### 3. **index.html**
Template HTML con struttura base e caricamento di app.js

## 🔄 Flusso Dati

```
┌─────────────────────────────────────────────────────┐
│          MAIN THREAD (UI Thread)                    │
│  - Renderizza il DOM                                │
│  - Interagisce con l'utente                         │
│  - Legge da localStorage                            │
└─────────────────┬───────────────────────────────────┘
                  │
        postMessage() / onmessage
                  │
┌─────────────────▼───────────────────────────────────┐
│          WEB WORKER (Separate Thread)               │
│  - Fetch /api/v1/health                             │
│  - Fetch /api/v1/models                             │
│  - localStorage.setItem()                           │
│  - Eseguito ogni 30 secondi                         │
└─────────────────────────────────────────────────────┘
                  │
        postMessage({ DATA_UPDATED })
                  │
          ┌───────▼────────┐
          │  localStorage  │
          │  persistente   │
          └────────────────┘
```

## 💾 LocalStorage

I dati sono memorizzati **per server** con chiavi dinamiche:

- `llm_monitor_health_<serverId>` - Dati health check
- `llm_monitor_models_<serverId>` - Dati modelli disponibili
- `llm_monitor_running_<serverId>` - Modelli in esecuzione
- `llm_monitor_servers` - Lista istanze Ollama configurate
- `llm_monitor_active_server` - ID del server attivo

La funzione `getServerStorageKey(serverId, suffix)` in `server-config.js` costruisce le chiavi.

### Struttura dati health:
```json
{
  "status": "healthy",
  "ollama_status": "online",
  "timestamp": "2024-01-15T10:30:00.000Z"
}
```

### Struttura dati models:
```json
{
  "models": [
    {
      "name": "llama2",
      "digest": "abc123...",
      "size": 3825922048,
      "modified_at": "2024-01-15T10:30:00.000Z"
    }
  ],
  "total": 1,
  "totalSize": "3.56 GB",
  "showByModel": {
    "llama2": { "details": {}, "model_info": {}, "parameters": "..." }
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}
```

## 🎯 Vantaggi

### ✅ Performance
- **Main thread mai bloccato** - Le richieste HTTP avvengono nel Worker
- **DOM updates ottimizzate** - Aggiorna solo elementi cambiati
- **60 FPS garantito** - L'UI resta responsiva

### ✅ Offline Support
- I dati rimangono in **localStorage** anche se il server è offline
- La dashboard mostra l'ultimo stato noto
- Il **Service Worker** (`service-worker.js`) mette in cache l'app shell (HTML, CSS, JS) per navigazione offline
- Cache name corrente: `llm-monitor-v3`

### ✅ Efficienza di Rete
- Una sola fetch ogni 30 secondi (dal Worker)
- Compressione gzip della risposta
- Ridotto uso di bandwidth

### ✅ Scalabilità
- Più tab della dashboard non sovraccaricare il server
- LocalStorage condiviso tra tab (gli aggiornamenti si sincronizzano)

## 🔧 Configurazione

### Intervallo di aggiornamento
Modifica in `data-sync.worker.js`:
```javascript
const REFRESH_INTERVAL = 30000; // 30 secondi
```

### Disabilitare Web Worker (debug)
Nel browser console:
```javascript
window.app.worker = null;
window.app.syncDataInMainThread();
```

## 🛠️ Sviluppo

### Debug del Worker
```javascript
// In data-sync.worker.js
console.log("Worker sync triggered", new Date());
```

Console del browser (DevTools > Dedicated Worker)

### Ispezionare localStorage
```javascript
// In console del browser
JSON.parse(localStorage.getItem('llm_monitor_health'))
JSON.parse(localStorage.getItem('llm_monitor_models'))
```

## 📱 Browser Support

- ✅ Chrome/Edge 4+
- ✅ Firefox 3.6+
- ✅ Safari 4+
- ✅ Opera 10.6+
- ⚠️ Fallback disponibile se non supportati

## 🚀 Ottimizzazioni Future

- [ ] IndexedDB per dati maggiori
- [ ] Sincronizzazione tra tab (BroadcastChannel API)
- [ ] Caching intelligente con TTL
- [ ] Compressione dati (Zstandard/Brotli)

## 🔍 Troubleshooting

### Worker non carica
- Verificare CORS
- Controllare DevTools > Application > Service Workers
- Verificare console per errori

### localStorage non persiste
- Modalità incognito/privato disabilita localStorage
- Spazio esaurito: svuotare localStorage
- Cookie di terze parti potrebbe essere disabilitato

### Aggiornamenti non visibili
- Controllare DevTools > Application > LocalStorage
- Verificare che il Worker sia attivo (DevTools > Dedicated Workers)
- Forzare refresh manuale con pulsante 🔄

## 📚 Riferimenti

- [MDN Web Workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API)
- [localStorage API](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage)
- [Performance Best Practices](https://web.dev/performance/)

---

**Sviluppato per LLM Monitor v1.1.0** 🦙