GigMaster

A dedicated operating system for gigging musicians — manage gigs, lineups, setlists, finances, and calendars in one place.

Tech Stack

• Framework: Next.js 15 (App Router) + React 19 + TypeScript
• Styling: Tailwind CSS + shadcn/ui
• Backend: Supabase (Postgres, Auth, Storage, Realtime)
• State: TanStack Query v5 (React Query)
• Testing: Vitest + React Testing Library + happy-dom
• Deployment: Vercel
• Future: Expo React Native mobile companion app

Getting Started

Prerequisites

• Node.js >= 24.0.0
• npm

Installation

1. Clone the repository

2. Install dependencies:

npm install

3. Set up environment variables:

   • Create .env.local with your Supabase credentials
   • See ENVIRONMENT_VARIABLES.md for all variables

4. Run the development server:

npm run dev

5. Open http://localhost:3000

Project Structure

/app
  /(app)                # Authenticated routes
    /gigs               # Main landing page — gig list, editor, and pack views
    /bands              # Band/act management
    /calendar           # Calendar view (month/week/3-day) with swipe navigation
    /dashboard          # Dashboard (grayed out, pending redesign)
    /history            # Past gigs archive
    /invitations        # Invitation acceptance
    /money              # Earnings & payouts
    /my-circle          # Musician contacts
    /settings           # Unified settings (Profile, General, Calendar, Account)
  /api                  # API routes (calendar, invitations, gigpack)
  /auth                 # Authentication pages

/components
  /bands                # Band editor
  /contacts             # Contact management dialogs
  /dashboard            # Dashboard widgets & gig cards
  /gigpack              # GigPack editor, layouts, setlists, sharing
  /gigs                 # Gig-specific dialogs
  /layout               # Top nav, sidebar, notifications, user menu
  /money                # Earnings & payouts tables
  /roles                # Role/lineup management
  /setlists             # Setlist editor, bulk add, learning status
  /shared               # Reusable components
  /ui                   # shadcn/ui primitives

/lib
  /api                  # Data access layer (21 modules, mobile-ready)
  /gigpack              # GigPack utilities, templates, i18n
  /integrations         # Google Calendar OAuth
  /providers            # React context (auth, query)
  /supabase             # Supabase clients (browser + server)
  /types                # TypeScript types (database, shared, gigpack)
  /utils                # Pure utility functions
  /emails               # Email templates

/tests                  # Vitest test suite
  /api                  # API function tests
  /components           # Component tests
  /fixtures             # Mock data
  /mocks                # Supabase mock factory

Available Scripts

Script	Description
npm run dev	Start dev server with Turbopack
npm run build	Production build
npm run start	Start production server
npm run lint	Run ESLint on app, lib, components
npm run check	Lint + TypeScript type check (no emit)
npm run typecheck	TypeScript check only
npm run test	Run tests in watch mode
npm run test:run	Run all tests once
npm run test:coverage	Run tests with coverage report

Features

Core

• Gig creation and management (standalone or within bands/projects)
• GigPack — shareable, mobile-optimized gig info pages
• Lineup management with role assignment and fee tracking
• Setlist editor with drag-and-drop, bulk import, and section support
• PDF setlist upload with inline preview
• Gig drafts with auto-save

People

• "My Circle" musician contacts with smart learning
• Unified search (contacts, system users, invite fallback)
• Email and WhatsApp invitations with magic links
• Invitation acceptance/decline with conflict detection

Calendar

• Google Calendar OAuth import with smart schedule parsing
• Automatic calendar invites sent to musicians on gig creation
• In-app calendar view (month/week/3-day) with swipe navigation and animations
• Conflict detection across GigMaster gigs and Google Calendar

Money

• Player earnings view with year/month filtering
• Manager payouts view with project filtering
• Payment status tracking (pending, paid, partial, overdue)
• Summary KPIs and one-click payment marking

Other

• Real-time notifications (Supabase Realtime)
• Dashboard with player/manager views, search, and filters
• Profile avatars (upload + Google OAuth auto-import)
• Dark mode
• Passwordless authentication (magic link, Google OAuth)
• Activity feed and gig history

Documentation

• CLAUDE.md — AI agent instructions and architecture overview
• ENVIRONMENT_VARIABLES.md — All environment variables
• BUILD_STEPS.md — Step-by-step build history
• CHANGELOG.md — Release history
• docs/CONTRIB.md — Contributing guide
• docs/RUNBOOK.md — Operations runbook
• docs/APP_OVERVIEW.md — Full app overview
• docs/TESTING.md — Testing guide
• docs/agent-protocols/ — Database safety protocols
• docs/build-process/ — Feature build documentation
• docs/future-enhancements/ — Roadmap and planned features

Current Status

See CHANGELOG.md for recent changes and BUILD_STEPS.md for full build history.

Not yet production-ready. Active development areas: UI redesign, calendar enhancements, payment tracking improvements, and mobile companion app. Test suite: 827 tests across 26 files (95% API coverage).