Music Mindscape

Visualize your Spotify listening habits as an interactive force-directed mind map. Tracks are clustered into musical zones by audio features, with an optional AI mode powered by Gemini that re-clusters using music knowledge rather than raw numbers.

Features

• Mind Map — force-directed graph where nodes are tracks, positioned by audio feature similarity
• Node Entrance Animations — staggered fade-in when tracks first appear on the graph
• Musical Zones — tracks auto-grouped into clusters (Energy, Chill, Sad, Happy, Electronic, Acoustic, Romantic, Devotional, Party)
• Cluster Hover Highlight — hover a zone in the sidebar to spotlight it; all other nodes and links are dimmed on the graph
• AI Clustering — toggle Gemini 2.5 Flash to re-cluster tracks using musical context instead of Spotify's audio features
• AI Algorithm Insight — sidebar panel explaining step-by-step how Gemini re-clustered your tracks, with a live zone distribution chart
• Influence Simulator — search any Spotify artist, add them as a ghost node, and watch the graph connect them to your most similar tracks via dashed edges
• Influence Analysis Panel — collapsible bottom panel showing feature mini-bars, an auto-generated description, and top 3 connected tracks with cosine similarity scores for each active influence
• Save Image — export the current graph view as a PNG (dark background composited automatically)
• Spotify Sync — connect your Spotify account to load your top 20 tracks; re-sync at any time
• Playlist Export — export any cluster as a new Spotify playlist (authenticated users) or copy to clipboard (demo mode)
• Demo Mode — try everything without logging in using mock data
• Persistent State — ghost nodes, AI clustering results, and clustering mode are saved to localStorage and restored on revisit; AI cache is automatically invalidated if your track library changes after a re-sync

Tech Stack

• Frontend — React 18, TypeScript, Vite, Tailwind CSS, shadcn/ui, Framer Motion
• Graph — react-force-graph-2d, d3-force
• Backend — Supabase Edge Functions (Deno)
• Auth & Data — Spotify OAuth via Supabase, PostgreSQL for track storage
• AI — Google Gemini 2.5 Flash API

Getting Started

Prerequisites

• Node.js 18+
• A Spotify Developer app
• A Supabase project
• A Google AI Studio API key (for AI clustering)

Setup

1. Clone and install

   git clone <your-repo-url>
   cd music-mindscape
   npm install

2. Configure environment variables

   Copy .env.example to .env and fill in your keys:

   VITE_SUPABASE_URL=your_supabase_url
   VITE_SUPABASE_ANON_KEY=your_supabase_anon_key
   VITE_GEMINI_API_KEY=your_gemini_api_key

3. Deploy Supabase Edge Functions

   supabase functions deploy spotify-auth --no-verify-jwt
   supabase functions deploy spotify-callback --no-verify-jwt
   supabase functions deploy spotify-sync --no-verify-jwt
   supabase functions deploy spotify-create-playlist --no-verify-jwt
   supabase functions deploy spotify-artist-search --no-verify-jwt
   supabase functions deploy spotify-artist-tracks --no-verify-jwt

   Set the following secrets on your Supabase project:

   supabase secrets set SPOTIFY_CLIENT_ID=...
   supabase secrets set SPOTIFY_CLIENT_SECRET=...
   supabase secrets set SUPABASE_SERVICE_ROLE_KEY=...

4. Run locally

   npm run dev

Project Structure

src/
  pages/
    Index.tsx          # Landing page
    Dashboard.tsx      # Main mind map view
    SpotifyCallback.tsx
  components/
    MindMapGraph.tsx        # Force-directed graph (forwardRef, entrance animations, cluster highlight, save image)
    InfluencePanel.tsx      # Collapsible bottom panel for active ghost node analysis
    AlgorithmInsight.tsx    # Sidebar section explaining AI clustering steps + zone distribution
    SpiderChart.tsx         # Audio feature radar chart
    ClusteringTransparency.tsx
  lib/
    geminiClustering.ts  # Gemini AI clustering logic
    artistSearch.ts      # Spotify artist search + Gemini feature estimation
    spotifyData.ts       # Fetch tracks from Supabase
    similarity.ts        # Graph node types & similarity
  data/
    mockTracks.ts        # Demo data & cluster definitions
supabase/functions/
  spotify-auth/             # Initiates OAuth flow
  spotify-callback/         # Handles OAuth redirect
  spotify-sync/             # Fetches & stores top tracks
  spotify-create-playlist/  # Creates Spotify playlists
  spotify-artist-search/    # Searches Spotify artists for the Influence Simulator
  spotify-artist-tracks/    # Fetches top tracks for a given Spotify artist

Influence Simulator

The Influence Simulator lets you overlay any Spotify artist onto your personal mind map to see how they'd fit into your musical taste.

How it works

1. Search — type any artist name in the sidebar search box. When logged in, results come from the Spotify search API in real time (via the spotify-artist-search edge function) with a 400 ms debounce. In demo mode, a small set of preset artists is available instead.

2. Feature estimation — once you click an artist, Google Gemini 2.5 Flash estimates their audio features (danceability, energy, valence, acousticness, instrumentalness, tempo, speechiness) and assigns them to one of the 9 musical clusters. This is the same approach used by AI Clustering mode.

3. Ghost node — the artist appears on the graph as a semi-transparent dashed node. Cosine similarity is computed between the ghost's estimated features and every real track in your library.

4. Edges — dashed lines connect the ghost to its 4 most similar real tracks, showing which of your songs are closest in sonic character to that artist.

5. Influence Analysis Panel — a collapsible panel at the bottom of the graph shows a card for each active influence with: feature mini-bars (energy, danceability, mood, acousticness), an auto-generated influence description, and the top 3 most similar tracks with their cosine similarity scores.

6. Persistence — active influence artists and the AI clustering state are saved to localStorage, so your setup is restored automatically when you return to the page.

Notes

• Multiple ghost artists can be active at the same time.
• Ghost nodes are shown at 50% opacity and always render on top of the cluster they are assigned to.
• Removing a ghost from the "Active influences" list instantly removes it, its edges, and its Influence Analysis card from the graph.
• AI tracks (from Gemini clustering) are cached in localStorage per user. If you re-sync your Spotify library and the track list changes, the cached AI results are automatically invalidated and discarded.

Scripts

Command	Description
npm run dev	Start development server
npm run build	Production build
npm run preview	Preview production build
npm run test	Run tests
npm run lint	Lint source files