# Analisi del Progetto Bookish

## 1. Qualità del Codice

### Punti di Forza
- **Architettura modulare**: blueprint Flask separati per convertitore, reader, API
- **Servizi isolati**: converter, formatter, SSE manager, database come moduli indipendenti
- **Pattern Factory**: `create_app()` con registrazione blueprint e init DB
- **Responsabilità chiare**: ogni file ha uno scopo ben definito
- **Thread safety**: lock `threading.Lock()` in SSE manager per accesso concorrente
- **Frontend vanilla**: nessuna dipendenza framework pesante, codice lineare
- **Path robust**: `os.path.basename()`, `secure_filename()`, sanity check su ogni path
- **Error handling**: try/except in routes con fallback e messaggi d'errore

### Aree di Miglioramento
- **Tipo**: usare mypy con typing anche per i parametri Flask
- **Test**: nessuna suite di test (accettabile per single-user)
- **Logging**: log minimale, potrebbe essere più strutturato
- **Cleanup SSE**: il thread cleanup ogni 60s funziona ma non è elegante
- **Race condition DB**: `allow_commit` come flag per SKIP/LOCKED è un workaround. In pratica SQLite gestisce bene le race con WAL mode — testato con debounce 1.5s e non dà problemi

## 2. Sicurezza

- ✅ **Path traversal**: `secure_filename()` + `os.path.basename()` + sanity check
- ✅ **Estensione validata**: controllo su SUPPORTED_FORMATS/OUTPUT_FORMATS_BY_INPUT
- ✅ **MIME check**: al download per prevenire tipo sbagliato
- ✅ **Cleanup automatico**: file temporanei eliminati dopo 1h
- ✅ **SQLite parametriziato**: query con placeholder `?`, niente interpolazione stringhe
- ✅ **Niente eval/exec**: zero codice dinamico pericoloso
- ✅ **CSRF**: non rilevante per single-user con API REST semplici
- ⚠️ **Secret key hardcoded**: default in `app.py`. Impostare `BOOKISH_SECRET` in produzione
- ⚠️ **Upload estensione**: solo check estensione, non MIME reale (sufficiente per single-user)
- ⚠️ **No rate limiting**: Upload illimitati (accettabile per uso personale)

## 3. Performance

- **SSE leggero**: nessuna dipendenza (Celery/Redis), thread in memoria
- **SQLite WAL mode**: letture non bloccano scritture
- **File temporanei su disco**: senza streaming, ma i formati ebook sono <50MB
- **Debounce position save (1.5s)**: evita flooding di scritture DB ad ogni cambio pagina
- **Sync server + localStorage**: UX veloce con aggiornamento asincrono
- **WeasyPrint**: lento su PDF grandi (>200 pagine) per limiti del motore di rendering
- **Pandoc**: performante, tempi medi 1-5s per file standard

## 4. Manutenibilità

- **Codice auto-documentante**: nomi di funzioni e variabili chiari
- **Config centralizzata**: `config.py` con tutti i path e formati
- **Servizi disaccoppiati**: modificare il converter non impatta reader o API
- **Separazione API**: le rotte `/api/` sono in blueprint dedicato
- **reader.js separato**: anche se lungo (800+ righe), è l'unico file JS del reader
- **CSS strutturato**: sezioni per reader, converter, generiche
- **Documentazione completa**: README, architecture, deploy, wiki

## 5. Affidabilità

- **Porta libera automatica**: se 5000 occupata, `find_free_port()` scorre fino a trovare una libera
- **Cleanup temp**: thread timer ogni 60 minuti elimina file scaduti
- **Fallback localStorage**: se server API non risponde, bookmarks e posizioni funzionano comunque (solo in locale)
- **Content hash come ID**: stesso file → stesso hash → stessi segnalibri, anche su PC diverso
- **Auto-creazione DB**: database creato al primo avvio senza intervento manuale
- **Gestione errori conversione**: errori Pandoc catturati e propagati come messaggio utente

## 6. Dipendenze

### Python (produzione)
| Pacchetto | Versione | Ruolo |
|---|---|---|
| Flask | ≥3.0 | Web framework |
| Flask-CORS | ≥4.0 | CORS per API |
| pypandoc_binary | ≥2.0 | Pandoc binary + binding |
| WeasyPrint | ≥62 | PDF da HTML |
| python-docx | ≥1.0 | DOCX post-processing |
| beautifulsoup4 | ≥4.0 | HTML/tabelle post-processing |
| lxml | ≥5.0 | Parser XML per BeautifulSoup |
| Werkzeug | ≥3.0 | Secure filename, HTTP utilities |
| markdown | ≥3.0 | MD → HTML per anteprime |
| pdfminer.six | ≥2022 | Testo base da PDF |

### Frontend (browser)
| Libreria | Versione | Ruolo |
|---|---|---|
| epub.js | 0.3.93 | Render EPUB |
| pdf.js | 3.x | Render PDF |
| PDF.js | 3.x | Text layer PDF |
| jszip | 3.x | ZIP per EPUB |

## 7. Architettura Componenti

```
┌──────────────────────────────────────────────────┐
│                    Flask App                      │
│                                                    │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐       │
│  │ Convert  │  │  Reader  │  │  API     │       │
│  │ /upload  │  │ /reader  │  │ /api/*   │       │
│  │ /progress│  │ /reader/ │  │          │       │
│  │ /download│  │  <file>  │  │ bookmarks│       │
│  └─────┬────┘  └────┬─────┘  └────┬─────┘       │
│        │             │             │              │
│  ┌─────▼─────────────▼─────────────▼──────┐      │
│  │            Services                      │      │
│  │  ┌──────────┐ ┌──────────┐             │      │
│  │  │converter │ │ database │─▶ SQLite    │      │
│  │  │sse_mgr   │ └──────────┘             │      │
│  │  │formatter │                          │      │
│  │  └──────────┘                          │      │
│  └──────────────────────────────────────────┘      │
│                                                    │
│  Filesystem: uploads/  converted/  bookish.db      │
└──────────────────────────────────────────────────┘
```

## 8. Conclusioni

**Bookish è un'applicazione solida per il suo scopo**: self-hosted, single-user, conversione e lettura ebook.

### Cosa funziona bene
- Il flusso conversione con SSE progress è semplice ma efficace
- Il reader supporta EPUB, PDF e formati testo in un'unica interfaccia
- La persistenza segnalibri con content_hash è robusta: funziona anche su PC diversi
- Il fallback localStorage assicura che il reader non si rompa se il server API è giù
- Slider larghezza e help modal completano l'UX del reader
- La documentazione è completa e in italiano

### Cosa sarebbe migliorabile (ma non necessario per single-user)
- Suite di test automatici
- Pipeline CI/CD
- HTTPS nativo (gestito da reverse proxy in produzione)
- Gestione code block più sofisticata nel reader testo
- Mobile optimization
- Logging strutturato (può essere aggiunto con poche righe)