# Architettura di Bookish

## Panoramica

Bookish è un'applicazione web Flask monolitica progettata per l'uso self-hostato. Si compone di due macro-funzionalità: un **convertitore di formati ebook** e un **reader web** per visualizzarli.

```
┌──────────┐     ┌─────────────────────────────────────┐
│ Browser  │────▶│              Flask                   │
│          │     │  ┌─────────┐  ┌──────────────────┐   │
│ HTML/CSS │     │  │ Routes  │  │    Services       │   │
│ JS/ES    │     │  │         │  │                  │   │
│          │     │  │convert  │─▶│converter.py      │──▶│ Pandoc
│epub.js   │     │  │reader   │  │sse_manager.py    │   │ WeasyPrint
│pdf.js    │     │  │         │  │formatter.py      │   │ python-docx
└──────────┘     │  └─────────┘  └──────────────────┘   │
                 └─────────────────────────────────────┘
                          │            │
                     uploads/     converted/
                     (temporaneo) (temporaneo)
```

## Stack Tecnologico

| Componente | Tecnologia | Ruolo |
|---|---|---|
| Backend | Flask 3.x + Jinja2 | Server web, routing, template engine |
| Conversione | Pandoc 3.x (via pypandoc) | Motore di conversione principale |
| PDF avanzato | WeasyPrint | PDF con layout precisi da HTML |
| DOCX avanzato | python-docx | Post-processing documenti Word |
| Frontend | JavaScript vanilla | Nessun framework pesante |
| Reader EPUB | epub.js 0.3 | Renderer EPUB lato client |
| Reader PDF | pdf.js 3.x | Renderer PDF lato client |
| Progresso | SSE (Server-Sent Events) | Barra progresso real-time |
| Storage | Filesystem locale | `uploads/` e `converted/` |

## Flusso Conversione

```
Upload file  →  Validazione formato  →  Avvio thread conversione
                                            │
                     ┌──────────────────────┘
                     ▼
              SSE Manager crea task_id
                     │
              Frontend apre connessione SSE
                     │
              Converter dispatcher:
              ├─ Pandoc per formati standard
              ├─ WeasyPrint per PDF avanzati
              ├─ python-docx per DOCX
              └─ BeautifulSoup per tabelle/HTML
                     │
              Ogni fase → update SSE progress
                     │
                     ▼
         File salvato in converted/
         SSE invia download_url
```

## Flusso Reader

```
Upload file  →  Salva in uploads/  →  Redirect a /reader/<file_id>
                                          │
                                   Template reader.html
                                          │
                                   Rileva formato:
                                   ├─ EPUB → epub.js
                                   ├─ PDF → pdf.js
                                   └─ Testo → HTML renderizzato
                                          │
                                   Interazioni tutte lato client:
                                   - Temi, zoom, ricerca
                                   - Segnalibri, posizione
                                   - Salvataggio in LocalStorage
```

## Architettura del Codice

### Routes (`bookish/routes/`)

- **`convert.py`** — Blueprint `/upload`, `/progress/<task_id>`, `/download/<filename>`, `/formats`
- **`reader.py`** — Blueprint `/reader`, `/reader/<filename>`, `/reader/serve/<filename>`, `/reader/formats`

### Services (`bookish/services/`)

- **`converter.py`** — Dispatcher che sceglie Pandoc o pipeline custom in base alla coppia input/output. Aggiorna SSE progress ad ogni fase.
- **`sse_manager.py`** — Gestisce task in memoria con `{task_id: {progress, status, output_file}}`. Thread-safe con lock.
- **`formatter.py`** — WeasyPrint PDF da HTML con post-processing (tabelle, immagini via BeautifulSoup).

### Frontend (`bookish/static/js/`)

- **`main.js`** — Convertitore: drag&drop, form, SSE connection, download
- **`reader.js`** — Reader: epub.js/pdf.js/text viewer, side panel, temi, ricerca, segnalibri, posizione

## Decisioni Architetturali

| Decisione | Motivazione |
|---|---|
| Thread invece di Celery | Uso singolo utente, niente Redis, minore complessità |
| SSE invece di WebSocket | Sincrono semplice, nessuna dipendenza extra, supporto nativo |
| LocalStorage per reader | Zero backend, nessun DB necessario per lettura |
| File temporanei con cleanup | Nessun database, i file si auto-puliscono dopo 1h |
| JS vanilla | Nessun framework, leggero, manutenibile |
| Pandoc via pypandoc-binary | Include Pandoc binary, nessuna installazione systema richiesta |

## Limiti Attuali

- **Thread in memoria**: I task di conversione muoiono se il processo Flask viene killato
- **No autenticazione**: Uso personale, nessun multi-utente
- **No HTTPS di base**: Da abilitare con reverse proxy (nginx/caddy)
- **No ottimizzazione mobile**: Funziona ma non è prioritario
- **estione code block reader**: Reader testo ha markdown renderer minimale