CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Diora is a Django-based internet radio player with user accounts, track history, Last.fm scrobbling, and PWA support. No build tools or bundlers — pure Django with vanilla JavaScript.

Development Commands

# Setup
pip install -r requirements.txt
cp .env.example .env          # then edit with your values
python manage.py migrate
python manage.py createsuperuser

# Run
python manage.py runserver

# Database
python manage.py makemigrations
python manage.py migrate

There is no test suite configured. Django's built-in test runner would be used if tests are added: python manage.py test.

Environment Variables (`.env`)

SECRET_KEY=change-me
DEBUG=True
AMAZON_AFFILIATE_TAG=diora-20
LASTFM_API_KEY=
LASTFM_API_SECRET=

Architecture

Two Django apps:

radio/ — Core player functionality

models.py: SavedStation, StationPlay, TrackHistory, FocusSession
icy.py: Parses ICY metadata from streaming HTTP responses (extracts track titles from radio streams)
lastfm.py: Last.fm API wrapper (scrobbling, track love/unlove)
views.py: Player page, SSE endpoint for real-time metadata, track recording, station CRUD

accounts/ — Authentication and user profiles

models.py: UserProfile (extends Django's User via signal; stores Last.fm session key, background image, scrobble preference)
views.py: Registration, login, Last.fm OAuth flow, background image upload

Frontend (static/js/)

app.js: All client-side logic — HTML5 Audio playback, SSE connection for live metadata, station management UI, focus timer
sw.js: Service worker for PWA installability
No build step — files are served directly

Templates (templates/)

base.html: Main layout with navbar
radio/player.html: Single-page player UI
accounts/: Auth and settings pages

Key Data Flows

ICY Metadata (real-time track info): Browser → GET /radio/sse/?url=<stream_url> → Django SSE view → icy.py opens stream → yields StreamingHttpResponse events → app.js EventSource updates UI

Last.fm Scrobbling: Track recorded via POST /radio/record/ → TrackHistory created → lastfm.py scrobbles if user has session key and opt-in enabled

Station Persistence: All station CRUD is JSON API (save/remove/favorite/notes) consumed by app.js — no page reloads

Static Files

WhiteNoise serves static files with CompressedManifestStaticFilesStorage (cache-busting hashes). Run python manage.py collectstatic before production deployment.

2.6 KiB Raw Blame History