llm-monitor/docs/DEVELOPMENT.md

# Development Setup - LLM Monitor

## 🛠️ Setup Locale

### 1. Installare Dipendenze Python

```bash
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)

```bash
npm install
```

### 3. Compilare Tailwind CSS

#### Modalità Development (watch mode)
```bash
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)
```bash
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):

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

O usar il comando Makefile:
```bash
make dev
```

Accedi a: http://localhost:8000

---

## 📱 Workflow di Sviluppo

### Sviluppare il Frontend

1. **Terminal 1 - Tailwind Watcher:**
   ```bash
   npm run tailwind:dev
   ```

2. **Terminal 2 - FastAPI Dev Server:**
   ```bash
   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:
```bash
docker build -t llm-monitor:latest .
```

### Eseguire il container:
```bash
docker run -p 8000:8000 --env-file .env llm-monitor:latest
```

---

## ⚙️ Configurazione Tailwind

File: `tailwind.config.js`

```javascript
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`
```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`
```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
```bash
npm run tailwind:dev
# Guarda i file e compila automaticamente
```

### Debug CSS Compilation
```bash
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

```html
<!-- 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)

```bash
# 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).

```bash
# 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

```bash
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](https://tailwindcss.com/docs)
- [Tailwind CLI](https://tailwindcss.com/docs/installation)
- [FastAPI Hot Reload](https://fastapi.tiangolo.com/#example-upgrade)
- [Docker Multi-Stage Builds](https://docs.docker.com/build/building/multi-stage/)

---

**Ultimo aggiornamento:** Aprile 2024