bert.hausmans/band-management
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: align codebase with EventCrew domain and trim legacy band stack

Browse Source 
- Update API: events, users, policies, routes, resources, migrations
- Remove deprecated models/resources (customers, setlists, invitations, etc.)
- Refresh admin app and docs; remove apps/band

Made-with: Cursor
This commit is contained in:
bert.hausmans
2026-03-29 23:19:06 +02:00
parent 34e12e00b3
commit 1cb7674d52
1034 changed files with 7453 additions and 8743 deletions
Download Patch File Download Diff File Expand all files Collapse all files

344
.cursor/instructions.md
View File

@@ -1,28 +1,30 @@
# Band Management - Cursor AI Instructions
# EventCrew - Cursor AI Instructions
> This document provides AI assistants with comprehensive context about the project.
> Update this file as the project evolves.
> Multi-tenant SaaS platform for event- and festival management.
> Design Document: `/resources/design/EventCrew_Design_Document_v1.3.docx`
> Dev Guide: `/resources/design/EventCrew_Dev_Guide_v1.0.docx`
> Start Guide: `/resources/design/EventCrew_Start_Guide_v1.0.docx`
## Project Overview
**Name**: Band Management Platform
**Type**: Full-stack web application (API-first architecture)
**Name**: EventCrew
**Type**: Multi-tenant SaaS platform (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.
EventCrew is a multi-tenant SaaS platform for professional event and festival management. It supports the full operational cycle: artist booking and advancing, staff planning and volunteer management, accreditation, briefings, and real-time show-day operations (Mission Control). Built for a professional volunteer organisation, with SaaS expansion potential.
## 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 |
| API | Laravel 12 + Sanctum + Spatie Permission | `api/` | 8000 |
| Admin (Super Admin) | Vue 3 + Vuexy (full) | `apps/admin/` | 5173 |
| Organizer App (Main) | Vue 3 + Vuexy (full) | `apps/app/` | 5174 |
| Portal (External) | Vue 3 + Vuexy (stripped) | `apps/portal/` | 5175 |
| Database | MySQL 8 | Docker | 3306 |
| Cache / Queues | Redis | Docker | 6379 |
| Mail | Mailpit | Docker | 8025 |
## Documentation Structure
@@ -30,220 +32,118 @@ Band Management is a full-stack web application designed to streamline band oper
```
.cursor/
├── instructions.md # This file - overview and quick start
├── ARCHITECTURE.md # System architecture and data models
├── ARCHITECTURE.md # System architecture, schema, API routes
└── 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
├── 001_workspace.mdc # Project structure, conventions, multi-tenancy
├── 100_laravel.mdc # Laravel API patterns and templates
├── 101_vue.mdc # Vue + Vuexy patterns and templates
└── 200_testing.mdc # Testing strategies and templates
```
---
## Core Features
## Core Modules
### Authentication & Authorization
### Phase 1 - Foundation
- [ ] Multi-tenant architecture + Auth (Sanctum + Spatie)
- [ ] Users, Roles & Permissions (three-level model)
- [ ] Organisations CRUD + User Invitations
- [ ] Events CRUD with lifecycle status
- [ ] Crowd Types (org-level configuration)
- [ ] Festival Sections + Time Slots + Shifts
- [ ] Persons & Crowd Lists
- [ ] Accreditation Engine (categories, items, access zones)
- [ ] 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
### Phase 2 - Core Operations
- [ ] Briefings & Communication (template builder, queue-based sending)
- [ ] Staff & Crew Management (crowd pool, accreditation matrix)
- [ ] Volunteer Management + Portal (registration, shift claiming, approval flow)
- [ ] Form Builder (drag-drop, conditional logic, iframe embed)
- [ ] Artist Advancing + Portal (token-based access)
- [ ] Timetable & Stage management
- [ ] Show Day Mode
- [ ] Shift Swap & Waitlist
- [ ] Volunteer Profile + Festival Passport
- [ ] Communication Hub (email/SMS/WhatsApp via Zender, urgency levels)
### Member Management
### Phase 3 - Advancing & Show Day
- [ ] Guests & Hospitality
- [ ] Suppliers & Production (production requests, supplier portal)
- [ ] Mission Control (real-time check-in, artist handling, scanner management)
- [ ] Communication Campaigns (email + SMS batch)
- [ ] Allocation Sheet PDF (Browsershot)
- [ ] Scan infrastructure (hardware pairing)
- [ ] Reporting & Insights
- [ ] No-show automation
- [ ] Post-festival evaluation + retrospective
- [ ] 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
### Phase 4 - Differentiators
- [ ] Real-time WebSocket notifications (Echo + Pusher/Soketi)
- [ ] Cross-event crew pool with reliability score
- [ ] Global search (cmd+K)
- [ ] Crew PWA
- [ ] Public REST API + webhook system
- [ ] CO2/sustainability reporting
### 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
## Module Development Order (per module)
### RSVP System
Always follow this sequence:
- [ ] 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
1. Migration(s) - ULID PKs, composite indexes, constrained FKs
2. Eloquent Model - HasUlids, relations, scopes, OrganisationScope
3. Factory - realistic Dutch test data
4. Policy - authorization via Spatie roles
5. Form Request(s) - Store + Update validation
6. API Resource - computed fields, `whenLoaded()`, permission-dependent fields
7. Resource Controller - index/show/store/update/destroy
8. Routes in `api.php`
9. PHPUnit Feature Test - happy path (200/201) + unauthenticated (401) + wrong organisation (403) + validation (422)
10. Vue Composable (`useModuleName.ts`) - TanStack Query
11. Pinia Store (if cross-component state needed)
12. Vue Page Component
13. Vue Router entry
---
## Getting Started Prompts
### 1. Create Laravel API
### 1. Phase 1 Foundation (Backend)
```
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
Read CLAUDE.md. Then generate Phase 1 Foundation:
Follow the patterns in .cursor/rules/100_laravel.mdc
1. Migrations: Update users (add timezone, locale, deleted_at). Create organisations (ULID, name, slug, billing_status, settings JSON, deleted_at), organisation_user pivot, user_invitations, events (ULID, organisation_id, name, slug, start_date, end_date, timezone, status enum, deleted_at), event_user_roles pivot.
2. Models: User (update), Organisation, UserInvitation, Event. All with HasUlids, SoftDeletes where applicable, OrganisationScope on Event.
3. Spatie Permission: RoleSeeder with roles: super_admin, org_admin, org_member, event_manager, staff_coordinator, volunteer_coordinator.
4. Auth: LoginController, LogoutController, MeController (returns user + organisations + active event roles).
5. Organisations: Controller, Policy, Request, Resource.
6. Events: Controller nested under organisations, Policy, Request, Resource.
7. Feature tests per step. Run php artisan test after each step.
```
### 2. Create Database Migrations
### 2. Phase 1 Foundation (Frontend)
```
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.
Build auth flow in apps/app/:
1. stores/useAuthStore.ts - token storage, isAuthenticated, me() loading
2. pages/login.vue - use Vuexy login layout
3. Router guard - redirect to login if not authenticated
4. Replace Vuexy demo navigation with EventCrew structure
5. CASL permissions: connect to Spatie roles from auth/me response
```
### 3. Create Models with Relationships
### 3. Module Generation (example: Shifts)
```
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
Build the Shifts module following CLAUDE.md module order:
- Migration with ULID PK, festival_section_id, time_slot_id, location_id, slots_total, slots_open_for_claiming, status. Composite indexes.
- Model with HasUlids, SoftDeletes, relations, computed accessors (slots_filled, fill_rate).
- shift_assignments with denormalized time_slot_id, status machine (pending_approval > approved/rejected/cancelled/completed), UNIQUE(person_id, time_slot_id).
- Configurable auto-approve per shift.
- Queued notification jobs using ZenderService for WhatsApp.
- Feature tests covering 200/401/403/422.
```
---
@@ -256,25 +156,25 @@ Follow patterns in .cursor/rules/100_laravel.mdc and .cursor/rules/200_testing.m
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
5. Create Service class if complex business logic needed
6. Write PHPUnit Feature Test (200/401/403/422)
### Add a New Vue Page
1. Create page component in `src/pages/`
2. Add route in `src/router/index.ts`
2. Route added automatically by file-based routing (or add to router)
3. Add navigation item in `src/navigation/`
4. Create composable for API calls in `src/composables/`
5. Use Vuexy components for UI
5. Use Vuexy/Vuetify 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
1. Create migration with ULID PK, composite indexes
2. Create model with HasUlids, relations, OrganisationScope (if applicable)
3. Create factory with realistic Dutch test data
4. Create Policy, Form Request, Resource, Controller
5. Register routes in `api.php`
6. Write PHPUnit Feature Test
---
@@ -282,15 +182,15 @@ Follow patterns in .cursor/rules/100_laravel.mdc and .cursor/rules/200_testing.m
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
- Use PHP 8.2+ features (typed properties, enums, match, readonly)
- Use `declare(strict_types=1);`
- Use ULID primary keys via HasUlids trait
- Use Spatie laravel-permission for roles (never hardcode role strings)
- Scope all queries on `organisation_id` via Global Scope
- Use `<script setup lang="ts">` for Vue components
- Use TanStack Query for all API calls
- Use VeeValidate + Zod for form validation
- Use Vuetify/Vuexy components for UI (never custom CSS if Vuetify class exists)
---
@@ -306,13 +206,19 @@ make services-stop # Stop services
```bash
make api # Laravel on :8000
make admin # Admin SPA on :5173
make band # Band Portal on :5174
make customers # Customer Portal on :5175
make app # Organizer SPA on :5174
make portal # Portal SPA on :5175
```
### Database
```bash
make migrate # Run migrations
make fresh # Fresh migrate + seed
make db-shell # MySQL CLI
```
### Testing
```bash
cd api && php artisan test # All tests
cd api && php artisan test --filter=ShiftTest # Specific test
cd api && php artisan test --coverage # With coverage
```