Initial commit

docs/api.md

@@ -0,0 +1,73 @@
+# API
+
+All endpoints are served by the backend service and proxied by nginx under `/api`.
+
+## `GET /api/health`
+
+Returns:
+
+```json
+{ "ok": true }
+```
+
+## `GET /api/config`
+
+Returns public runtime configuration with secrets removed.
+
+## `GET /api/dashboard`
+
+Returns JSON state, drive usage, cached library files, cached extension breakdowns, and dry-run status. This endpoint does not scan the full media filesystem.
+
+## `POST /api/scan`
+
+Runs one scanner pass immediately. In dry-run mode this only records plans.
+
+## `POST /api/library/scan`
+
+Refreshes the cached library index. The scan only enters direct child folders of each media drive named `Movies`, `TV`, or `TV Shows`.
+
+## `GET /api/library`
+
+Returns the cached library summary and grouped movie/series collections for the Library page. Raw indexed file items stay server-side to keep routine dashboard refreshes small.
+
+## `GET /api/downloads`
+
+Returns current files under `/downloads` plus recent Sortarr plans or moves whose source was under `/downloads`.
+
+## `GET /api/releases`
+
+Returns missing/upcoming TV episodes derived from the cached library metadata, then appends any explicitly enabled public release providers.
+
+## `GET /api/media/probe`
+
+Runs `ffprobe` for a selected media file under configured media/download roots and returns detected video, audio, and subtitle streams.
+
+## `POST /api/media/tracks`
+
+Remuxes a selected media file to set an audio/subtitle stream as default or remove an embedded audio/subtitle stream. In dry-run mode it returns the ffmpeg command without modifying the file.
+
+## `GET /api/theme/custom.css`
+
+Serves host-editable custom CSS from `/config/custom-theme.css`.
+
+## `POST /api/settings`
+
+Updates runtime settings used by the current backend process. Settings can be sent as nested sections such as `{"app": {"dry_run": true}}` or as legacy top-level app keys.
+
+Supported sections include `app`, `paths`, `library`, `metadata`, `theme`, `drives`, and `release_providers`. Runtime settings are saved in `/data/state.json`; they are not written back into TOML.
+
+## `GET /api/tools/subtitles`
+
+Audits the cached library index for media files missing sidecar subtitles. Run `POST /api/library/scan` first for current subtitle data.
+
+## `GET /api/tools/transcoder`
+
+Builds a transcode queue for cached indexed media that is not already `.mp4`.
+
+## `POST /api/tools/transcoder/run-next`
+
+Runs the next queued ffmpeg transcode when `dry_run` is disabled. In dry-run mode it reports what would run.
+
+## `GET /api/tools/duplicates`
+
+Reports duplicate movie or series groups from the cached library index.

docs/configuration.md

