band-management/docs/SETUP.md

# Band Management - Setup Guide

This guide walks you through setting up the Band Management project from scratch.

## Cursor AI Configuration

The project includes comprehensive AI instructions:

```
.cursor/
├── instructions.md          # Quick start and common prompts
├── ARCHITECTURE.md          # System design and database schema
└── 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
```

**Read these files first!** They contain everything Cursor needs to generate code correctly.

## Prerequisites

Install these before starting:

### macOS (Homebrew)

```bash
# PHP 8.3
brew install php@8.3
brew link php@8.3

# Composer
brew install composer

# Node.js (via fnm)
brew install fnm
fnm install 20
fnm use 20

# pnpm
npm install -g pnpm

# Docker Desktop
# Download from: https://www.docker.com/products/docker-desktop/
```

### Verify Installation

```bash
php -v          # Should show 8.3.x
composer -V     # Should show 2.x
node -v         # Should show v20.x
pnpm -v         # Should show 8.x or 9.x
docker -v       # Should show Docker version
```

---

## Step 1: Start Docker Services

```bash
cd band-management
make services
```

This starts:
- **MySQL 8.0** on port 3306
- **Redis** on port 6379
- **Mailpit** on port 8025 (email testing UI)

---

## Step 2: Create Laravel API

Open the project in Cursor and use this prompt:

```
Create a new Laravel 12 project in the api/ folder.

Requirements:
- Use the command: composer create-project laravel/laravel api
- After creation, install Sanctum: composer require laravel/sanctum
- Configure for API-only (we don't need web routes)
- Set up CORS for localhost:5173, localhost:5174, localhost:5175
- Use MySQL with these credentials:
  - Host: 127.0.0.1
  - Database: band_management
  - Username: band_management  
  - Password: secret

Follow the conventions in .cursor/rules for code style.
```

### Manual Alternative

```bash
cd band-management
composer create-project laravel/laravel api
cd api
composer require laravel/sanctum
php artisan install:api
```

Then configure `api/.env`:
```env
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=band_management
DB_USERNAME=band_management
DB_PASSWORD=secret

SANCTUM_STATEFUL_DOMAINS=localhost:5173,localhost:5174,localhost:5175
SESSION_DOMAIN=localhost
```

---

## Step 3: Copy Vuexy Files

### Admin SPA (Full Version)

1. Extract your Vuexy download
2. Navigate to: `vuexy-vuejs-admin-template/typescript-version/full-version/`
3. Copy ALL contents to: `apps/admin/`

```bash
# Example (adjust path to your Vuexy download)
cp -r ~/Downloads/vuexy/typescript-version/full-version/* apps/admin/
```

### Band Portal (Starter Kit)

1. Navigate to: `vuexy-vuejs-admin-template/typescript-version/starter-kit/`
2. Copy ALL contents to: `apps/band/`

```bash
cp -r ~/Downloads/vuexy/typescript-version/starter-kit/* apps/band/
```

### Customer Portal (Starter Kit)

1. Copy starter-kit to: `apps/customers/`

```bash
cp -r ~/Downloads/vuexy/typescript-version/starter-kit/* apps/customers/
```

---

## Step 4: Configure SPAs

### Install Dependencies

```bash
cd apps/admin && pnpm install
cd ../band && pnpm install
cd ../customers && pnpm install
```

### Create Environment Files

**apps/admin/.env.local**
```env
VITE_API_URL=http://localhost:8000/api/v1
VITE_APP_NAME="Band Management Admin"
```

**apps/band/.env.local**
```env
VITE_API_URL=http://localhost:8000/api/v1
VITE_APP_NAME="Band Portal"
```

**apps/customers/.env.local**
```env
VITE_API_URL=http://localhost:8000/api/v1
VITE_APP_NAME="Customer Portal"
```

### Update Vite Ports

**apps/band/vite.config.ts** - Add port 5174:
```typescript
export default defineConfig({
  // ... existing config
  server: {
    port: 5174,
  },
})
```

**apps/customers/vite.config.ts** - Add port 5175:
```typescript
export default defineConfig({
  // ... existing config
  server: {
    port: 5175,
  },
})
```

---

## Step 5: Set Up API Client in SPAs

Use Cursor to add the API client. Prompt:

```
Add an API client to apps/admin/src/lib/api-client.ts that:
1. Uses axios with base URL from VITE_API_URL
2. Adds auth token from localStorage to requests
3. Handles 401 responses by redirecting to /login
4. Logs requests and responses in development

Follow the pattern in .cursor/rules
```

---

## Step 6: Create Database Schema

Use Cursor to create migrations. Prompt:

```
Create Laravel migrations for all tables defined in .cursor/rules:
- users (with roles and types)
- customers
- locations
- events
- event_invitations
- music_numbers
- music_attachments
- setlists
- setlist_items
- booking_requests
- notifications
- activity_logs

Use ULIDs for primary keys and follow Laravel conventions.
```

Then run:
```bash
cd api && php artisan migrate
```

---

## Step 7: Start Development

Open 4 terminal tabs:

```bash
# Tab 1: Services (already running)
make services

# Tab 2: Laravel API
make api

# Tab 3: Admin SPA
make admin

# Tab 4: Band Portal (optional)
make band
```

---

## Building Features

Use these Cursor prompts to build features:

### Authentication
```
Create the authentication system:
1. AuthController with login, logout, register, user endpoints
2. Form requests for validation
3. API resources for user responses
4. Update Vuexy's auth to use our API instead of fake backend
```

### Events Module
```
Create the Events module:
1. Event model with relationships (location, customer, setlist, invitations)
2. EventController with CRUD + invite and RSVP endpoints
3. Form requests and API resources
4. Event policy for authorization
```

### RSVP System
```
Create the RSVP system:
1. EventInvitation model
2. Endpoints for members to respond to invitations
3. Admin view of all RSVPs per event
4. Email notifications for new invitations
```

---

## Troubleshooting

### MySQL Connection Refused
```bash
# Check if Docker is running
docker ps

# Restart services
make services-stop
make services
```

### CORS Errors
Check `api/config/cors.php` allows your frontend origins.

### Vuexy TypeScript Errors
```bash
cd apps/admin
pnpm install
pnpm type-check
```

---

## Next Steps

1. ✅ Services running
2. ✅ Laravel API created
3. ✅ Vuexy copied to SPAs
4. ✅ Environment configured
5. 🔲 Build authentication
6. 🔲 Build events module
7. 🔲 Build members module
8. 🔲 Build music catalog
9. 🔲 Build setlist manager
10. 🔲 Build customer portal