novela/docs/TECHNICAL.md

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.