# Flimmer — Arbeitsauftrag & Projektgedächtnis

> Diese Datei ist mein (Claude) Gedächtnis für dieses Projekt. Sie hält fest,
> **was gebaut werden soll**, **wie gearbeitet wird** und **wo ich gerade stehe**.
> Nach jeder Etappe wird der Abschnitt „Fortschritt" aktualisiert.

## Was ist Flimmer?

Selbst hostbarer Serien- & Film-Tracker (angelehnt an „Flimmerkiste"). Multi-User,
TMDB-Metadaten, Episodenfortschritt, eigene Universen mit mehreren Reihenfolgen,
Statistiken, Benachrichtigungen, REST-API, PWA. Oberflächensprache **Deutsch**.

## Verbindliche Entscheidungen (nicht ohne Rückfrage ändern)

| Bereich | Entscheidung | Begründung |
|---|---|---|
| Framework | **Next.js 15, App Router, TypeScript** | UI + REST-API + Cron in einem Deployment; Server Components halten Prisma serverseitig; `output: "standalone"` ergibt ein schlankes Docker-Image |
| DB | **PostgreSQL + Prisma** (Schema + Migrationen) | vorgegeben |
| Styling | **Tailwind CSS v4** (`@theme`, CSS-Variablen) | Design-Tokens sind in v4 nativ CSS-Variablen → Dark/Light/Themes bauen sauber darauf auf |
| Auth | **eigene Session-Schicht**: bcryptjs + opake Tokens in DB-Tabelle `Session`, httpOnly-Cookie; OIDC optional über `jose` + Discovery | DB-Sessions erlauben Sperren/Abmelden durch Admin; kein Beta-API-Risiko von next-auth v5; Credentials + OIDC parallel möglich |
| Passwort-Hash | **bcryptjs** (pure JS) | keine nativen Build-Abhängigkeiten im Docker-Image |
| Scheduler | in-process über `instrumentation.ts` (`ENABLE_SCHEDULER`) **plus** `/api/cron/*` mit `CRON_SECRET` | kein zweiter Container nötig, externe Scheduler trotzdem möglich |
| Bild-Cache | Dateien unter `DATA_DIR/images`, ausgeliefert über `/api/image` | kein TMDB-Abruf pro Seitenaufruf |
| Charts | handgeschriebene SVG-Komponenten | volle Kontrolle über Design-Tokens, keine Chart-Lib-Abhängigkeit |
| PWA | eigenes `sw.js` + `manifest.webmanifest` | keine zusätzliche Abhängigkeit |
| i18n | Dictionary `src/i18n/de.ts` + `t()`-Helper mit Punkt-Keys | weitere Sprachen ergänzbar |
| API | `/api/v1/**`, Bearer-API-Keys pro Nutzer, OpenAPI unter `/api/v1/openapi.json` | für spätere Mobile-App/Skripte |

## Branding (fix)

- Name **Flimmer**, Motiv: warmes Flimmern des Bildschirms
- Logo als **SVG**: abgerundetes Bildschirm-Rechteck, weiches warmes Glühen (Gradient),
  dezentes Play-Dreieck; Wortmarke in moderner, leicht gerundeter Sans
- Drei Varianten: **Icon**, **Icon + Wortmarke horizontal**, **monochrom**
- Favicon + PWA-Icons (inkl. **maskable**) aus dem Icon generiert
- Farbwelt: sehr dunkles Blauviolett/Anthrazit als Grund, Signatur = **Glow-Gradient
  Bernstein → Magenta**; Light Mode = dieselben Akzente auf warmgrauem Grund
- **Alle Kombinationen müssen WCAG AA erfüllen**
- UI: posterlastig, großzügige Karten mit sanftem Hover-Glow, runde Ecken, weiche
  Verläufe, ruhige Mikro-Animationen (Aufglimmen beim Abhaken)
- Logo + Name konsistent in Header, Login, E-Mail-/Notification-Templates, README

## Arbeitsregeln

- **Git-Repo** mit Remote `origin` → `https://git.wilde-server.de/florian.wilde/flimmer.git`, Branch `main`
- **Conventional Commits** (`feat:`, `fix:`, `chore:`, `docs:` …), Nachrichten deutsch
- **Kleine Commits** nach jedem abgeschlossenen Schritt — kein Riesen-Commit
- `.env` **niemals** committen (nur `.env.example`)
- **CHANGELOG.md** im Keep-a-Changelog-Format, SemVer ab 0.1.0; jede Etappe = neue Minor-Version
- Pro Version: **Git-Tag** `vX.Y.Z` + **Gitea-Release** (via Gitea-MCP, `gh`/`tea` sind nicht installiert),
  Titel = Version, Notes = Changelog-Abschnitt; zusätzlich `releases/vX.Y.Z.md` ablegen
- **DEVLOG.md**: pro Arbeitsphase Start-/Endzeit per `date`-Befehl (nicht schätzen) + Kurzbeschreibung;
  je Etappe Summe, am Ende Gesamtübersicht
- Versionsnummer aus `package.json` im UI anzeigen (Footer/Einstellungen)
- Umgebung: **Windows + PowerShell/Git-Bash**, VS Code. `curl` → `curl.exe`. Keine Desktop-Benachrichtigungen.

## Etappen

1. **Projektgerüst, Branding, Docker-Compose, DB-Schema, Auth** → v0.1.0
2. **TMDB-Anbindung**: Suche, Detailimport, Episodendaten, Bild-Cache → v0.2.0
3. **Kern-Tracking**: Bibliothek, Status, Episodenfortschritt, Watchlist → v0.3.0
4. **Universen** mit Reihenfolgen und Fortschritt → v0.4.0
5. **Dashboard, Kalender, Statistiken** → v0.5.0
6. **Benachrichtigungen, Sync-Job, Import/Export, REST-API, PWA-Feinschliff** → v0.6.0

## Ausdrücklich gewünscht (nicht vergessen!)

- [ ] **Bebilderte Anleitung** `docs/ANLEITUNG.md` mit **Screenshots** der laufenden App
      (Playwright gegen die geseedete Instanz, Bilder nach `docs/screenshots/`)
- [ ] Papierkorb (30 Tage) statt hartem Löschen + **Undo** für „als gesehen markiert"
- [ ] Seed-Skript mit Beispieldaten
- [ ] Backup-Hinweise (DB-Dump) in der README
- [ ] Healthcheck `/api/health`
- [ ] Öffentliche Profilseite (abschaltbar)
- [ ] Rewatch-Tracking (Durchläufe, bei Serien pro Durchlauf)
- [ ] Streaming-Verfügbarkeit (TMDB Watch Providers), Region konfigurierbar, Standard DE
- [ ] Import: Trakt.tv-Export + CSV; Export: CSV/JSON
- [ ] Benachrichtigungen: SMTP, ntfy, Gotify, generischer Webhook — pro Nutzer
- [ ] Streamingdienste mit konsistenten Akzentfarben/Badges im ganzen UI
- [ ] Optional per ENV: OIDC/SSO (Authelia, Keycloak)
- [ ] Registrierung durch Admin abschaltbar; erster Nutzer wird Admin

## Fortschritt

- Stand: **Etappe 1 läuft** (Start 2026-09-01 18:09)