feat: complete translator stack

docs/architecture.md

@@ -0,0 +1,62 @@
+# Traduttore Multiformato - Architettura e Regole
+
+## 1. Chunking e preservazione struttura
+- Ogni chunk copre max 2.500 caratteri (testi vocali) o un paragrafo intero se più corto.
+- Il chunking cerca di rispettare titoli e separazioni: i chunk iniziano al punto in cui viene individuato un titolo o una riga vuota pre-esistente. Titoli (H1/H2/H3 o linee con `#`) vengono mantenuti e replicati nel chunk iniziale che li contiene.
+- Se il chunk contiene più paragrafi, viene inserito un marcatore interno (`¶`) per mantenere la separazione e garantire il merge coerente.
+- Per PDF/EPUB, il parser mantiene i metadati originali (titolo, sottotitoli) e li allega al primo chunk.
+- Chunk sequenziali vengono inviati a `translategemma:latest` via Ollama e la traduzione restituita viene appesa immediatamente all'interfaccia.
+- Il sistema calcola ETA dinamico: media temporale (ms o s) degli ultimi 3 chunk * chunk rimanenti; aggiornato dopo ogni chunk completato.
+
+## 2. Metadati e stato della sessione
+- Ogni sessione mantiene:
+  - `session_id` (UUID breve)
+  - `file_title`: nome file caricato.
+  - `text_title`: se disponibile, titolo interno del documento.
+  - `source_lang`: lingua rilevata (via `langdetect`).
+  - `target_lang`: scelta dropdown (almeno `en`, `it` + altre 13 principali).
+  - `total_chunks` e `current_chunk_index`.
+  - `started_at`, `ended_at`, `last_chunk_at` (timestamp ISO).
+  - `status`: `pending`, `running`, `stopped`, `error`, `completed`.
+  - `eta_seconds` e `chunks_remaining` ma anche `error_message`.*
+- Il backend espone `/status/{session_id}` per restituire stato, ETA, chunk totali/rimanenti, flag stop, e testo tradotto attualmente completo.
+
+## 3. API FastAPI proposta
+- `POST /upload`:
+  - Input: file multipart, `target_lang` (codice ISO), optional `session_id` (per riprendere).
+  - Output: metadati del file, session_id, chunk count, detected source lang.
+  - Effettua parsing in `processors/` e costruisce buffer chunking.
+- `POST /start`:
+  - Input: `session_id`, `start_from_chunk` optional.
+  - Output: conferma avvio, stats iniziali.
+  - Inizia loop chunk → Ollama, aggiorna stato, notifica SSE/polling.
+- `POST /stop`:
+  - Input: `session_id`.
+  - Output: flag stop e stato corrente; ferma la sequenza.
+- `GET /status/{session_id}`:
+  - Output: sessione JSON con tuti i campi sopra incluse caption (titolo file/text, numeri chunk, ETA per UI).
+- `GET /stream/{session_id}` (opzionale SSE o websocket): trasmette chunk completati insieme al testo parziale per box traduzione.
+
+## 4. Interfaccia e flusso operativo
+- Dropdown lingua: 15 lingue principali (es. `en`, `it`, `es`, `fr`, `de`, `pt`, `ru`, `zh`, `ja`, `ko`, `ar`, `hi`, `nl`, `sv`, `pl`). Inglese e italiano obbligatori.
+- Titolo file e titolo testo in caption; seguenti caption per orari e chunk:
+  - `File caricato: {file_title}`
+  - `Titolo documento: {text_title or titolo fallback}`
+  - `Avvio traduzione: {started_at}`
+  - `Fine traduzione: {ended_at}` (aggiornato a fine)
+  - `ETA: {eta_seconds} sec` (aggiornamento ogni chunk)
+  - `Chunk totali: {total_chunks}`
+  - `Chunk rimanenti: {chunks_remaining}`
+- Box traduzione aggiorna per append di chunk completato; log di errore appare nella caption dedicata.
+- Pulsanti: `Avvia traduzione` (chiama /start), `Stop traduzione` (chiama /stop).
+
+## 5. Comunicazione con Ollama
+- Client HTTP (es. `httpx.AsyncClient`) verso `https://ollama.solarpi.net/api/models/translategemma:latest`.
+- Payload chunk: {"prompt": "translate ...", ... } definire parametro prompt per target.
+- Timeout controllato (es. 60s) e retry (max 2) per chunk.
+- Se errore, sessione passa in `error` con `error_message` e UI mostra caption rosso.
+
+## 6. Next step suggerito
+1. Creare `backend/` e `frontend/` skeleton con router, componenti e placeholder per captions e stato.
+2. Implementare parser file e chunker.
+3. Costruire client Ollama e endpoint di stato.