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:

{
  "status": "healthy",
  "ollama_status": "online",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Struttura dati models:

{
  "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:

const REFRESH_INTERVAL = 30000; // 30 secondi

Disabilitare Web Worker (debug)

Nel browser console:

window.app.worker = null;
window.app.syncDataInMainThread();

🛠️ Sviluppo

Debug del Worker

// In data-sync.worker.js
console.log("Worker sync triggered", new Date());

Console del browser (DevTools > Dedicated Worker)

Ispezionare localStorage

// 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
• localStorage API
• Performance Best Practices

---

Sviluppato per LLM Monitor v1.1.0 🦙