# Novela 2.0 - Technical Plan

## Scope
Dit document beschrijft de technische uitvoering van de blauwdruk in implementeerbare stappen.

## Architectural Rules
- Bestand is source of truth.
- Database is snelle index.
- Schrijfacties: eerst bestand, dan DB.
- Lezen: primair uit DB, met scan/rescan voor recovery.

## Data Integrity Rules
- Alle child-tabellen refereren `library(filename)` met `ON DELETE CASCADE`.
- Verwijderen van een boek is een enkel `DELETE FROM library` na file-delete.
- Rename-flow moet `filename` synchroon aanpassen in:
  - `library`
  - `book_tags`
  - `reading_progress`
  - `reading_sessions`
  - `library_cover_cache`

## Runtime Lifecycle
- Startup:
  1. `init_pool()`
  2. `run_migrations()`
  3. routers mounten
- Shutdown:
  1. `close_pool()`

## Module Responsibilities
- `db.py`: pool ownership + connection helpers.
- `migrations.py`: schema + seeds.
- `routers/library.py`: import/scan/delete/cover/home/stats.
- `routers/reader.py`: lezen + progress + metadata patch + epub editor endpoints.
- `routers/editor.py`: uiteindelijke dedicated editor routes (kan initieel delegaten).
- `routers/grabber.py`: scraper orchestration + credentials + SSE.
- `routers/backup.py`: Dropbox sync + pg dump + logging.
- `routers/settings.py`: break patterns + cleaning endpoints.

## Endpoint Contract Notes
- Alle file routes gebruiken veilige path-resolutie tegen traversal.
- Cover endpoint gedrag:
  - cached eerst
  - fallback raw extract
  - anders 404
- Progress payload:
  - EPUB: `{ cfi, progress }`
  - PDF/CBR: `{ page, progress }`

## Backup Plan
- `POST /api/backup/run`:
  - insert `running` in `backup_log`
  - sync files naar Dropbox (incremental op mtime+size)
  - draai `pg_dump` en upload `.sql`
  - update `backup_log` naar `success`/`error`
- OAuth token opslag via `credentials` (`site='dropbox'`) en encrypted-at-rest (Fernet) in de database.
- Beheer via webinterface op `/credentials-manager` (site: `dropbox`, token in password veld).
- Legacy plaintext credentials worden automatisch gemigreerd naar encrypted bij uitlezen.

## Migration Plan from Current State
1. Behoud v1 stabiele modules (`epub.py`, `xhtml.py`, scrapers, templates/static).
2. Introduceer nieuwe routers zonder bestaande frontend te breken (compat routes waar nodig).
3. Schakel library root om naar `library/`.
4. Activeer PDF/CBR scan en reader paden.
5. Split editor-routes uit reader naar dedicated `editor.py`.
6. Volledige scrape->epub flow migreren naar `grabber.py`.
7. Backup volledig afronden (Dropbox + pg_dump).

## Test Matrix
- Import:
  - EPUB met/zonder cover
  - PDF 1+ pagina
  - CBR/CBZ met images
- Reader:
  - EPUB CFI save/load
  - PDF page render + page progress
  - CBR page render + page progress
- Metadata edit:
  - rename path
  - db references geupdate
  - old row cleanup
- Delete:
  - file weg
  - lege dirs gepruned
  - cascade records weg
- Break patterns:
  - create/update/delete/enable
- Grabber:
  - preload/debug
  - convert job events
- Backup:
  - status/history
  - success/error logging

## Deployment Notes
- Docker image bouwt vanuit `containers/novela`.
- Stack uit `stack/stack.yml` met env uit `stack/novela.env`.
- `NOVELA_MASTER_KEY` is verplicht voor encrypt/decrypt van credentials in de database en moet stabiel blijven na initiele ingebruikname.
- Postgres volume persistent.
- Library mount persistent.