True Random Songs

True Random Songs is a music-discovery app for people who want to hear something outside their usual listening loop. It generates a fresh playlist from a large music dataset, renders Spotify or YouTube embeds, and can save selected tracks to a Spotify playlist after the user authorizes the app.

The production URL configured in the frontend and backend is https://random-songs.lordpatil.com.

Architecture

• frontend/ — Next.js 16 App Router interface with Tailwind CSS and DaisyUI.
• backend/ — FastAPI service using DuckDB over local Parquet metadata.
• frontend/content/blog-posts.json — source of truth for static, indexable discovery guides.

Run locally

Frontend

cd frontend
pnpm install
pnpm dev

The UI runs at http://localhost:3000. Its API target defaults to http://localhost:8002.

Backend

cd backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python main.py

The backend runs on port 8002. It expects data/tracks_lite.parquet and data/albums_lite.parquet; these datasets are deliberately ignored by Git.

Environment variables

Variable	Used by	Purpose
NEXT_PUBLIC_API_URL	frontend	Base URL for the FastAPI service. Defaults to http://localhost:8002.
NEXT_PUBLIC_SPOTIFY_CLIENT_ID	frontend	Public client ID for the Spotify PKCE authorization flow.
ALLOWED_ORIGINS	backend	Comma-separated CORS allowlist for the API.

Never commit credentials, tokens, local datasets, or production environment files.

SEO and content maintenance

The SEO blog is statically rendered at /blog and /blog/[slug]. Each post has its own title, description, canonical URL, Open Graph card, structured article data, accessible image alt text, and a prominent route back to the generator.

• frontend/app/robots.ts publishes a crawl policy and the sitemap location.
• frontend/app/sitemap.ts lists the generator, guide index, and post URLs, including article-image URLs.
• docs/seo-keyword-plan.md records the initial intent research and the validation plan.

After deployment, submit https://random-songs.lordpatil.com/sitemap.xml in the matching Google Search Console property and inspect the three guide URLs. A sitemap is a discovery signal, not a guarantee that Google will index a page; use Search Console impressions, queries, and indexing reports before expanding the content set.

The guide covers are original typographic and diagrammatic artwork made for this repository on 2026-08-03. Their SVG source files live in frontend/artwork/blog-covers/, while WebP exports provide broadly compatible page and social-preview images. They contain no Spotify marks, album art, lyrics, or artist likenesses. Keep future editorial content equally original, useful, and clearly separate from any Spotify endorsement.

Checks

cd frontend
pnpm test
pnpm lint
pnpm build

pnpm test validates the post corpus, images, canonical/sitemap wiring, and crawl controls. The build statically renders the public guide pages.