🎵 Show Tracker

A modern Progressive Web App for groups to track concerts and manage RSVPs

Built with Next.js 16.1.0 and Supabase, featuring offline capabilities and native app-like experience.

📖 Table of Contents

Why Show Tracker?
Features
Quick Start
Prerequisites
Installation
Configuration
Usage
Deployment
API Reference
Tech Stack
Performance
Troubleshooting
FAQ
Contributing
License

🎯 Why Show Tracker?

Keep your concert group organized with:

Shared calendar - Everyone sees upcoming shows at a glance
Easy RSVPs - Know who's going where
New music tracking - Never miss releases from your favorite artists
Year-end stats - See your concert history and trends
Works offline - Install as an app, use anywhere

Built for music lovers who attend lots of shows and want to stay coordinated.

✨ Features

Core Functionality

🔐 Password-protected access - Simple shared password with show/hide toggle
📅 Show management - Add, edit, delete, and duplicate shows with intuitive time picker
✅ Smart RSVP system - Going/Maybe/Not Going for upcoming shows, I was there!/Clear for past shows
🔍 Advanced filtering - Filter by status and people with smart AND logic for complex queries
🔔 Toast notifications - Real-time feedback for all user actions
📋 Copy & share - One-click copy of show details for easy sharing

Music & Artists

🎶 Community Release Radar - Track new releases from any artist the community adds
🔍 Artist Search - Search and add artists to shows via Spotify API
🎵 Music integration - Spotify and Apple Music links for shows
🎯 Headliner tracking - Mark and track headliners in your year-end recap
🖼️ Artist images - Automatic artist photos from Spotify

My Profile & Cost Tracking

🎟️ My Profile - Personal dashboard at /my-profile with upcoming and past shows split by date
- Expandable cards showing poster, artists, attendees, and costs
- Year selector and direct link to Recap stories
💰 Cost Tracking - Log spending per show by category (Ticket, Transport, Food/Drink, Merch, Accommodation, Other)
📊 Spending Summary - Yearly breakdown with total spend, average per show, cost per artist, and category breakdown

Merch Tracking

👕 Merch collection - Track your concert merchandise at /my-profile/merch
- Add items with artist (Spotify search), category, images (Vercel Blob upload), price, quantity, and show link
- Edit and delete items with confirmation dialogs
- Multi-image support with navigation and counter on cards
🔍 Smart filters - Filter by category and artist with options populated from your collection
📊 Stats bar - Compact chip-based overview of total items, total spent, top artist, and top category

Badges

🏆 Achievement badges - Earn badges based on concert attendance and merch at /my-profile/badges
- 6 categories: Attendance, Streaks & Timing, Venues & Cities, Artists, Social, Merch
- Lifetime badges (earn once) and year-scoped badges (earn once per calendar year)
- Collapsible category sections with animated chevron indicators
- Badges auto-evaluated on every page load and on RSVP
👕 Merch badges - 13 lifetime and 2 year-scoped badges for collection milestones, signed/limited items, spending, and artist variety
🔒 Secret artist badges - Hidden badges revealed only when earned; tied to specific Spotify artists
- Secret merch badges — owning merch by a secret artist unlocks a companion badge
- Admin interface at /my-profile/badges/admin to create and manage secret badge definitions
🔄 Backfill support - Retroactively award badges to all existing users via /api/badges/backfill

Data & Analytics

📈 Year-end Recap - Comprehensive analytics with leaderboards, monthly trends, and personal stats at /my-profile/recap
📅 Calendar Export - Export shows to Google Calendar or download .ics files with custom duration
📊 Performance monitoring - Vercel Speed Insights integration
📸 Photo sharing - Google Photos links for past shows
🖼️ Poster uploads - Upload and display show posters with Vercel Blob storage
📖 Recap Stories - Instagram-style story experience for year-end stats with 5 themes and auto-advance

PWA & Performance

