# Novela

Novela is a self-hosted web application for managing and reading a personal digital library.
It supports EPUB, PDF, and CBR/CBZ, with metadata editing, reading progress tracking, a web scraper/converter, and Dropbox backups.

## What Novela Provides

### Library
- Import and indexing for EPUB, PDF, CBR/CBZ
- Drag-and-drop import from library page or home page
- Cover extraction and caching (EPUB, PDF first page, CBR/CBZ first page); manual cover upload for EPUB
- Metadata editing: title, author, publisher, series, volume, tags, genres, sub-genres, star rating, publication status
- Publication statuses: Complete, Ongoing, Temporary Hold, Long-Term Hold
- Want-to-read flag and archived flag
- 1–5 star ratings (stored in EPUB OPF / CBZ ComicInfo.xml / DB)
- Download individual files

### Views and Navigation
- Home dashboard: continue reading, unread shorts/novels, read shorts/novels
- Library grid/list views with search (title, author, genre)
- Series view: grouped by series with volume order
- Duplicates view: groups books with matching title+author
- Incomplete view: books not marked Complete
- New view: recently imported books awaiting review; bulk "Remove from New" action
- Following page: track external URLs per author

### Bulk Import
- `/bulk-import` page: import multiple files at once with filename-based metadata parsing
- Free-text `%placeholder%` pattern editor (e.g. `%series% - %volume% - %title% - %year%`)
- Available placeholders: `%series%`, `%volume%`, `%title%`, `%year%`, `%month%`, `%day%`, `%author%`, `%publisher%`, `%ignore%`
- Colored chips: click to insert at cursor or drag onto the pattern input
- Shared metadata fields (author, publisher, status, genres, tags) override filename-parsed values
- Preview table with editable cells before importing
- Duplicate detection: checks title+author against existing library; duplicate rows highlighted, skipped by default
- Batched upload (5 files per request) with progress bar
- Batched bulk delete (20 files per request) with progress bar

### Reader
- EPUB reader: chapter navigation, configurable content width and text colour, bookmarks
- PDF reader: page-by-page rendering
- CBR/CBZ reader: page-by-page image rendering
- Reading progress saved per book (resume where you left off)
- Bookmarks with notes; listed in library sidebar section

### EPUB Tools
- EPUB editor (`/library/editor/{filename}`): edit chapter HTML in the browser
- Book Builder (`/builder`): create EPUB books from scratch with a WYSIWYG editor; publish directly to library
- Web Grabber (`/grabber`): scrape and convert web fiction to EPUB; site credentials management
- Converter (`/convert`): convert a URL to EPUB; duplicate detection before conversion

### Analytics
- Statistics dashboard: reads by month / day / hour, genre and publisher breakdowns, top books, read history

### Backups
- Dropbox backup: versioned snapshots with object-level deduplication and retention policy
- OAuth2 flow (preferred) or legacy access token
- Scheduled background backups (configurable interval)
- Live progress indicator during backup runs
- PostgreSQL dump included in each backup

### Sidebar
- Disk usage warning: amber ≥ 85% or < 2 GB free; red ≥ 95% or < 500 MB free

## Tech Stack
- FastAPI
- Jinja2 templates + vanilla JavaScript
- PostgreSQL 16
- Docker / Docker Compose style deployment

## Repository Layout
- `containers/novela/` — application code (routers, templates, static assets, migrations)
- `stack/` — deployment stack files and environment configuration
- `docs/` — technical status and changelog documentation
- `build-and-push.sh` — helper script for container build/push

## Quick Start (Development)
1. Configure environment values in `stack/novela.env`.
2. Start the stack using your preferred Docker workflow (Compose/Portainer stack).
3. Open the app and complete backup credential setup on `/backup` if needed.

## Key Environment Variables
- `POSTGRES_DB`
- `POSTGRES_USER`
- `POSTGRES_PASSWORD`
- `NOVELA_MASTER_KEY`
- `CONFIG_DIR`
- `LIBRARY_DIR` (optional override)

## Documentation
- Technical status: `docs/TECHNICAL.md`
- Develop changelog: `docs/changelog-develop.md`

## Disclaimer
This project was developed entirely with AI-assisted implementation workflows.
Use it at your own discretion and responsibility, and validate behavior, security, and data handling for your environment before production use.

## Status
This repository is actively evolving. The develop documentation reflects implemented behavior in the current codebase.