novela/docs/TECHNICAL.md

Novela 2.0 - Technical Status (Develop)

Scope

Dit document beschrijft de actuele technische status van de develop codebase. Dit document is de primaire technische documentatie voor de huidige codebase.

Architecture

• Stack: FastAPI, Jinja2 templates, plain JS, PostgreSQL 16, Docker.
• Startup lifecycle (main.py):
  1. init_pool()
  2. run_migrations()
  3. start_backup_scheduler()
  4. routers mounten
• Shutdown lifecycle:
  1. stop_backup_scheduler()
  2. close_pool()
• Source-of-truth regel: bestand op schijf leidend, database als index/cache.

Router Status

routers/library.py

• GET /library
• GET /api/library
• POST /library/rescan
• POST /library/import (EPUB/PDF/CBR/CBZ)
• DELETE /library/file/{filename}
• GET /library/cover/{filename}
• GET /library/cover-cached/{filename}
• POST /library/cover/{filename} (EPUB)
• POST /library/want-to-read/{filename}
• POST /library/archive/{filename}
• POST /library/new/mark-reviewed (bulk needs_review=false)
• GET /home
• GET /api/home
• GET /stats
• GET /api/stats
• GET /library/list (compat)

GET /api/library draait standaard in fast-path (DB-only, geen full disk rescan). Voor geforceerde sync: GET /api/library?rescan=true of POST /library/rescan. include_file_info=true is optioneel voor bestandsgrootte/mtime verrijking.

/api/home levert:

• continue_reading
• shorts_unread
• novels_unread
• shorts_read
• novels_read

/api/stats levert naast totals ook chart- en history-data voor stats.html:

• reads_by_month, reads_by_dow, reads_by_hour
• genre_counts, publisher_counts, fav_genre, fav_publisher
• top_books, history

Home-secties filteren series uit met:

• COALESCE(series, '') = ''
• filename NOT LIKE '%/Series/%'

Read-secties op Home zijn gesorteerd op oudste eerst:

• shorts_read: ORDER BY MAX(read_at) ASC
• novels_read: ORDER BY MAX(read_at) ASC

routers/reader.py

• Epub serving/chapters/images
• Reader pagina + book detail
• Metadata patch (PATCH /library/book/{filename})
• Progress read/write/delete
• Mark-as-read
• PDF render endpoint
• CBR/CBZ page endpoint
• Genres endpoint

routers/editor.py

• Editor pagina
• Chapter get/save
• Chapter add
• Chapter delete

routers/grabber.py

• Grabber pagina + convert/debug flows
• SSE events
• Credentials beheer voor scraper-sites
• Credentials manager UI (/credentials-manager)

routers/backup.py

• GET /backup
• GET/POST/DELETE /api/backup/credentials
• GET /api/backup/health
• GET /api/backup/status
• GET /api/backup/history
• POST /api/backup/run

Backup & Security

• Dropbox token encrypted-at-rest in credentials (site='dropbox').
• Dropbox backup root encrypted opgeslagen in credentials (site='dropbox_backup_root').
• Retentie (snapshots to keep) encrypted opgeslagen in credentials (site='dropbox_backup_retention').
• Backup schedule (enabled + interval_hours) encrypted opgeslagen in credentials (site='dropbox_backup_schedule').
• Encryptie via NOVELA_MASTER_KEY (Fernet).

Implementatie:

• Versie-gebaseerde backups met deduplicatie:
  • bestandsobjecten in Dropbox: library_objects/{sha256_prefix}/{sha256}
  • snapshots in Dropbox: library_snapshots/snapshot-YYYYMMDD-HHMMSS.json
• Elke run maakt een nieuwe snapshot (versie) en uploadt alleen ontbrekende objecten.
• Retentie verwijdert oude snapshots boven de ingestelde limiet.
• Orphan object-prune verwijdert objecten die niet meer door retained snapshots worden gerefereerd.
• Lokale manifestcache (config/backup_manifest.json) versnelt changeddetectie.
• Database backup via pg_dump naar Dropbox postgres/.
• POST /api/backup/run start altijd als background task en geeft direct status terug.
• Scheduler draait in achtergrond (start_backup_scheduler) en triggert op interval als backup aanstaat.
• Concurrentierestrictie: slechts 1 backup tegelijk.
• Bij container restart/crash worden stale running logs automatisch gemarkeerd als interrupted/error.

Environment

stack/novela.env bevat nu minimaal:

• POSTGRES_DB
• POSTGRES_USER
• POSTGRES_PASSWORD
• NOVELA_MASTER_KEY
• CONFIG_DIR

Dropbox settings verlopen via webinterface op /backup.

UI Notes

• Library import accepteert: EPUB/PDF/CBR/CBZ.
• Home heeft dezelfde importmogelijkheden.
• Home heeft zoekfunctionaliteit.
• Home header/dropzone uitlijning gelijkgetrokken met Library (zoek rechtsboven, dropzone eronder).
• New view ondersteunt Grid en List mode.
• Bulk selectie + Remove from New werkt alleen in List mode.
• List mode heeft kolomfilter (aan/uit) met kolommen:
  • Publisher
  • Author
  • Series
  • Volume
  • Title
  • Has cover
  • Updated
  • Genres
  • Sub-genres
  • Tags
  • Status
• List mode ondersteunt multi-select met Shift+klik range-select op checkboxes.
• Grid mode toont geen selectie-checkboxes of bulkacties.
• Backup pagina ondersteunt:
  • handmatige run en dry-run
  • instellingen voor Dropbox root
  • retentie-aantal snapshots
  • geplande backup (aan/uit + interval in uren)
  • status + history overzicht

Known Conventions

• Verwijderen boek: bestand verwijderen, lege mappen prunen, daarna DELETE FROM library (cascade op child-tabellen).
• Cover strategie:
  • EPUB: cover uit bestand + cache
  • PDF/CBR: thumbnail via cover cache

Performance Notes

• Library-load geoptimaliseerd voor grote datasets:
  • list_library_json() gebruikt pre-aggregatie voor reading_sessions.
  • has_cached_cover komt direct uit SQL join i.p.v. losse volledige cache-fetch.
• Nieuwe migrations-indexen:
  • idx_library_sort_coalesce
  • idx_library_needs_review
  • idx_library_archived
  • idx_reading_sessions_filename_readat
  • idx_book_tags_filename_tag