📱 Progressive Web App - Installable on mobile and desktop devices
🌐 Offline capabilities - Works without internet connection with graceful degradation
⚡ Instant updates - Optimistic UI updates for immediate feedback
🚀 High-performance - Optimized queries, indexes, and caching (80% fewer database calls)
📄 Infinite scroll - Efficient loading of past shows (20 per page)
🔄 Auto-recovery - Automatic chunk loading error recovery with cache clearing
🎨 Dark/light theme - System preference detection with manual toggle
🕐 Smart time picker - Realistic show times (3 PM to 2 AM)
📊 Intelligent sorting - Next show first (upcoming), newest first (past)

Integrations

🔔 Discord Integration - Optional Discord bot notifications for new and updated shows
🤖 Automated updates - GitHub Actions for release checking (4x daily)
⚙️ Auto-versioning - Automated cache busting on deployment

🚀 Quick Start

Want to try it first? Check out the live demo with mock data at: https://show-tracker.emontofazzal.com/

Want to run locally in 5 minutes? Follow these steps:

✅ Prerequisites

Before you begin, ensure you have:

✅ Node.js 18+ installed (Download)
✅ A Supabase account (Sign up free)
✅ A Spotify Developer account for Release Radar (Register)
⚠️ Optional: Vercel account for deployment
⚠️ Optional: Discord bot for notifications

Check your Node.js version:

node --version  # Should be 18.x or higher

📦 Installation

Clone the repository

git clone https://github.com/emonhoque/show-tracker
cd show-tracker

Install dependencies
```
npm install
```
Set up the database
- Create a new project in Supabase
- Go to SQL Editor and run the contents of database-complete-setup.sql
- This single file sets up tables, indexes, and optimized RLS policies
Configure environment variables

⚙️ Configuration

Create a .env.local file in the root directory with the following variables:

Variable	Required	Description	Example
`NEXT_PUBLIC_APP_PASSWORD`	✅	Shared access password for the app	`boston-shows-2024`
`SUPABASE_URL`	✅	Your Supabase project URL	`https://xxx.supabase.co`
`SUPABASE_SERVICE_ROLE_KEY`	✅	Supabase service role key	`eyJhbGc...`
`SPOTIFY_CLIENT_ID`	✅	Spotify API client ID	`abc123...`
`SPOTIFY_CLIENT_SECRET`	✅	Spotify API client secret	`xyz789...`
`TZ`	✅	Your timezone	`America/New_York`
`BLOB_READ_WRITE_TOKEN`	⚠️	Vercel Blob storage token	Auto-generated on Vercel
`DISCORD_BOT_API_URL`	❌	Discord webhook URL for notifications	`https://your-bot.com/api`
`CRON_SECRET`	❌	Secret for securing cron endpoints	Any random string

Minimal .env.local example:

NEXT_PUBLIC_APP_PASSWORD="your-chosen-password"
SUPABASE_URL=your_supabase_project_url
SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key
SPOTIFY_CLIENT_ID=your_spotify_client_id
SPOTIFY_CLIENT_SECRET=your_spotify_client_secret
TZ=America/New_York

🔧 Advanced Configuration (Click to expand)

Spotify API Setup

Go to Spotify Developer Dashboard
Create a new app
Copy Client ID and Client Secret to your .env.local
No redirect URI needed for this application

Discord Bot Integration

Set up a Discord bot with webhook capabilities
Configure the webhook endpoint URL
Add DISCORD_BOT_API_URL to your environment variables
Notifications are sent asynchronously and won't block operations

Vercel Blob Storage

Deploy to Vercel (or set up locally)
Enable Vercel Blob in your project settings
Token is auto-generated in production
For local development, use blob as placeholder

GitHub Actions (Automated Release Checks)

See GITHUB_ACTIONS_SETUP.md for detailed instructions.

Run the application
```
npm run dev
```
Visit http://localhost:3000

📖 Usage

Web App

Enter the shared password and your name
Add shows with the "Add" button
RSVP to upcoming shows
Past shows are automatically moved to the Past tab
Check the "Music" tab to see new music from tracked artists
Visit My Profile for your personal show dashboard, cost tracking, badges, and recap

PWA Installation

