bert.hausmans
a92ddc48ec
Retires the "integer AI PK for join performance" exception documented in earlier migrations and SCHEMA.md §3.5.11 Rule 1. Every business and pivot table now uses ULID primary keys, per /dev-docs/ARCH-CONSOLIDATION-ADDENDUM-2026-04-24.md Q1. Tables migrated (WS-1 A-01 through A-11): - Pure pivots: organisation_user, event_user_roles, crowd_list_persons, event_person_activations - Model-backed: user_organisation_tags, person_section_preferences, mfa_backup_codes, mfa_email_codes, form_submission_section_statuses, form_values, form_value_options Migration pattern: one new migration per table (plus one combined for the form_values / form_value_options FK pair), timestamped today, dropping + recreating with the new ULID PK. Pre-launch — no backfill required. Original migrations remain in place; the new migrations apply in timestamp order for a clean schema history. Pivot model correction (addendum drift): The addendum's "no model required for pure pivots" reading did not account for Laravel's BelongsToMany::attach() — it cannot auto-generate a pivot ULID without a Pivot subclass. Minimal Pivot classes under app/Models/Pivots/ (OrganisationUser, EventUserRole, CrowdListPerson, EventPersonActivation) carry HasUlids so attach() works. The six belongsToMany relations (User.organisations / .events, Organisation.users, Event.users, CrowdList.persons, Person.crowdLists) now ->using(...) the appropriate Pivot class. DB::table()->insert() on event_person_activations in DevSeeder populates the ULID inline via Str::ulid(). FormValueObserver uses bulk FormValueOption::insert() which bypasses model events — ULIDs are now generated inline there too. Docs: - SCHEMA.md §3.5.11 Rule 1 rewritten to mandate ULID on pivots too, with legacy note citing the addendum. - All eleven table entries updated from "int AI PK" to "ULID PK" with addendum Q1 references. - form_values and form_submission_section_statuses prose blocks updated to drop the retired ARCH §4.4 / "high-volume pivot" rationale. - form_value_options.form_value_id column type corrected from "int FK" to "ULID FK". Tests: tests/Feature/Schema/UlidPrimaryKeyTest.php covers HasUlids trait presence, ULID shape + 26-char Crockford pattern, Route::bind resolution, distinct + sortable pivot ULIDs, attach() auto-generation on pure pivots, and the A-10/A-11 FK chain. 10 tests / 28 new assertions. Full suite: 977 passed (2662 assertions). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Crewli
Multi-tenant SaaS platform for event and festival operations: planning, people, accreditation, artist advancing, volunteer shifts, briefings, and show-day tooling (Mission Control). The backend is a JSON-only Laravel API; all user interfaces are Vue 3 single-page apps.
What Crewli covers
- Organisations & events — Multi-tenant data with organisation-scoped access; events move through a defined lifecycle (draft → published → registration → buildup → show day → teardown → closed).
- Festival structure — Sections, time slots, shifts, assignments, claiming/approval flows for volunteers and crew.
- People & crowds — Crowd types (crew, volunteers, artists, guests, press, partners, suppliers), persons, lists, and (planned) rich accreditation (items, zones, hand-out).
- Artists & advancing — Booking status, stages/timetable concepts, advance sections and token-based portal access for external artists.
- Communication — Briefings, campaigns, and operational messaging (see architecture doc for target modules).
- Portal (external users) — One portal app, two modes: login (Sanctum) for long-term users such as volunteers, and token access for per-event links (e.g. artists, suppliers).
Implementation is phased; the authoritative feature and schema list lives in the architecture and design references below.
Applications
| App | Path | Port | Role |
|---|---|---|---|
| Organizer | apps/app/ |
5174 | Main product for org and event staff: events, sections, shifts, people, artists, accreditation, briefings, reports. Includes Platform Admin section for super admins (/platform/*). |
| Portal | apps/portal/ |
5175 | External users: stripped layout; login- or token-based access. |
All apps talk to the API over CORS with Laravel Sanctum tokens.
Tech stack
| Layer | Technology |
|---|---|
| API | PHP 8.2+, Laravel 12, Sanctum, Spatie Permission (and Activity Log / Media Library where used) |
| Data | MySQL 8, Redis (cache/queues) |
| Frontends | Vue 3, TypeScript, Vite, Vuexy + Vuetify, Pinia, TanStack Query, VeeValidate + Zod |
| Local services | Docker Compose (MySQL, Redis, Mailpit) |
Rule of thumb: business tables use ULID primary keys; event-related data is scoped by organisation (global scopes + policies), not ad hoc where clauses in controllers.
Project structure
crewli/
├── api/ # Laravel 12 REST API (JSON only)
├── apps/
│ ├── app/ # Organizer SPA (primary UI + platform admin)
│ └── portal/ # External portal SPA
├── docker/ # Docker / Compose assets
├── docs/ # SETUP, API notes, schema notes
├── resources/
│ ├── design/ # Product source of truth (design docs, see table below)
│ └── vuexy-admin-*/ # Vuexy template reference (bundled kit)
├── .cursor/ # ARCHITECTURE.md, instructions.md, rules for AI/helpers
└── Makefile # Dev commands
Vuexy @core/ and @layouts/ in each app should stay untouched; customize via app config, navigation, and app-level components.
Quick start
# 1. Infrastructure
make services
# 2. API env, dependencies, database (see docs/SETUP.md)
cd api && cp .env.example .env && composer install && php artisan key:generate && php artisan migrate
# 3. Run API + the SPAs you need (separate terminals)
make api
make app
make portal
Detailed setup: docs/SETUP.md.
Development URLs
| Service | Development | Env / notes |
|---|---|---|
| API | http://localhost:8000/api/v1 | Base path /api/v1 |
| Organizer | http://localhost:5174 | FRONTEND_APP_URL |
| Portal | http://localhost:5175 | FRONTEND_PORTAL_URL |
| Mailpit | http://localhost:8025 | Local mail capture |
Production (crewli.app)
Domains: crewli.app is this product (API + organizer + portal SPAs, transactional email from the app, seeds, etc.). crewli.nl is reserved for a future public marketing site only — do not point this codebase's APP_URL, CORS, Sanctum, or app mail at crewli.nl.
Typical layout (configure the same values in api/.env — see api/.env.example):
| Service | URL | Env variable |
|---|---|---|
| API | https://api.crewli.app |
APP_URL |
| Organizer | https://crewli.app |
FRONTEND_APP_URL |
| Portal | https://portal.crewli.app |
FRONTEND_PORTAL_URL |
Frontends: set VITE_API_URL=https://api.crewli.app/api/v1 in each app's env for production builds. SANCTUM_STATEFUL_DOMAINS must list the hostnames only of the two SPAs (e.g. crewli.app,portal.crewli.app).
Makefile commands
make services # MySQL, Redis, Mailpit
make services-stop
make api # Laravel on :8000
make app # Organizer on :5174
make portal # Portal on :5175
make migrate
make fresh # migrate:fresh --seed
make db-shell
Documentation
| Resource | Contents |
|---|---|
| resources/design/ | Canonical product specs in Markdown. Referenced by .cursor and CLAUDE.md as source of truth for features and data model: design-document.md, dev-guide.md, start-guide.md. |
| .cursor/ARCHITECTURE.md | System diagram, apps, multi-tenancy, roles, event lifecycle, API route map, core schema overview (summarises resources/design when present) |
| .cursor/instructions.md | Quick reference, phased roadmap, module build order |
| .cursor/rules/ | Workspace, Laravel, Vue, testing conventions |
| docs/SETUP.md | Environment and local setup |
| docs/API.md | API notes (if maintained) |
| docs/SCHEMA.md | Schema notes (if maintained) |
Testing
cd api && php artisan test
Feature tests should cover happy paths plus 401 (unauthenticated), 403 (wrong organisation), and 422 (validation) where applicable.