add download service

CLAUDE.md

@@ -38,10 +38,30 @@ uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
 **Video generation runs in ThreadPoolExecutor (max_workers=1) to avoid blocking the async event loop.**
 
 ### Frontend (Vue 3 + Vite)
-- `frontend/src/App.vue` - Single component handling all UI, form state, and API calls
+- `frontend/src/App.vue` - Main component handling quiz UI, form state, and API calls
+- `frontend/src/components/OpeningsDownloader.vue` - Anime openings downloader UI
+- `frontend/src/components/DownloadQueue.vue` - Download queue status component
 - Uses Vue 3 Composition API (`ref`, `reactive`, `computed`)
 - Vite proxies `/api`, `/videos`, `/download` to backend at `http://backend:8000`
 
+### Openings Downloader Module
+Located in `backend/app/openings_downloader/`:
+- `router.py` - FastAPI router with `/api/downloader/*` endpoints
+- `db_models.py` - SQLAlchemy models (Anime, AnimeTheme, DownloadTask)
+- `schemas.py` - Pydantic schemas for API requests/responses
+- `config.py` - Module settings with `DOWNLOADER_` env prefix
+- `services/shikimori.py` - Shikimori GraphQL API client (anime search)
+- `services/animethemes.py` - AnimeThemes API client (theme videos)
+- `services/downloader.py` - Download queue processing, WebM→MP3 conversion
+- `services/storage_tracker.py` - S3 storage usage tracking
+
+**Download flow:**
+1. Search anime via Shikimori API
+2. Fetch available themes from AnimeThemes API
+3. Add themes to download queue
+4. Background worker downloads WebM, converts to MP3 via FFmpeg, uploads to S3
+5. Creates Opening entity in main table for use in quiz generation
+
 ### Media Organization
 ```
 media/
@@ -68,6 +88,7 @@ output/videos/    # Generated MP4 files
 
 ## API Endpoints
 
+### Core Endpoints
 | Method | Endpoint | Purpose |
 |--------|----------|---------|
 | GET | `/health` | Health check with FFmpeg status |
@@ -77,10 +98,32 @@ output/videos/    # Generated MP4 files
 | DELETE | `/videos/{filename}` | Delete video |
 | GET | `/videos-list` | List generated videos |
 
+### Openings Downloader Endpoints (`/api/downloader`)
+| Method | Endpoint | Purpose |
+|--------|----------|---------|
+| GET | `/search` | Search anime via Shikimori (query, year, status params) |
+| GET | `/anime/{shikimori_id}` | Get anime details with available themes |
+| POST | `/queue/add` | Add specific themes to download queue |
+| POST | `/queue/add-all` | Add all themes from anime to queue |
+| GET | `/queue` | Get queue status (includes `worker_running` flag) |
+| DELETE | `/queue/{task_id}` | Cancel a queued task |
+| POST | `/queue/{task_id}/retry` | Retry a failed task |
+| DELETE | `/queue/clear` | Clear completed/failed tasks (`include_failed` param) |
+| GET | `/storage` | Get S3 storage usage stats |
+
 ## Environment Variables
 
+### Core Settings
 ```
 QUIZ_MEDIA_PATH=/app/media
 QUIZ_OUTPUT_PATH=/app/output/videos
 VITE_API_URL=http://backend:8000
 ```
+
+### Downloader Settings
+```
+DOWNLOADER_SHIKIMORI_USER_AGENT=AnimeQuiz/1.0
+DOWNLOADER_SHIKIMORI_TOKEN=              # Optional OAuth token for higher rate limits
+DOWNLOADER_S3_STORAGE_LIMIT_BYTES=107374182400  # 100 GB default
+DOWNLOADER_DOWNLOAD_TIMEOUT_SECONDS=300
+```