band-management/.cursor/instructions.md

Band Management - Cursor AI Instructions

This document provides AI assistants with comprehensive context about the project. Update this file as the project evolves.

Project Overview

Name: Band Management Platform
Type: Full-stack web application (API-first architecture)
Status: Development

Description

Band Management is a full-stack web application designed to streamline band operations by centralizing member coordination, gig management, music cataloging, and setlist planning. The platform serves as the single source of truth for all band-related activities.

Quick Reference

Component	Technology	Location	Port
API	Laravel 12 + Sanctum	api/	8000
Admin Dashboard	Vue 3 + Vuexy (full)	apps/admin/	5173
Band Portal	Vue 3 + Vuexy (starter)	apps/band/	5174
Customer Portal	Vue 3 + Vuexy (starter)	apps/customers/	5175
Database	MySQL 8.0	Docker	3306
Cache	Redis	Docker	6379
Mail	Mailpit	Docker	8025

Documentation Structure

.cursor/
├── instructions.md          # This file - overview and quick start
├── ARCHITECTURE.md          # System architecture and data models
└── rules/
    ├── 001_workspace.mdc    # Project structure and conventions
    ├── 100_laravel.mdc      # Laravel API patterns
    ├── 101_vue.mdc          # Vue + Vuexy patterns
    └── 200_testing.mdc      # Testing strategies

---

Core Features

Authentication & Authorization

• User registration with email verification
• User login/logout
• Password reset functionality
• Role-based access control (Admin, Booking Agent, Music Manager, Member)
• Permission middleware for route protection
• Session management

Member Management

• List all members with search and filter
• Create new member with role assignment
• Edit member profile and roles
• Deactivate/reactivate members
• Member profile page (instruments, bio, contact info)
• Avatar upload
• Member invitation via email
• Activity log per member

Events/Gigs Management

• List events with calendar and list view
• Create event with details (title, date, time, fee, notes)
• Edit/delete events
• Link event to location (from Location Manager)
• Link event to customer (from Customer Manager)
• Event status workflow (Draft → Pending → Confirmed → Completed → Cancelled)
• Invite members to event
• View RSVP responses per event
• Attach setlist to event
• Event detail page with all related info
• Duplicate event functionality

RSVP System

• Member receives event invitation notification
• RSVP response options (Available, Unavailable, Tentative)
• Add note/reason with RSVP
• Change RSVP before deadline
• RSVP deadline per event
• Overview of member availability per event
• Automatic reminders for pending RSVPs

Music Management

• List all music numbers with search and filter
• Add music number with metadata (title, artist, genre, duration)
• Edit/delete music numbers
• Additional fields: key, tempo (BPM), time signature
• File attachments (lyrics, chord sheets, audio files)
• Categorization with tags/genres
• Notes field for arrangements/cues

Setlist Manager

• List all setlists
• Create setlist with name and description
• Add music numbers to setlist from catalog
• Drag-and-drop reordering of songs
• Add set breaks/intermissions
• Auto-calculate total duration
• Clone existing setlist
• Link setlist to event(s)
• Delete/archive setlists

Location Manager

• List all locations with search
• Add location with details (name, address, capacity)
• Edit/delete locations
• Contact information (phone, email, contact person)
• Technical specifications (stage size, PA, backline, parking)
• Notes and special requirements

Customer Manager

• List all customers with search
• Add customer (company or individual)
• Edit/delete customers
• Contact details (name, email, phone, address)
• Customer type classification
• Notes and preferences
• View booking history per customer

Customer Portal

• Customer dashboard with booked events
• Submit booking requests
• Track request status
• View assigned setlists (if permitted)
• Profile settings

Band Member Portal

• Member dashboard with upcoming events
• Personal event calendar
• RSVP management interface
• View event details (location, time, setlist)
• Browse music catalog (view-only)
• View setlists assigned to events
• Profile settings
• Notification preferences

Admin Dashboard

• Dashboard with statistics/overview
• Quick actions panel
• Recent activity feed
• Upcoming events widget
• Pending RSVPs overview
• Booking requests management

