ARRFLIX/docs/00-overview.md

# 00 — ARRFLIX Technical Overview

ARRFLIX is the operator's premium home-streaming project: AI-upscaled masters,
hand-curated metadata, and a Netflix-faithful viewing surface for a small
trusted set of users.

Under the hood, the stack is **Jellyfin 10.10.3 in Docker on nullstone**, sat
behind **Traefik** with **Let's Encrypt DNS-01 via Gandi** for TLS, name-served
internally by **Pi-hole**, and access-bounded to the LAN (`192.168.0.0/24`)
plus tagged tailnet nodes via a Traefik allowlist middleware. The Jellyfin web
UI is rebranded as ARRFLIX through a `web-overrides/` bind-mount, an SPA
runtime shim, and the **NeutralFin / Cineplex** CSS theme stack — none of the
default Jellyfin chrome, names, or logos are reachable by an unprivileged user.

---

## Architecture

| Layer            | Component                                                                                      |
|------------------|------------------------------------------------------------------------------------------------|
| Frontend         | Jellyfin web bundle, themed and rebranded as ARRFLIX (web-overrides + NeutralFin/Cineplex CSS) |
| Application      | `jellyfin/jellyfin:10.10.3` container on nullstone, sibling `jellyfin-dev` for theme work     |
| Reverse proxy    | Traefik with **file-provider** routing (docker-label routing flakes for this container)       |
| DNS              | Pi-hole internal A record: `arrflix.s8n.ru` → `192.168.0.100`          |
| TLS              | Let's Encrypt via DNS-01, Gandi LiveDNS provider                                              |
| Storage (media)  | RO bind-mount from host `/home/user/media/{movies,tv,…}` → container `/media`                 |
| Storage (state)  | Config + cache + metadata under host `/home/docker/jellyfin/`                                 |
| ACL              | Traefik `no-guest@file` middleware: LAN `192.168.0.0/24` + tailnet admin/infra tags only      |
| WAN exposure     | A record published; router port-forward gated — see `09-wan-exposure.md`                      |

A second container `jellyfin-dev` runs on `dev.arrflix.s8n.ru` as a behavioural
mirror of prod for theme and branding experiments — same media (read-only),
separate config and users, LAN-only.

---

## Read these in order

1. [`01-artwork-and-images.md`](01-artwork-and-images.md) — how artwork flows through Jellyfin and the curl recipes used to repair a botched first scan.
2. [`02-metadata-and-titles.md`](02-metadata-and-titles.md) — episode/title scraping, `RemoteSearch/Apply`, and the lock-the-series workflow.
3. [`03-subtitles.md`](03-subtitles.md) — subtitle resolution order, sidecar conventions, and the OpenSubtitles plugin setup.
4. [`04-theming-and-users.md`](04-theming-and-users.md) — active theme (Cineplex v1.0.6), server-side branding, multi-user UX, SyncPlay, revert path.
5. [`05-file-structure-rules.md`](05-file-structure-rules.md) — authoritative on-disk layout for Movies / TV / Anime / Music libraries.
6. [`06-per-library-themes.md`](06-per-library-themes.md) — research note on shimming per-library CSS scoping (Movies = Netflix, Anime = Crunchyroll, Music = Spotify).
7. [`07-pre-import-cleanup.md`](07-pre-import-cleanup.md) — normative ruleset for stripping junk from scene/group dumps before import.
8. [`08-filename-normalization.md`](08-filename-normalization.md) — canonical, group-tag-free renaming ruleset between "torrent dump" and the live tree.
9. [`09-wan-exposure.md`](09-wan-exposure.md) — the LAN-only → public-internet plan, server-side changes already applied, router TODOs, and rollback.
10. [`10-spa-runtime-shim.md`](10-spa-runtime-shim.md) — why static `<title>` patching loses to Jellyfin's SPA, and the runtime shim that wins it back.
11. [`11-neutralfin-audit.md`](11-neutralfin-audit.md) — read-only audit of the NeutralFin render gap vs the demo screenshots (no fixes applied).
12. [`12-dev-instance.md`](12-dev-instance.md) — `jellyfin-dev` sibling container: image pinning, mounts, and isolation guarantees.
13. [`13-optimization-audit.md`](13-optimization-audit.md) — read-only performance / capacity / reliability / ops-hygiene audit across REST, host, and container.
14. [`14-theme-audit.md`](14-theme-audit.md) — Cineplex theme audit and the detail-page left-band backdrop diagnosis (forward plan, not a fix).
15. [`15-force-english.md`](15-force-english.md) — root cause of the German Play button and the per-user `UICulture` pin that fixes it.
16. [`16-jellyfin-branding-leaks.md`](16-jellyfin-branding-leaks.md) — exhaustive inventory of every place "Jellyfin" or the teal triangle still leaks to a non-admin.
17. [`17-dev-mirror-and-settings-fix.md`](17-dev-mirror-and-settings-fix.md) — making dev a faithful prod mirror and fixing the non-admin Settings drawer leak (dev only).

---

## See also

- [`../README.md`](../README.md) — ARRFLIX brand-facing project page.
- [`../ADMIN-GUIDE.md`](../ADMIN-GUIDE.md) — operator runbook (day-to-day administration).
- [`../ROADMAP.md`](../ROADMAP.md) — what's next and what's known-broken.