Features & Technology Stack
Everything My Music offers, split by who can use it.
Feature Overview
Published — for listeners
- Track library with search by title, artist, or album
- Audio player with play, pause, seek, and volume controls
- Next / previous track navigation
- Shuffle button to randomize track order and sort by title, artist, album, genre, duration, created, updated, or rating
- Smooth background art cross-fade on track change
- Responsive layout — works on mobile and desktop
- Audio and cover art served via worker proxy route — works on any domain
- Live track data from Cloudflare R2 — updates on page load
- Static site export for fast, lightweight deployment
- Multi-theme color schemes with live switcher
- Star ratings on each track — click to rate, averages persisted in D1
- New/updated track badges — tracks added or modified since your last visit get NEW or UPDATED labels. No badges shown on first visit.
- Development issue log with tabs, search, severity badges, and commit-level resolutions
- URL updates when playing a track — shareable links with auto-play
Admin — for developers
- Local track drafts with add, edit, and delete — no server writes until publish
- Search and sort tracks by title, artist, album, genre, duration, created, or updated
- iTunes metadata (title, artist, album, genre) and cover art lookup directly from browser (CORS)
- One-click publish uploads all tracks + files to R2 in a single request
- Published diff shows added, updated, and removed tracks
- File upload validation (type, size, extension) on publish
- Cloudflare Access Zero Trust authentication for admin and admin-only API routes (
/api/publish,/api/me) - Authenticated user identity via
Cf-Access-Authenticated-User-Emailheader /api/meendpoint returning authenticated user info- Safe git operations with argument array (no shell injection)
npm run audit— dependency vulnerability checker- Security lint rules via
eslint-plugin-security - Worker-side R2 proxy for audio and cover art serving
- R2 bucket binding for server-side data operations
- Cloudflare R2 external storage for audio and cover art
- Reset ratings per track via checkboxes and bulk delete API
- On-demand browser-based e2e tests via Puppeteer — 17 tests covering page load, search, sort, shuffle, audio player, ratings, and track link validation
Technology Stack
| Layer | Technology | Purpose |
|---|---|---|
| Framework | Next.js 16 | App Router, worker deployment |
| UI Library | React 19 | Client components, hooks, context |
| Language | TypeScript | Type safety across the entire stack |
| Styling | Tailwind CSS v4 | Utility-first styling with @theme |
| Testing | Vitest + RTL | Unit tests with React Testing Library |
| Linting | ESLint | eslint-config-next, core-web-vitals, security plugin |
| Data | JSON file | Admin writes to R2 on publish. Published site reads from R2 |
| Audio detection | HTMLAudioElement API | Client-side duration from metadata |
| External API | iTunes Search API | Metadata and cover art lookup |
| Theming | CSS custom properties | 7 color schemes with runtime switching |
| AI tooling | opencode | Conversational development workflow |
| Object storage | Cloudflare R2 | Audio/cover storage with bucket binding and worker-side proxy |
| Authentication | Cloudflare Access | Edge JWT validation + user identity headers for admin and API routes |
Architecture
Public Site — Data Flow
Admin & API — Internal Flow
