bert.hausmans
1cb7674d52
- 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
225 lines
8.4 KiB
Markdown
225 lines
8.4 KiB
Markdown
# 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
|
|
```bash
|
|
make services # Start MySQL, Redis, Mailpit
|
|
make services-stop # Stop services
|
|
```
|
|
|
|
### Development Servers
|
|
```bash
|
|
make api # Laravel on :8000
|
|
make admin # Admin SPA on :5173
|
|
make app # Organizer SPA on :5174
|
|
make portal # Portal SPA on :5175
|
|
```
|
|
|
|
### Database
|
|
```bash
|
|
make migrate # Run migrations
|
|
make fresh # Fresh migrate + seed
|
|
```
|
|
|
|
### 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
|
|
```
|