Mobile: Tap "Add to Home Screen" in your browser menu
Desktop: Look for the install button in your browser's address bar
Features: Once installed, scroll-to-top functionality, offline capabilities, and native app-like experience

Time Picker

Shows start at 3:00 PM and cycle through to 2:00 PM the next day
Covers realistic show times from afternoon to late night
No more scrolling through 3 AM times for evening shows!

Filtering System

The app includes a powerful filtering system to help you find specific shows:

Status Filters

All: Shows all upcoming shows (default)
Going: Shows where people have RSVP'd as "Going"
Maybe: Shows where people have RSVP'd as "Maybe"
Not Going: Shows where people have RSVP'd as "Not Going"

People Filters

Everyone: Shows all upcoming shows (default)
Individual People: Filter by specific attendees
Smart Logic: When multiple people are selected, shows only events where ALL selected people have the selected status

Filter Examples

Select "John" + "Taylor" + "Going" = Shows where both John AND Taylor are going
Select "Going" only = Shows where anyone is going
Select "Sarah" + "Maybe" = Shows where Sarah is maybe attending

Release Radar Feature

The app now includes a community-driven Release Radar tracking system:

Adding Artists

Go to the "Music" tab
Click "Add Artist" to search for artists via Spotify
Once added, the artist's releases will be visible to all users
Artists are shared across the entire community

Viewing Releases

New releases from all tracked artists appear in the Music tab
Shows releases from the last 13 weeks by default
Each release shows artist name, release type (album/single/EP), release date, and Spotify link
Releases are automatically fetched and updated

Automatic Updates

Set up a cron job to call /api/cron/check-releases periodically
This checks all tracked artists for new releases
New releases are automatically added to the database

Badges Feature

Earn achievement badges based on your concert attendance history:

Badge Categories

Attendance — milestone badges for total shows attended (lifetime) and yearly warrior
Streaks & Timing — back-to-back nights, triple threat (3 shows in a week), weekend warrior, monthly streak, night owl
Venues & Cities — venue explorer/collector, venue regular, city hopper, home turf
Artists — artist devotee/fan, diverse taste, headliner collector, local champion
Social — dynamic duo (co-attend 5+ shows with the same person)

Secret Badges

Hidden badges that appear only when unlocked
Tied to specific Spotify artists — attending a show featuring that artist unlocks the badge
Admins can manage secret badge definitions at /my-profile/badges/admin

Backfilling

Run the backfill script to award badges retroactively: node scripts/backfill-badges.mjs
Or call POST /api/badges/backfill directly

Year-end Recap Feature

The app includes comprehensive analytics and year-end recaps:

Personal Analytics

Show Statistics: Total shows attended, average per month, busiest month
Venue Tracking: Most visited venues and attendance patterns
Artist Diversity: Unique artists seen and most frequently seen artists
Time Patterns: Most common days of the week, back-to-back shows
Gap Analysis: Longest breaks between shows and attendance streaks

Group Analytics

Leaderboard: Ranked by total shows attended
Group Statistics: Total shows, average per person, most active users
Popular Venues: Most visited venues across the group
Artist Popularity: Most seen artists across all attendees
Monthly Trends: Visual charts showing attendance patterns over time

Features

Copy Summary: Generate and copy personalized year-end summaries
Year Selection: View recaps for any year from 2023 onwards
Interactive Charts: Monthly trend visualization with user comparisons
Comprehensive Stats: 20+ different statistics and insights

Calendar Export Feature

Export shows to your preferred calendar application:

Export Options

Google Calendar: Direct integration with Google Calendar
ICS Download: Download .ics files for any calendar app
Custom Duration: Set event duration from 1-6 hours
Timezone Support: Proper timezone handling (America/New_York)

Usage

Click the "Calendar" button on any show card
Choose between Google Calendar or .ics download
Set the event duration
Export with one click

Show Artists Management

Enhanced show creation with detailed artist information:

Features

Spotify Integration: Search and add artists directly from Spotify
Custom Artists: Add artists not found on Spotify
Role Assignment: Mark artists as Headliner or Support
Artist Images: Automatic artist photos from Spotify
Spotify Links: Direct links to artist pages

