---
title: Introduction
description: What Mood Music does, how it's built, and who this documentation is for.
url: https://mood-music-docs.thally.app/
---

# Introduction

What Mood Music does, how it's built, and who this documentation is for.

Mood Music turns a one-line description of your mood or your day into real Spotify playlists. Type something like "rainy Lagos afternoon, need focus" and get back a ranked list of matching playlists, pulled straight from Spotify's own catalog. Try it live at [moodmusic.chikeozulumba.com](https://moodmusic.chikeozulumba.com).

Logging in with Spotify adds one thing on top of the core mood search: a saved history of your past searches, with the vibe Claude read into each one and the playlists that came back.

## Who this is for

This documentation is for developers who want to:

- Run their own copy of Mood Music, locally or deployed
- Understand how a small LLM-driven search feature can sit in front of a third-party API without needing a traditional database
- See a working example of Cloudflare Workers, KV, and Durable Objects used together in a single small project

If you just want to use the app, you don't need any of this — go to the live site and type a mood.

## How it's built

Mood Music is a pnpm monorepo with two apps that deploy as a single Cloudflare Worker:

- `apps/web` — a Vite + React + TanStack Router single-page app
- `apps/api` — a Hono API running on Cloudflare Workers

In production, the Worker serves the built SPA and runs the API from the same domain, so there's no CORS to think about and cookie-based sessions just work.

## How a mood search works

1. You type a mood or a description of your day.
2. The API sends it to Claude, which returns a short "vibe" interpretation and a handful of search phrases.
3. Each phrase searches Spotify's catalog via the Client Credentials flow — no user login required for this part — paginated and merged round-robin across phrases, so the strongest match from every phrase surfaces before any phrase's second-tier results.
4. The combined result is cached in Workers KV, keyed by a hash of the normalized mood text, for 24 hours — so the same mood never re-hits Claude or Spotify twice.

If you're logged in with Spotify, the mood text, Claude's vibe summary, and the playlists returned are also saved to your own history, stored in a Durable Object addressed by your Spotify user ID.

## Where to go next

- **[Quickstart](/quickstart)** — get it running locally and pull your first playlist recommendation.
- **[Deploying to Cloudflare](/deploying)** — ship it to a real Worker, on your own domain or the default workers.dev URL.
- **[Spotify login: setup and troubleshooting](/guides/spotify-oauth)** — add login, and fix the redirect URI errors that come with deploying to a new domain.
- **[Troubleshooting](/troubleshooting)** — an index of common failures across setup, login, and usage, each linking to the full fix.