Initial commit: YouTube Studio Flow (backend, frontend, infrastructure, docs)

2026-08-11 12:27:44 +02:00
commit d5af006443
304 changed files with 74604 additions and 0 deletions
@@ -0,0 +1,31 @@
+# Quota Management
+
+## User Perspective
+The Quota History page (`/quota-history`) shows YouTube API quota usage over time. Each sync or playlist operation is logged. Entries are grouped by action (e.g. all API calls for a single video sync appear as one row) with the total quota cost shown.
+
+The display shows:
+- Video title + YouTube video ID
+- Action type (video_sync, playlist_add, etc.)
+- Units consumed
+- Time of operation
+- Expandable detail rows
+
+## Developer Perspective
+
+### Quota Budget
+YouTube imposes a **10,000 unit daily quota** that resets at midnight Pacific Time. Key costs:
+- `videos.update` — 50 units
+- `videos.list` — 1 unit
+- Playlist operations — varies
+
+### QuotaService
+- `canSpend(units: number)` — returns true if spending is allowed
+- `spend(units, operation, meta)` — logs usage to `QuotaLog`
+
+All YouTube API writes must call `canSpend()` before proceeding and `spend()` after. This is enforced in the `youtube-sync` processor.
+
+### QuotaLog Fields
+`datePt` stores the date in Pacific Time (for correct daily boundary). `actionId` groups related log entries from one user action (e.g. one video sync). The frontend clusters entries with the same `videoId` within 60 seconds for display.
+
+## Related
+- [[10 - Quota API]]