Soleri
A personal dashboard that turns your Spotify listening history into clear visual insights.
Live at soleri.fyi
Features
- Listening Stats: Top tracks, artists, genre breakdown, and recent play counts, filterable by time range (last 4 weeks, last 6 months, all time)
- Listening Clock: Heatmap of when you listen across hours and days, with work focus vs. wind-down patterns
- Discovery Rate: Weekly breakdown of new tracks and artists explored versus replayed favourites
- Listening Marathons: Longest uninterrupted listening sessions ranked by duration
- Artist Obsession Phases: Detects periods where you listened to an artist heavily before moving on
- Billboard Comparison: Compare your top artists and average track popularity against the Billboard Hot 100
- Taste Match: Share your taste profile as a QR code and scan a friend's to compare listening habits
- Share Links: Publish a snapshot of your stats at a short
soleri.fyi/u/<id> link with a styled QR code. One link per user; links expire after 90 days
- Profile Customisation: Add an avatar, banner, bio, pronouns, location, links, a pinned track and an accent colour, and choose which stats are public. Edits appear live on your share link
Tech Stack
Frontend
- React.js
- TypeScript
- Tailwind CSS v4
- Recharts
- Framer Motion
- qr-code-styling
Backend
- Vercel Serverless Functions (region
syd1)
Database
- Supabase (Postgres + Storage, accessed via REST from the serverless functions only)
Third Party APIs
Getting Started
Prerequisites
Installation
git clone https://github.com/d4n1elliu/Soleri.git
cd Soleri
npm install
Environment Variables
Create a .env file in the project root:
# Server-side (used by the api/ serverless functions)
SPOTIFY_CLIENT_ID=your_client_id
SPOTIFY_CLIENT_SECRET=your_client_secret
REDIRECT_URI=http://localhost:5173
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key
# Client-side
VITE_SPOTIFY_CLIENT_ID=your_client_id
VITE_REDIRECT_URI=http://localhost:5173
# Canonical site origin used by the SEO prerenderer
VITE_SITE_URL=https://your-domain.com
In production these are set in the Vercel project settings. The Supabase keys are
never exposed to the browser; all database and storage access goes through api/.
Supabase Setup
Soleri uses two tables and one storage bucket. Row Level Security is enabled with no
policies, so only the service role key (used server-side) can read or write.
public.shares — id (text, PK), payload (jsonb), created_at. A daily pg_cron
job deletes rows older than 90 days.public.profiles — spotify_user_id (PK), display_name, bio, pronouns,
location, links (jsonb), pinned_track (jsonb), accent_color, avatar_url,
banner_url, show_genres, show_artists, show_tracks, created_at, updated_at.- Storage bucket
profile-images — public, 2 MB limit, JPEG/PNG/WebP. Files are stored
at avatars/<id> and banners/<id> and converted to WebP on upload.
Running Locally
# Terminal 1: serve the api/ functions on port 3000
vercel dev
# Terminal 2: run the Vite dev server (proxies /api to port 3000)
npm run dev
Then open http://localhost:5173 in your browser.
Building
npm run build
The build type-checks, bundles the app, then prerenders the public routes to
static HTML with per-page metadata, structured data, a sitemap and robots.txt.
API
All endpoints live in api/ and run as Vercel serverless functions. Write endpoints
verify the caller's Spotify token against /v1/me and act as that user only.
| Endpoint | Method | Purpose |
|---|
/api/share | POST | Create or reuse the caller's share link |
/api/share?id= | GET | Fetch a share snapshot for /u/:id |
/api/profile?spotifyId= | GET | Public profile (Cache-Control: no-store) |
/api/profile | PUT | Save profile fields (rate-limited, ~6/min) |
/api/profile | DELETE | Remove profile row and images |
/api/profile-image?kind=avatar|banner | POST | Upload an image (raw bytes, sniffed, ≤ 2 MB) |
Project Structure
Soleri/
├── api/ # Vercel serverless functions
│ ├── _lib/ # Shared helpers (Spotify fetch, Supabase REST, http utils)
│ ├── auth/ # Spotify OAuth endpoints
│ ├── spotify/ # Top tracks/artists and recently-played endpoints
│ ├── billboard.ts # Billboard Hot 100 data endpoint
│ ├── profile.ts # Profile read/update/delete
│ ├── profile-image.ts # Avatar and banner uploads
│ └── share.ts # Share link creation and lookup
├── public/ # Static assets (logo, OG image, demo video)
├── scripts/ # Build-time SEO prerenderer and route metadata
├── shared/
│ └── types/ # Types shared between api/ and src/
├── src/
│ ├── api/ # API client functions
│ ├── components/
│ │ ├── dashboard/ # Core dashboard widgets, share and scan modals
│ │ ├── insights/ # Listening insight components
│ │ ├── landing/ # Landing page
│ │ ├── legal/ # Terms of Service and Privacy Policy pages
│ │ ├── profile/ # Profile editor (/settings/profile)
│ │ ├── share/ # Public shared profile page (/u/:id)
│ │ └── ui/ # Shared UI primitives (modal, styled QR, avatar)
│ ├── hooks/ # React hooks
│ ├── lib/ # Pure utility and data-processing functions
│ ├── types/ # Frontend TypeScript types
│ └── entry-server.tsx # Build-time SSR entry for the prerenderer
└── vercel.json # Vercel deployment config (region, SPA rewrites)
Privacy
Spotify tokens are held in memory only and never persisted. Share links contain a
stats snapshot you choose to publish; profile data is public on your share link and
can be deleted at any time from the editor. See the Privacy Policy.
Contributing
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
Credits
Billboard Top 100 chart data is fetched directly from billboard.com.
Music data and artist metadata is provided by the Spotify Web API.
See NOTICE for full third-party license information.
License
Licensed under the MIT License.
