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