# YouTube Analytics — CLAUDE.md

PBS YouTube channel analytics pipeline: collect data from YouTube APIs, store in SQLite, visualize with Streamlit.

## Project Structure

```
main.py              — Click CLI entry point (init-db, seed, collect, dashboard)
src/
  auth.py            — OAuth2 authentication (YouTube Data API v3 + Analytics API v2)
  collector.py       — Data collection (videos, daily metrics, retention, traffic sources, channel stats)
  database.py        — SQLite schema (5 tables) and connection management (WAL mode, foreign keys)
  dashboard.py       — Streamlit dashboard (charts, tables, retention curves)
  seed.py            — Sample data generator (PBS plant-based cooking channel theme)
config/              — OAuth credentials (git-ignored, not committed)
data/                — SQLite database (git-ignored)
```

## Package Manager

Uses **uv** (not pip, not poetry). Python >=3.12.

```bash
uv sync                          # install deps from lockfile
uv add <pkg>                     # add a dependency
uv run python main.py <command>  # run within managed venv
```

## CLI Commands

```bash
uv run python main.py init-db-cmd   # create database tables
uv run python main.py seed          # populate with sample data
uv run python main.py collect       # pull real data (requires OAuth creds in config/)
uv run python main.py dashboard     # launch Streamlit dashboard
```

## Database

SQLite at `data/pbs_youtube.db` with five tables:
- `videos` — video metadata (id, title, published_at, duration, type)
- `video_daily_metrics` — per-video daily stats (views, watch time, CTR, engagement)
- `video_retention` — 100-point audience retention curves per video
- `video_traffic_sources` — traffic source breakdown per video per day
- `channel_daily_metrics` — channel-level daily summary

All inserts use `ON CONFLICT DO UPDATE` for idempotent runs.

## Authentication

Real YouTube API access requires:
1. Create OAuth credentials at https://console.cloud.google.com/apis/credentials
2. Download client secret JSON → save as `config/client_secret.json`
3. First run of `collect` opens browser for OAuth consent, stores token at `config/token.json`

For development/testing, use `seed` command instead — no credentials needed.

## Key Dependencies

click, streamlit, plotly, pandas, google-api-python-client, google-auth-oauthlib

## Conventions

- All data collection functions live in `collector.py`, one function per data type
- Dashboard uses Plotly for charts via `streamlit` + `plotly`
- Duration parsing handles ISO 8601 (PT1H2M3S format)
- Shorts classified as videos ≤60 seconds