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)

# 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

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

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

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

Then configure api/.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/

# 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/

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

Customer Portal (Starter Kit)

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

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

---

Step 4: Configure SPAs

Install Dependencies

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

Create Environment Files

apps/admin/.env.local

VITE_API_URL=http://localhost:8000/api/v1
VITE_APP_NAME="Band Management Admin"

apps/band/.env.local

VITE_API_URL=http://localhost:8000/api/v1
VITE_APP_NAME="Band Portal"

apps/customers/.env.local

VITE_API_URL=http://localhost:8000/api/v1
VITE_APP_NAME="Customer Portal"

Update Vite Ports

apps/band/vite.config.ts - Add port 5174:

export default defineConfig({
  // ... existing config
  server: {
    port: 5174,
  },
})

apps/customers/vite.config.ts - Add port 5175:

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:

cd api && php artisan migrate

---

Step 7: Start Development

Open 4 terminal tabs:

# 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

# 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

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