# NtR SoundCloud Fetcher — Full Implementation

## Task Description

Designed and implemented a Python service that polls NicktheRat's SoundCloud likes, builds weekly playlists aligned to the Wednesday 22:00 ET show schedule, and serves them via a JSON API for an IRC bot.

## Changes Made

### Design Phase
- Brainstormed requirements through 6 clarifying questions
- Evaluated 3 architectural approaches, selected single-process daemon
- Produced design doc covering architecture, data model, API, poller logic
- Produced 13-task TDD implementation plan

### Implementation (42 tests, all passing, lint clean)

| Module | File | Purpose |
|--------|------|---------|
| Config | `src/ntr_fetcher/config.py` | Pydantic settings with `NTR_` env prefix |
| Week | `src/ntr_fetcher/week.py` | DST-aware Wednesday 22:00 ET boundary computation |
| Models | `src/ntr_fetcher/models.py` | Track, Show, ShowTrack dataclasses |
| Database | `src/ntr_fetcher/db.py` | SQLite schema, CRUD, track sync with unlike removal |
| SoundCloud | `src/ntr_fetcher/soundcloud.py` | client_id extraction, user resolution, likes fetching |
| Poller | `src/ntr_fetcher/poller.py` | Hourly polling with supervised restart |
| API | `src/ntr_fetcher/api.py` | FastAPI routes for playlist, shows, admin, health |
| Main | `src/ntr_fetcher/main.py` | Entry point wiring everything together |

### Key Design Decisions
- Tracks removed when Nick unlikes them (positions re-compact)
- Cursor-seeking for efficient SoundCloud API pagination
- Automatic client_id rotation on 401
- Supervisor restarts poller on failure without affecting API

## Follow-up Items

- **Incremental fetching**: Currently fetches full week every poll; could optimize to stop at known tracks
- **Retry/backoff for non-401 errors**: 429, 5xx, timeouts not yet handled with retries
- **`full` parameter**: Accepted but currently equivalent to normal poll (no incremental to differentiate from)
- **`soundcloud_url` in admin add track**: Removed from API; only `track_id` supported