Notifications

• Email notifications for event invitations
• RSVP reminder notifications
• Event update notifications
• In-app notification center
• Notification preferences per user

---

Getting Started Prompts

1. Create Laravel API

Create a Laravel 12 project in api/ with:
- Sanctum for API authentication
- MySQL configuration (host: 127.0.0.1, db: band_management, user: band_management, pass: secret)
- CORS configured for localhost:5173, localhost:5174, localhost:5175
- API response trait for consistent JSON responses
- Base controller with response helpers

Follow the patterns in .cursor/rules/100_laravel.mdc

2. Create Database Migrations

Create all migrations based on the schema in .cursor/ARCHITECTURE.md:
- Users, Customers, Locations
- Events, EventInvitations
- MusicNumbers, MusicAttachments
- Setlists, SetlistItems
- BookingRequests, Notifications, ActivityLogs

Use ULIDs for primary keys. Follow Laravel conventions.

3. Create Models with Relationships

Create Eloquent models for all tables with:
- HasUlids trait for ULID primary keys
- Proper relationships (belongsTo, hasMany, etc.)
- Fillable arrays
- Casts for enums, dates, and JSON fields
- Scopes for common queries

Follow patterns in .cursor/rules/100_laravel.mdc

4. Create Authentication System

Create auth system with:
- AuthController (login, logout, register, user, forgot-password, reset-password)
- Form requests for validation
- API resources for responses
- Sanctum token generation

Follow patterns in .cursor/rules/100_laravel.mdc

5. Integrate Vuexy with API

I've copied Vuexy Vue (typescript-version/full-version) to apps/admin/.

Update it to:
1. Create src/lib/api-client.ts for API calls with auth token handling
2. Install and configure @tanstack/vue-query
3. Replace Vuexy's fake auth with our Laravel API
4. Update navigation menu for our modules

Follow patterns in .cursor/rules/101_vue.mdc

6. Create Feature Modules

Create the Events module with:
- EventController with CRUD + invite/RSVP endpoints
- StoreEventRequest, UpdateEventRequest for validation
- EventResource, EventCollection for responses
- CreateEventAction, UpdateEventAction for business logic
- EventPolicy for authorization
- Feature tests

Follow patterns in .cursor/rules/100_laravel.mdc and .cursor/rules/200_testing.mdc

---

Common Tasks

Add a New API Endpoint

1. Create/update Controller in app/Http/Controllers/Api/V1/
2. Create Form Request in app/Http/Requests/Api/V1/
3. Create/update API Resource in app/Http/Resources/Api/V1/
4. Add route in routes/api.php
5. Create Action class if complex logic needed
6. Write feature test

Add a New Vue Page

1. Create page component in src/pages/
2. Add route in src/router/index.ts
3. Add navigation item in src/navigation/
4. Create composable for API calls in src/composables/
5. Use Vuexy components for UI

Add a New Database Table

1. Create migration: php artisan make:migration create_tablename_table
2. Create model with relationships
3. Create factory and seeder
4. Create controller, requests, resources
5. Add API routes
6. Write tests

---

Code Generation Preferences

When generating code, always:

• Use PHP 8.3 features (typed properties, enums, match, readonly)
• Use strict types: declare(strict_types=1);
• Use final classes for Actions, Form Requests, Resources
• Use ULIDs for all primary keys
• Follow PSR-12 coding standards
• Use TypeScript strict mode in Vue
• Use Vue 3 Composition API with <script setup lang="ts">
• Use TanStack Query for API calls
• Return consistent API response format

---

Environment Setup

Docker Services

make services       # Start MySQL, Redis, Mailpit
make services-stop  # Stop services

Development Servers

make api            # Laravel on :8000
make admin          # Admin SPA on :5173
make band           # Band Portal on :5174
make customers      # Customer Portal on :5175

Database

make migrate        # Run migrations
make fresh          # Fresh migrate + seed
make db-shell       # MySQL CLI