Usage

When adding/editing shows, use the "Add Artist" button
Search for artists by name
Select from Spotify results or add custom artists
Assign headliner/support roles
Reorder artists as needed

Discord Integration

Optional Discord bot notifications for show updates:

Features

New Show Notifications: Automatic alerts when shows are added
Show Updates: Notifications when show details change
Health Monitoring: Bot status checking and error handling
Async Delivery: Non-blocking notification system

Setup

Configure DISCORD_BOT_API_URL environment variable
Set up Discord bot with appropriate webhook endpoints
Notifications are sent asynchronously and won't block show creation

Additional Features

Copy Show Information

One-click Copy: Copy show details including title, date, venue, and links
Formatted Text: Clean, readable format for sharing
Mobile Optimized: Works seamlessly on all devices

Image Modal

Full-screen Viewing: Click posters for full-screen display
Zoom Capabilities: Enhanced image viewing experience
Mobile Friendly: Touch-optimized for mobile devices

🚀 Deployment

Deploy to Vercel (Recommended)

The easiest way to deploy is using Vercel:

Manual deployment:

Push your code to GitHub
Connect your repository to Vercel
Add your environment variables in Vercel's dashboard (see Configuration)
Deploy!

Note: Vercel automatically generates BLOB_READ_WRITE_TOKEN for Blob storage.

Other Platforms

This app can be deployed to any platform that supports Next.js 16:

Netlify - Configure build command: npm run build
Railway - Add Dockerfile or use Node.js template
Self-hosted - Run npm run build && npm start

Important: For platforms other than Vercel, you'll need to configure alternative file storage for poster uploads (currently uses Vercel Blob).

🛠️ Tech Stack

Core Framework

Next.js 16.1.0 - React framework with App Router
React 19.2.3 - UI library
TypeScript 5.x - Type safety

Styling & UI

Tailwind CSS 4.x - Utility-first CSS
Radix UI - Accessible component primitives
Lucide React - Icon library
Recharts - Data visualization

Backend & Data

Supabase - PostgreSQL database with RLS
Vercel Blob - File storage for posters
Spotify API - Music data

Utilities

date-fns - Date manipulation with timezone support
class-variance-authority - Component variants
clsx & tailwind-merge - Class management

Performance & Monitoring

Vercel Speed Insights - Performance tracking
Optimized Database - Strategic indexing and caching
Service Worker - Offline capabilities and caching

Development

ESLint - Code linting
React Testing Library - Component testing
GitHub Actions - Automated release checking

🗄️ Database Setup

The app uses a single, comprehensive database setup file (database-complete-setup.sql) that includes:

Tables

shows - Show information with JSONB artist data
rsvps - RSVP tracking with composite primary key
artists - Spotify artist data for release tracking
releases - Music releases from tracked artists
user_artists - Many-to-many relationship for community tracking
user_badges - Unlocked badges per user with scope_year for yearly variants; unique index on (user, badge, scope)
show_costs - Per-show cost entries by category per user
secret_badge_definitions - Admin-managed secret badge definitions tied to Spotify artist IDs

Key Features

Optimized indexes - For upcoming/past shows and RSVP joins
Row Level Security (RLS) - Streamlined policies for performance
JSONB fields - Flexible artist and metadata storage
Cascading deletes - Automatic cleanup of related data
Statistics - Pre-analyzed for optimal query planning

Schema Highlights

Shows table fields:

title, date_time, time_local, city, venue
ticket_url, spotify_url, apple_music_url, google_photos_url
poster_url, notes
show_artists (JSONB) - Flexible artist data with roles

PWA Features

This app is a fully functional Progressive Web App with:

Installable: Can be installed on mobile and desktop devices
Offline capable: Works without internet connection (with graceful degradation)
Native-like experience: Scroll-to-top, app-like navigation
No stale data: Always fetches fresh show/RSVP data when online
Cross-platform: Works on iOS, Android, Windows, macOS, Linux
Theme support: Dark and light mode with system preference detection
Responsive design: Optimized for all screen sizes
Pull-to-refresh: Native gesture support for refreshing content
Chunk error recovery: Automatic recovery from JavaScript chunk loading failures

