From 3f3c5ffaa176ec816c9c1e628325abc02408b9dc Mon Sep 17 00:00:00 2001
From: Viktor Barzin <viktorbarzin@meta.com>
Date: Mon, 23 Feb 2026 21:53:51 +0000
Subject: [PATCH] docs: initialize project

---
 .planning/PROJECT.md | 66 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)
 create mode 100644 .planning/PROJECT.md

diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md
new file mode 100644
index 00000000..e155b359
--- /dev/null
+++ b/.planning/PROJECT.md
@@ -0,0 +1,66 @@
+# F1 Streaming Service
+
+## What This Is
+
+A private F1 streaming aggregation service that auto-scrapes specific streaming sites, extracts actual video source URLs through custom per-site extractors (bypassing obfuscation, CSRF, and redirect chains), and proxies the streams through a unified Svelte web app. Deployed on the existing K8s cluster.
+
+## Core Value
+
+When an F1 session is live, users open one URL and immediately see working streams — no hunting for links across sketchy sites.
+
+## Requirements
+
+### Validated
+
+- ✓ Kubernetes cluster with ingress, NFS storage, monitoring — existing
+- ✓ Cloudflare DNS and TLS — existing
+- ✓ CI/CD pipeline (Woodpecker) — existing
+- ✓ Terraform/Terragrunt deployment pattern — existing
+
+### Active
+
+- [ ] Auto-scrape configured streaming sites for live F1 stream links
+- [ ] Custom per-site extractors to bypass obfuscation (CSRF tokens, JS rendering, redirect chains) and extract final video source URLs
+- [ ] Stream health checks — verify extracted streams are actually live and working before displaying
+- [ ] Stream proxying/relay through the service for unified playback
+- [ ] Auto-pull F1 race schedule from official data (Ergast/OpenF1 API)
+- [ ] Cover all F1 sessions: FP1-3, Qualifying, Sprint, Race, pre/post shows, press conferences
+- [ ] Svelte web app with schedule view, stream picker, and embedded video player
+- [ ] Deploy as a service on the existing K8s cluster
+
+### Out of Scope
+
+- User authentication — security by obscurity (private URL, not publicly discoverable)
+- Community features (chat, comments, voting) — just streams
+- DVR/recording — live viewing only
+- Mobile app — web-only
+- Official F1TV integration — unofficial re-streams only
+
+## Context
+
+- Stream sites have anti-scraping protections: CSRF tokens, JavaScript-rendered pages, obfuscated video URLs, redirect chains
+- Custom extractors per site are preferred over headless browser for efficiency and reliability
+- User will provide the specific sites to scrape — not a discovery/search problem
+- F1 calendar data available via Ergast API (ergast.com/mrd/) and OpenF1 API
+- HLS (m3u8) is the most common stream format on these sites
+- Existing infra supports Svelte apps (user's preferred frontend framework)
+
+## Constraints
+
+- **Frontend**: Svelte — user preference for all new web apps
+- **Deployment**: K8s cluster via Terraform/Terragrunt stack pattern
+- **Storage**: NFS at 10.0.10.15 for any persistent data
+- **No auth**: Rely on non-discoverable URL, no Authentik integration needed
+- **Extractors**: Custom per-site logic, no headless browser dependency
+
+## Key Decisions
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| Custom per-site extractors over headless browser | More efficient, reliable, and lighter on resources | — Pending |
+| No authentication | Private community, security by obscurity sufficient | — Pending |
+| Proxy streams through service | Unified player experience, hides source from end users | — Pending |
+| All sessions coverage | Users want full weekend + extras, not just race day | — Pending |
+
+---
+*Last updated: 2026-02-23 after initialization*