t-youtube/CLAUDE.md

T YouTube — Text-Based YouTube Digest

PDD Workflow

This project follows PDD (Product Definition Document) development.

Always read these files before writing code:

• docs/PDD.md — product vision, goals, targets (the north star)
• docs/specs/active.md — current sprint spec (what we're building now)

Workflow:

1. PDD → Sprint Spec → Implementation → Validate ACs
2. Scope changes update the sprint spec first, code second
3. Never ship without ACs passing

Dev Commands

• Build: docker compose up -d --build
• Test: ./run_tests.sh
• Run locally: uvicorn backend.main:app --reload (backend) + npm run dev (frontend)
• Sync subscriptions: python run_sync.py

Architecture

• Frontend: Svelte 5 + Vite (frontend/)
• Backend: FastAPI + SQLite (backend/)
• Deployment: Docker container on NAS DS224+, port 8001
• Sync: run_sync.py fetches YouTube subscriptions + transcripts via yt-dlp
• Auth: Authelia SSO in front, cookie-based session
• Proxy: YouTube blocked from China — sync runs via VPS (Oracle Tokyo) or proxy

Key Files

• docs/architecture.md — full architecture reference
• Dockerfile — multi-stage build (node → python)
• docker-compose.yml — deployment config
• run_sync.py — subscription sync entry point
• config/cookies.txt — YouTube auth cookies (not committed)