Bookish — Design Document

Data: 2026-07-22 Stato: Validato

Overview

Bookish è un'app Flask self-hosted per convertire eBook tra formati e visualizzarli in un reader web integrato. Uso personale, girante su server Proxmox.

Stack

Componente	Tecnologia
Backend	Flask (Python 3)
Template	Jinja2
Conversione	Pandoc + WeasyPrint + python-docx
Frontend reader	epub.js + pdf.js
Progresso real-time	SSE (Server-Sent Events)
DB opzionale	SQLite (cronologia, reading position)
Storage locale	`uploads/` + `converted/`

Struttura directory

bookish/
├── app.py
├── config.py
├── requirements.txt
├── run.sh
├── uploads/
├── converted/
└── bookish/
    ├── __init__.py           # create_app factory
    ├── routes/
    │   ├── __init__.py
    │   ├── convert.py         # upload, convert, download, SSE
    │   └── reader.py          # reader page, serve file
    ├── services/
    │   ├── __init__.py
    │   ├── converter.py       # dispatcher Pandoc/lib specialistiche
    │   ├── sse_manager.py     # eventi progresso in memoria
    │   └── formatter.py       # PDF/DOCX layout avanzato
    ├── templates/
    │   ├── base.html
    │   ├── index.html         # upload + convertitore
    │   └── reader.html        # reader
    └── static/
        ├── css/
        ├── js/
        └── lib/               # epub.js, pdf.js

Formati supportati

Formato	Input	Output	Engine
EPUB	✅	✅	Pandoc
Markdown	✅	✅	Pandoc
DOCX	✅	✅	Pandoc + python-docx
PDF	✅	✅	Pandoc + WeasyPrint
TXT	✅	✅	Pandoc
HTML	✅	✅	Pandoc
FB2	✅	✅	Pandoc
MOBI	✅	❌	Pandoc
LaTeX	✅	✅	Pandoc

Flusso di conversione con SSE

Utente carica file + seleziona formato output
Flask avvia thread conversione, restituisce task_id
Frontend apre connessione SSE a /progress/<task_id>
Thread conversione emette eventi progresso (20%, 40%, ... 100%)
A 100%, SSE invia download_url
Frontend mostra link download
File in converted/ puliti dopo 1h

Stati progresso: started → analyzing → converting (con %) → finalizing → completed / error

Conversion pipeline

convert(input_file, output_format):
  ├─ INPUT non-testuali (EPUB/FB2/MOBI/HTML/LaTeX) → Pandoc per qualsiasi output
  ├─ PDF in → EPUB/MD/DOCX/TXT/HTML → Pandoc
  ├─ DOCX → PDF → Pandoc → HTML intermedio → WeasyPrint
  ├─ MD/TXT → EPUB → Pandoc con template EPUB
  ├─ DOCX → EPUB/MD/HTML → Pandoc
  ├─ MD/TXT/HTML → DOCX → Pandoc + python-docx post-processing
  └─ Output PDF avanzato → WeasyPrint con template HTML custom

Reader

Route /reader/<file_id> carica il reader con:

EPUB → epub.js
PDF → pdf.js
Formati testo (md, txt, html, docx, fb2) → convertiti in HTML da Pandoc, renderizzati in iframe

Funzionalità reader

Feature	Come
Zoom	epub.js fontSize / pdf.js zoom / CSS scale
Temi (giorno/notte/seppia)	epub.js themes / pdf.js CSS filter
Font (dimensione, famiglia)	epub.js fontSize + CSS injection
Ricerca full-text	epub.js search API / pdf.js findController
Sommario	epub.js navigation / pdf.js outline
Segnalibri	LocalStorage
Salvataggio posizione	Auto-save su LocalStorage ad ogni cambio pagina
Vista singola/doppia	epub.js spread mode
Scorrimento continuo	epub.js continuous manager
Navigazione tastiera	← → per pagina, +/- per zoom
Fullscreen	Fullscreen API
Annotazioni/highlights	epub.js annotations API

Layout reader

Sidebar sinistra collassabile (Indice, Ricerca, Note)
Barra superiore col titolo capitolo
Area lettura centrale
Toolbar inferiore con navigazione, zoom, temi, fullscreen
Toolbar si nasconde dopo 3s inattività

Frontend convertitore

Drag & drop upload
Griglia formati output con validazione dinamica
Barra progresso animata con SSE
Download diretto a completamento
Tema chiaro iniziale

Gestione errori

Formato input non supportato → messaggio chiaro
Formato output non valido → bottoni disabilitati
Pandoc non installato → errore all'avvio
File >50MB → bloccato
Conversione fallita → SSE evento error
Pulizia automatica file vecchi >1h

Pre-requisiti server

Python 3.10+
Pandoc installato via apt
WeasyPrint dipende da librerie di sistema (libpango, libcairo)

4.6 KiB Raw Blame History