Initial commit: Spectra YouTube Suggest Engine

README.md

@@ -0,0 +1,77 @@
+# Spectra — A YouTube Suggest Engine
+
+> Better YouTube recommendations: zero repeats, steerable topics & creators, recency-biased suggestions, and a preserved watch list.
+
+![Spectra UI](public/icon.svg)
+
+## 💡 Elevator Pitch
+YouTube does a terrible job of suggesting videos based on what it knows about you. Spectra creates a balanced series of suggested videos with **no repeats** over topics and creators you actually care about. Timing-wise, suggestions tend toward newer releases. You can click to add items to a **preserved Watch List** that persists across suggestion regenerations, and steer the algorithm with **Thumbs Up**, **Thumbs Down**, or **Big Nope** exclusions.
+
+---
+
+## ⚡ Core Features
+
+- **Strict Zero-Repeat Guarantee**: Spectra tracks every suggested video ID in persistent SQLite storage (`seen_videos`). Once a video has been suggested in any batch, it will never repeat unless you explicitly choose to reset seen history.
+- **Steerable Algorithm**:
+  - **👍 Thumbs Up**: Increases affinity weight for the creator (+affinity) and topic.
+  - **👎 Thumbs Down**: Reduces affinity weight for the creator and topic.
+  - **🚫 Big Nope**: Instantly removes video, blocks the creator/channel permanently, and excludes them from all future queries. (Includes 5-second undo toast).
+- **Timing Tendency (Recency Bias)**:
+  - Exponential decay multiplier prioritizing newer videos:
+    - ⚡ **Ultra Fresh**: Past 48 hours
+    - 📅 **Recent**: Past 30 days (default)
+    - 🌐 **Broad**: All-time high-affinity catalog
+- **Preserved Watch List**:
+  - One-click "Watch Later" saves videos into a persistent list that remains completely preserved even when suggestion batches are regenerated.
+  - Track watched vs unwatched status, launch embedded player or open directly in YouTube.
+- **Series of Topics & People**:
+  - Curated starter streams matching maker passions: Vintage Screenprint & Apparel, Specialty Espresso, ESP32 & E-Ink telemetry, Self-Hosted Homelabs, Alpine Skiing, Lateral Thinking, Vinyl Audio, and Maker Fast Builds.
+  - Add custom topics or YouTube creator handles on the fly.
+- **Embedded Theater Player**:
+  - Clean preview player using privacy-enhanced `youtube-nocookie.com`.
+  - Full feedback steering controls inside the player modal.
+
+---
+
+## 🏗️ Architecture & Tech Stack
+
+- **Runtime**: Node.js 22 LTS (Alpine)
+- **Database**: Native `node:sqlite` (zero npm C++ compilation overhead, blazing fast synchronous queries)
+- **YouTube Retrieval**: Live YouTube search scraper (`ytInitialData`), YouTube Channel RSS feeds (`/feeds/videos.xml?channel_id=...`), and offline seed catalog fallback
+- **Frontend**: Pure modern ES modules, CSS Grid, Glassmorphism, and responsive design (no heavy client bundlers needed)
+- **Deployment**: Docker Compose on `vloser` homelab, Traefik reverse proxy, Homepage dashboard integration
+
+---
+
+## 🧪 Automated Verification Suite
+
+Run the unit and integration test suite:
+
+```bash
+npm test
+```
+
+Verifies:
+1. Healthcheck endpoint and database readiness
+2. Starter topics and creators initialization
+3. Zero repeats across successive suggestion generation batches
+4. Watch list persistence across batch regenerations
+5. Algorithm steering: Thumbs Up / Thumbs Down topic weight updates
+6. Big Nope permanent channel and video blacklisting
+7. Seen history reset and telemetry reporting
+
+---
+
+## 🚀 Homelab Deployment (vloser.us)
+
+### 1. Repository
+Hosted on Gitea: `https://gitea.vloser.us/chrisf/spectra-a-youtube-suggest-engine`
+
+### 2. Traefik Dynamic Routing
+Configured in `/home/chrisf/docker/appdata/traefik3/rules/app-spectra-a-youtube-suggest-engine.yml`:
+- Public URL: `https://spectra-a-youtube-suggest-engine.vloser.us`
+- API Passthrough: `chain-no-auth`
+- Web UI: `chain-oauth` (Authentik SSO)
+
+### 3. Homepage Entry
+Configured in `/home/chrisf/docker/appdata/homepage/services.yaml` under Media & Discovery with custom SVG icon `/icons/spectra.svg`.