@@ -0,0 +1,79 @@
+# Configuration
+
+Configuration is layered in this order:
+
+1. `backend/default-config/app.toml`
+2. `config/app.toml`
+3. `.env` variables passed into Docker Compose
+
+The backend deep-merges TOML files and then applies environment overrides for common deployment values.
+
+## Organizer Settings
+
+`[app]`
+
+- `dry_run`: plan without moving files.
+- `scan_interval_seconds`: worker polling interval.
+- `settle_seconds`: minimum file age before processing.
+- `stable_checks`: number of matching size/mtime observations required before a file is considered stable.
+- `incomplete_suffixes`: suffixes ignored while downloads are still active.
+- `media_extensions`: media files eligible for organizing.
+- `subtitle_extensions`: subtitle files visible to the scanner.
+- `extra_keywords`: filename terms ignored by the organizer, such as samples and trailers.
+- `library_scan_max_files`: maximum files indexed by the manual library scan.
+- `library_scan_timeout_seconds`: timeout for the manual library scan.
+- `cache_max_bytes`: maximum server-side cache size. Defaults to 20GB.
+
+`[library]`
+
+- `movie_folder`: destination folder template for movies.
+- `series_folder`: destination folder template for shows.
+- `movie_file`: Jellyfin-friendly movie filename template.
+- `episode_file`: Jellyfin-friendly episode filename template.
+- `collision`: `keep-both`, `skip`, or `replace`.
+- `duplicate`: reserved duplicate policy hook.
+- `permissions_mode`: final file mode after a move.
+- `directory_mode`: directory mode applied to created destination folders.
+
+## Drives
+
+Each `[[drives]]` entry has:
+
+- `id`: stable machine name.
+- `name`: dashboard display name.
+- `path`: mounted drive path inside the container.
+- `min_free_gb`: minimum free space required before the drive is eligible.
+
+Drive selection first checks whether the title already has a home under `Movies` or `Shows`. If not, it selects the eligible drive with the most free space.
+
+## Themes
+
+Bundled presets live in `web/src/themes.css`. The current presets are:
+
+`slate`, `midnight`, `graphite`, `nord`, `dracula`, `solar`, `forest`, `marine`, `ember`, `paper`.
+
+Runtime custom CSS is loaded from `/config/custom-theme.css` when `[theme].allow_custom_css` is enabled. Override any token:
+
+```css
+:root {
+  --accent: #5cc8ff;
+  --radius: 4px;
+}
+```
+
+## Release Providers
+
+`[[release_providers]]` supports pluggable free sources:
+
+- `type = "rss"` for RSS/Atom-style feeds.
+- `type = "json"` for simple public JSON endpoints.
+
+Provider code is isolated in `backend/sortarr/releases.py` so new adapters can be added without touching the UI.
+
+## TMDb Metadata
+
+Set `TMDB_API_KEY` or `TMDB_BEARER_TOKEN` in `.env` to enrich manual library scans with TMDb posters, overviews, release dates, and TV season episode data. Without credentials, Sortarr still groups local media and shows placeholder covers.
+
+## Server Cache
+
+Sortarr stores reusable TMDb and ffprobe results under `/data/cache`. The default cache cap is 20GB via `[app].cache_max_bytes`; older cache files are pruned when new cache entries are written.

docs/operations.md

@@ -0,0 +1,62 @@
+# Operations
+
+## Dry Run First
+
+Keep this in `.env` until destination paths look correct:
+
+```bash
+SORTARR_DRY_RUN=true
+```
+
+Then switch to:
+
+```bash
+SORTARR_DRY_RUN=false
+```
+
+Restart:
+
+```bash
+docker compose up -d
+```
+
+## Logs
+
+Backend logs are written to `/logs/sortarr.log` in the container and to the host path configured by `LOGS_PATH`.
+
+## Backups
+
+Back up:
+
+- `.env`
+- `config/`
+- `data/state.json`
+- `logs/` if you need historical audit trails
+
+Media files are not stored inside containers.
+
+## Updating
+
+Because all source is mounted or copied from this project, update by editing files and rebuilding:
+
+```bash
+docker compose up -d --build
+```
+
+## Transcoding
+
+The backend image includes `ffmpeg`. The dashboard Tools page can build a queue from the cached library index and run the next conversion. Keep dry-run enabled while checking output paths; actual transcoding only runs when `SORTARR_DRY_RUN=false` or dry-run is disabled from the runtime Settings page.
+
+## Track Editing
+
+The Library detail panel can inspect a selected file with `ffprobe` and remux embedded audio/subtitle streams to set defaults or remove tracks. Dry-run mode returns the planned `ffmpeg` command only. Disable dry-run only after confirming the command and keep media backups for any bulk edits.
+
+## Cache
+
+Reusable metadata and ffprobe results are cached under `/data/cache`. The default cap is 20GB and pruning removes oldest cache files first.
+
+## Recovery
+
+Sortarr moves through a temporary `.sorting` file before final placement. If a container stops mid-move, check the destination folder for `*.sorting` files and compare against `/downloads`.
+
+The app intentionally avoids deleting source folders and does not run destructive cleanup by default.