bookish/docs/architecture.md

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, con SQLite per persistenza di segnalibri e posizioni di lettura.

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

Stack Tecnologico

Componente	Tecnologia	Ruolo
Backend	Flask 3.x + Jinja2	Server web, routing, template engine
Database	SQLite (via sqlite3)	Segnalibri e posizioni di lettura
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 + SQLite	uploads/, converted/, bookish.db

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 con Persistenza

Upload file → Salva in uploads/ → Calcola SHA256 (content_hash)
                                       │
                                Redirect a /reader/<file_id>
                                       │
                                Template reader.html (contiene BOOKISH_HASH)
                                       │
                                Rileva formato:
                                ├─ EPUB → epub.js
                                ├─ PDF → pdf.js
                                └─ Testo → HTML renderizzato
                                       │
                                Interazioni lato client:
                                - Temi, zoom, ricerca, indice
                                - Slider larghezza lettura
                                - Aiuto contestuale (?)
                                       │
                                Segnalibri e posizione:
                                ├─ Salvataggio immediato in localStorage
                                ├─ Sync asincrono su server SQLite
                                └─ Caricamento da server con fallback localStorage

Il content_hash (SHA256 del file) è l'identificatore univoco del libro. Viene calcolato:

• All'upload (restituito nella response)
• All'apertura del reader (dal file su disco)
• Garantisce che lo stesso contenuto → stesso hash → stessi segnalibri

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. Calcola SHA256 del file per identificare univocamente il libro.
• api.py — Blueprint /api/bookmarks/* (CRUD segnalibri), /api/position/* (salva/carica posizione lettura)

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).
• database.py — Gestione SQLite con WAL mode. Due tabelle: bookmarks (per file) e reading_positions (una per file).

Frontend (bookish/static/js/)

• main.js — Convertitore: drag&drop, form, SSE connection, download
• reader.js — Reader completo (800+ righe): epub.js/pdf.js/text viewer, sidebar con TOC/cerca/segnalibri, temi, zoom, slider larghezza, help modal, sync server per bookmarks e posizioni

Template (bookish/templates/)

• base.html — Layout base con navbar e logo SVG
• index.html — Convertitore con drag&drop, griglia formati, progress bar
• reader.html — Reader con toolbar, sidebar, help modal, e script inline per BOOKISH_FILE, BOOKISH_EXT, BOOKISH_HASH

API REST

Metodo	Path	Descrizione
POST	/upload	Carica file e avvia conversione
GET	/progress/<task_id>	SSE stream progresso
GET	/download/<filename>	Scarica file convertito
GET	/formats?input=<ext>	Formati disponibili
GET	/reader	Pagina reader
GET	/reader/<filename>	Reader per file
GET	/reader/serve/<filename>	Serve file al reader
GET	/reader/formats	Formati supportati
GET	/api/bookmarks/<hash>	Segnalibri del libro
POST	/api/bookmarks	Aggiunge segnalibro
DELETE	/api/bookmarks/<id>	Elimina segnalibro
GET	/api/position/<hash>	Posizione di lettura
PUT	/api/position/<hash>	Salva posizione di lettura

Database SQLite (bookish.db)

Tabella bookmarks

Colonna	Tipo	Descrizione
id	TEXT PK	ID univoco del segnalibro
content_hash	TEXT	SHA256 del file libro
type	TEXT	epub, pdf, text
cfi	TEXT	CFI per EPUB
href	TEXT	Href del capitolo EPUB
page	INTEGER	Numero pagina PDF
total_pages	INTEGER	Pagine totali (PDF)
scroll_pct	INTEGER	% scorrimento (testo)
label	TEXT	Etichetta visualizzata
chapter_title	TEXT	Titolo capitolo corrente
created	REAL	Timestamp creazione

Tabella reading_positions

Colonna	Tipo	Descrizione
content_hash	TEXT PK	SHA256 del file libro
type	TEXT	epub, pdf, text
cfi	TEXT	CFI per EPUB
href	TEXT	Href del capitolo
page	INTEGER	Pagina PDF
scroll_pct	INTEGER	% scorrimento (testo)
chapter_title	TEXT	Titolo capitolo
updated	REAL	Timestamp ultimo aggiornamento

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
content_hash (SHA256) invece di UUID	Identifica il contenuto, non l'istanza. Stesso file = stesso hash
SQLite per persistenza	Incluso in Python, zero configurazione, file singolo
Server + localStorage come fallback	Offline-resilient, UX istantanea, sync asincrono
Position save debounced (1.5s)	Evita flooding di scritture SQLite ad ogni pagina
File temporanei con cleanup	Nessun accumulo, auto-pulizia 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
• Gestione code block reader: Reader testo ha markdown renderer minimale