SoundCluster maps songs into a 3D emotional space. The app searches track metadata through iTunes, fetches lyrics through LRCLIB when available, analyzes the song with Gemini, stores reusable analysis/share data in MongoDB Atlas, and renders the resulting 5D emotion vector with React Three Fiber.
- Frontend: React, TypeScript, Vite, React Three Fiber, Three.js, CSS Modules
- Backend: Express, TypeScript, Server-Sent Events
- LLM: Google
@google/genai - External APIs: iTunes Search API, LRCLIB API
- Storage: MongoDB Atlas
- Deployment: Vercel frontend, Render backend, MongoDB Atlas database
- Tests: TypeScript build +
node:test
- Live app: https://soundcluster-jhu.vercel.app/
- iTunes track search by title and optional artist
- LRCLIB lyrics lookup with fallback to title/artist-only analysis
- Gemini 5D emotion analysis
- MongoDB-backed analysis cache
- SSE progress events for analysis state
- R3F 3D music space rendering
- Axis on/off projection controls for five emotion dimensions
- Hover metadata popup with album image, title, artist, and emotion values
- Selected track HUD with emotion detail panel and remove action
- Nearest/farthest relation calculation and visual connection lines
nanoidshare URLs backed by MongoDB snapshot storage- Duplicate share snapshot detection through stable snapshot hashes
Frontend:
corepack pnpm devBackend:
corepack pnpm run server:build
corepack pnpm run server:startDefault URLs:
Frontend: http://localhost:5173
Backend: http://127.0.0.1:3001
Health: http://127.0.0.1:3001/api/health
Required backend environment variables:
GEMINI_API_KEY=
MONGODB_URI=
MONGODB_DB_NAME=
The frontend should call the deployed Render backend in production and the local backend during local development.
corepack pnpm run test
corepack pnpm run lint
corepack pnpm run server:build
corepack pnpm run buildmain: integrated stable branchdev: active integration branchfeature/*: task or milestone branches
Implementation work is tracked through GitHub issues and mirrored in docs/checklist.md.
MIT