band-management/.cursor/instructions.md

EventCrew - Cursor AI Instructions

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: EventCrew Type: Multi-tenant SaaS platform (API-first architecture) Status: Development

Description

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 + 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

.cursor/
├── instructions.md          # This file - overview and quick start
├── ARCHITECTURE.md          # System architecture, schema, API routes
└── rules/
    ├── 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 Modules

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)

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)

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

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

---

Module Development Order (per module)

Always follow this sequence:

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. Phase 1 Foundation (Backend)

Read CLAUDE.md. Then generate Phase 1 Foundation:

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. Phase 1 Foundation (Frontend)

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. Module Generation (example: Shifts)

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.

---

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 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. 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/Vuetify components for UI

Add a New Database Table

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

---

Code Generation Preferences

When generating code, always:

• 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)

---

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 app            # Organizer SPA on :5174
make portal         # Portal SPA on :5175

Database

make migrate        # Run migrations
make fresh          # Fresh migrate + seed

Testing

cd api && php artisan test                          # All tests
cd api && php artisan test --filter=ShiftTest       # Specific test
cd api && php artisan test --coverage               # With coverage