⚡ Performance

Show Tracker is optimized for speed and efficiency:

Metrics

80% fewer database calls - From 11+ queries to just 2 per page load
2-5x faster queries - Optimized database structure and indexes
Instant RSVP updates - Optimistic UI, no waiting for server
< 150KB bundle - Efficient code splitting and lazy loading

Database Optimizations

✅ Combined queries - Shows and RSVPs in single calls (eliminates N+1)
✅ Strategic indexes - Optimized for upcoming/past shows and joins
✅ Streamlined RLS - Simplified policies for better performance
✅ Response caching - API responses cached (1-5 minutes)
✅ JSONB storage - Efficient artist data without extra joins

Frontend Optimizations

✅ Optimistic updates - Immediate UI feedback, background sync
✅ Infinite scroll - Paginated past shows (20 at a time)
✅ Skeleton loading - Smooth loading states, no layout shifts
✅ Smart caching - Service worker for static assets
✅ Code splitting - Route-based and component lazy loading
✅ Error recovery - Automatic chunk load error handling

PWA Performance

✅ Offline-first - Critical data cached for offline access
✅ Background sync - Updates when connection restored
✅ Install prompts - Native app-like installation
✅ Auto-updates - Service worker updates on new deployment

🔒 Security

✅ Input validation - All user inputs validated and sanitized
✅ Row Level Security - Supabase RLS policies protect data
✅ File upload security - Type and size validation (JPEG, PNG, WebP, max 10MB)
✅ XSS protection - HTML sanitization prevents script injection
✅ Environment variables - Sensitive data in .env.local (never committed)
✅ HTTPS only - Secure connections in production
✅ CRON_SECRET - Optional secret for securing automated endpoints

🔧 Troubleshooting

Service Worker Not Updating

Hard refresh: Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac)
Clear cache in browser settings
Check service worker update in DevTools → Application → Service Workers

Environment Variables Not Loading

Ensure .env.local is in root directory (not in subdirectories)
Restart dev server after adding/modifying variables: npm run dev
Check Vercel dashboard for production environment variables
Verify variable names match exactly (case-sensitive)

Database Connection Issues

Verify Supabase URL and service role key in .env.local
Check RLS policies are enabled (run database-complete-setup.sql)
Ensure Supabase project is active (not paused)
Check network connectivity and firewall settings

Spotify API Errors

Verify client ID and secret are correct
Check API credentials haven't expired
Ensure you're within Spotify API rate limits
Test credentials at Spotify Developer Dashboard

Build/Deployment Failures

Clear Next.js cache: rm -rf .next
Delete node_modules and reinstall: rm -rf node_modules && npm install
Check Node.js version: node --version (should be 18+)
Review build logs for specific errors

Poster Upload Issues

Ensure BLOB_READ_WRITE_TOKEN is set (auto-generated on Vercel)
Check file size (max 10MB) and type (JPEG, PNG, WebP only)
Verify Vercel Blob is enabled in project settings
Check browser console for specific error messages

❓ FAQ

Q: Can I use this for my own group? A: Absolutely! This project is MIT licensed and designed to be easily customizable for any group.

Q: Do I need a paid Supabase account? A: No, the free tier is sufficient for small to medium groups (up to 500MB database, 50MB file storage).

Q: Can I customize the password? A: Yes, set NEXT_PUBLIC_APP_PASSWORD in your environment variables to any password you choose.

Q: How do I update artist release data? A: Set up the GitHub Action (see GITHUB_ACTIONS_SETUP.md) or manually call /api/cron/check-releases.

Q: Can I deploy to platforms other than Vercel? A: Yes, but you'll need to configure alternative file storage (currently uses Vercel Blob). Consider AWS S3, Cloudinary, or Supabase Storage.

Q: How do I add more people to my group? A: Just share the password and URL! Anyone with the password can access and add their name.

Q: Can I have multiple groups/instances? A: Yes, deploy separate instances with different Supabase databases and passwords for each group.

