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
```bash
make services       # Start MySQL, Redis, Mailpit
make services-stop  # Stop services
```

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

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