llm-monitor/docs/DEVELOPMENT.md

Development Setup - LLM Monitor

🛠️ Setup Locale

1. Installare Dipendenze Python

python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
pip install -r requirements-dev.txt

2. Installare Dipendenze Node (per Tailwind CSS)

npm install

3. Compilare Tailwind CSS

Modalità Development (watch mode)

npm run tailwind:dev

Questo comando:

• Compila app/web/static/css/input.css in app/web/static/css/output.css
• Rimane in watch mode per compilare automaticamente al salvataggio
• Legge la configurazione da tailwind.config.js

Modalità Production (minified)

npm run tailwind:build

Questo comando:

• Compila e minifica il CSS
• Ottimizzato per produzione
• Usato durante il build Docker

4. Avviare l'Applicazione

In una finestra di terminale (con npm run tailwind:dev in watch):

source venv/bin/activate
python3 -m uvicorn main:app --reload --host 0.0.0.0 --port 8000

O usar il comando Makefile:

make dev

Accedi a: http://localhost:8000

---

📱 Workflow di Sviluppo

Sviluppare il Frontend

1. Terminal 1 - Tailwind Watcher:

   npm run tailwind:dev
   

2. Terminal 2 - FastAPI Dev Server:

   source venv/bin/activate
   uvicorn main:app --reload
   

3. Modificare i file:

   • HTML: app/web/templates/index.html, servers.html, models_running.html
   • CSS input: app/web/static/css/input.css (raramente, usa classi Tailwind)
   • JavaScript: app/web/static/js/app.js, servers.js, models-running.js, data-sync.worker.js

   ⚠️ Classi Tailwind dinamiche: Le classi generate dinamicamente via innerHTML (es. in accordion o card) non vengono rilevate dal JIT scanner. Usa stili inline (style="...") o classi hardcoded nei template HTML per queste situazioni.

4. Compilato automaticamente:

   • Tailwind genera app/web/static/css/output.css automaticamente
   • FastAPI recarica il server automaticamente
   • Browser reload automatico (se abilitato)

---

🐳 Build Docker

Il Dockerfile multi-stage:

1. Stage 1 - CSS Builder (Node):

   • Installa dipendenze npm
   • Compila Tailwind CSS
   • Genera app/web/static/css/output.css

2. Stage 2 - Python Builder:

   • Installa dipendenze Python
   • Crea virtualenv

3. Stage 3 - Runtime:

   • Copia CSS compilato dal Stage 1
   • Copia Python packages dal Stage 2
   • Immagine finale ottimizzata (~300MB)

Build locale:

docker build -t llm-monitor:latest .

Eseguire il container:

docker run -p 8000:8000 --env-file .env llm-monitor:latest

---

⚙️ Configurazione Tailwind

File: tailwind.config.js

module.exports = {
  content: [
    "./app/web/templates/**/*.html",
    "./app/web/static/**/*.js",
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

Content: Specifica quali file Tailwind deve scansionare per le classi utilizzate

---

🎯 CSS Architecture

Input CSS

File: app/web/static/css/input.css

@tailwind base;
@tailwind components;
@tailwind utilities;

Output CSS

File: app/web/static/css/output.css (generato)

• Contiene solo le classi Tailwind utilizzate
• Minificato in produzione (~30KB)
• Ottimizzato per performance

Usage in HTML

File: app/web/templates/index.html

<!-- Usa il CSS compilato (produzione) -->
<link rel="stylesheet" href="/static/css/output.css">

<!-- Fallback CDN per sviluppo (se output.css non esiste) -->
<script src="https://cdn.tailwindcss.com"></script>

---

📝 Tips di Sviluppo

Hot Reload CSS

npm run tailwind:dev
# Guarda i file e compila automaticamente

Debug CSS Compilation

npm run tailwind:build
# Se il CSS non appare, verifica:
# 1. Le classi sono usate nei file HTML/JS?
# 2. C'è un errore nella sintassi CSS?
# 3. I percorsi in tailwind.config.js sono corretti?

Aggiungere Nuove Classi Tailwind

1. Modifica i file HTML/JS con classi Tailwind
2. Tailwind watcher le detetta automaticamente
3. output.css viene rigenerato

<!-- Nuova classe aggiunta -->
<div class="bg-gradient-to-r from-purple-500 to-pink-500">
  <!-- Viene aggiunta automaticamente al CSS compilato -->
</div>

---

🚀 Production Checklist

• Eseguire npm run tailwind:build per minificare
• Verificare che output.css sia generato
• Eseguire i test Python: make test
• Eseguire i test E2E: npm run test:e2e

---

🧪 Testing

Unit Test (pytest)

# Tutti i test
pytest tests/ -v

# Con coverage
pytest tests/ --cov=app

E2E Test (Playwright)

I test E2E verificano il comportamento del browser (cache-first, navigazione, PWA).

# Installare i browser Playwright (prima volta)
npx playwright install --with-deps

# Eseguire i test E2E (richiede Ollama attivo)
OLLAMA_HOST=http://<ollama-host>:11434 npm run test:e2e

# Con report HTML
npm run test:e2e -- --reporter=html

I test si trovano in tests/e2e/. Il report viene generato in playwright-report/ (gitignored).

Makefile

make test          # pytest
make lint          # flake8
make format        # black
make dev           # uvicorn --reload
make deploy-no-cache  # Docker rebuild forzato

• Controllare che il container Docker usi il CSS compilato
• Test performance con Lighthouse
• Verifica bundle size output.css

---

🔗 Risorse

• Tailwind CSS Documentation
• Tailwind CLI
• FastAPI Hot Reload
• Docker Multi-Stage Builds

---

Ultimo aggiornamento: Aprile 2024