Q: Is there a mobile app? A: The PWA can be installed on mobile devices as an app. Tap "Add to Home Screen" in your browser menu.

Q: How do I backup my data? A: Use Supabase's built-in backup features or export data via their dashboard (Projects → Database → Backups).

📚 API Reference

View API Endpoints

Shows API

Get Upcoming Shows

GET /api/shows/upcoming

Returns all upcoming shows with RSVPs.

Get Past Shows (Paginated)

GET /api/shows/past?page=1&limit=20

Returns past shows with pagination.

Create Show

POST /api/shows
Content-Type: application/json

{
  "title": "Show Title",
  "date_time": "2024-12-31T20:00:00Z",
  "time_local": "20:00",
  "venue": "Venue Name",
  "city": "Boston"
}

Duplicate Show

POST /api/shows/[id]/duplicate

Duplicates a show without RSVPs.

RSVP API

Create/Update RSVP

POST /api/rsvp
Content-Type: application/json

{
  "show_id": "uuid",
  "name": "User Name",
  "status": "going" | "maybe" | "not_going"
}

Artists API

Search Artists

GET /api/artists/search?query=artist+name

Searches Spotify for artists.

Get Releases

GET /api/releases?weeks=13

Gets recent releases from tracked artists.

Badges API

Get & Evaluate Badges

GET /api/badges?user=name

Fetches all badges for a user and evaluates/unlocks any newly earned badges. Returns lifetime badges, year-grouped badges, secret artist badges, and a summary with unlock counts.

Backfill Badges

POST /api/badges/backfill

Evaluates and unlocks badges for all existing users retroactively.

For complete API documentation, see the source code in app/api/.

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Quick start for contributors:

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

📄 License

MIT License - feel free to use this project for your own group!

See LICENSE for full details.

🙏 Acknowledgments

Built with amazing open-source technologies:

Next.js - React framework
Supabase - Database and backend
Radix UI - Accessible components
Tailwind CSS - Styling
Spotify API - Music data
Vercel - Hosting and storage

⬆ Back to Top

Made with ❤️ for music lovers everywhere

Name		Name	Last commit message	Last commit date
Latest commit History 235 Commits
.github/workflows		.github/workflows
app		app
components		components
lib		lib
public		public
scripts		scripts
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
GITHUB_ACTIONS_SETUP.md		GITHUB_ACTIONS_SETUP.md
LICENSE		LICENSE
README.md		README.md
components.json		components.json
database-complete-setup.sql		database-complete-setup.sql
env.example		env.example
eslint.config.mjs		eslint.config.mjs
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

🎵 Show Tracker

📖 Table of Contents

🎯 Why Show Tracker?

✨ Features

Core Functionality

Music & Artists

My Profile & Cost Tracking

Merch Tracking

Badges

Data & Analytics

PWA & Performance

Integrations

🚀 Quick Start

✅ Prerequisites

📦 Installation

⚙️ Configuration

Spotify API Setup

Discord Bot Integration

Vercel Blob Storage

GitHub Actions (Automated Release Checks)

📖 Usage

Web App

PWA Installation

Time Picker

Filtering System

Status Filters

People Filters

Filter Examples

Release Radar Feature

Adding Artists

Viewing Releases

Automatic Updates

Badges Feature

Badge Categories

Secret Badges

Backfilling

Year-end Recap Feature

Personal Analytics

Group Analytics

Features

Calendar Export Feature

Export Options

Usage

Show Artists Management

Features

Usage

Discord Integration

Features

Setup

Additional Features

Copy Show Information

Image Modal

🚀 Deployment

Deploy to Vercel (Recommended)

Other Platforms

🛠️ Tech Stack

Core Framework

Styling & UI

Backend & Data

Utilities

Performance & Monitoring

Development

🗄️ Database Setup

Tables

Key Features

Schema Highlights

PWA Features

⚡ Performance

Metrics

Database Optimizations

Frontend Optimizations

PWA Performance

🔒 Security

🔧 Troubleshooting

Service Worker Not Updating

Environment Variables Not Loading