68 lines
2.6 KiB
Markdown
68 lines
2.6 KiB
Markdown
# 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
|