docs: expand EventCrew README with stack and structure
Sync auto-imports and typed-router generated declarations from Vue tooling. Made-with: Cursor
This commit is contained in:
172
README.md
172
README.md
@@ -1,73 +1,137 @@
|
||||
# Event Crew
|
||||
# EventCrew
|
||||
|
||||
Full-stack event crew operations management platform.
|
||||
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.
|
||||
|
||||
## Tech Stack
|
||||
---
|
||||
|
||||
## What EventCrew 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 |
|
||||
|-----|------|------|------|
|
||||
| **Admin** | `apps/admin/` | 5173 | Platform **super admin**: organisations, billing-style flags, global settings. Full Vuexy shell. |
|
||||
| **Organizer** | `apps/app/` | 5174 | Main product for **org and event staff**: events, sections, shifts, people, artists, accreditation, briefings, reports, etc. |
|
||||
| **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 |
|
||||
|-------|------------|
|
||||
| Backend | Laravel 12 + PHP 8.3 + Sanctum |
|
||||
| Database | MySQL 8.0 |
|
||||
| Frontend | Vue 3 + TypeScript + Vuexy |
|
||||
| Local Dev | Native PHP/Node + Docker |
|
||||
| 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) |
|
||||
|
||||
## Quick Start
|
||||
**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.
|
||||
|
||||
```bash
|
||||
# 1. Start Docker services
|
||||
make services
|
||||
---
|
||||
|
||||
# 2. Open in Cursor and start building!
|
||||
```
|
||||
|
||||
See [docs/SETUP.md](docs/SETUP.md) for detailed instructions.
|
||||
|
||||
## Project Structure
|
||||
## Project structure
|
||||
|
||||
```
|
||||
event-crew/
|
||||
├── api/ # Laravel 12 API
|
||||
├── api/ # Laravel 12 REST API (JSON only)
|
||||
├── apps/
|
||||
│ ├── admin/ # Admin Dashboard
|
||||
│ ├── band/ # Band Member Portal
|
||||
│ └── customers/ # Customer Portal
|
||||
├── docker/ # Docker configs
|
||||
├── docs/ # Documentation
|
||||
├── resources/ # Vuexy template source (reference)
|
||||
├── .cursor/rules # Cursor AI instructions
|
||||
└── Makefile # Development commands
|
||||
│ ├── admin/ # Super Admin SPA
|
||||
│ ├── app/ # Organizer SPA (primary UI)
|
||||
│ └── 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
|
||||
```
|
||||
|
||||
## Frontend Apps (Vuexy v10.11.1)
|
||||
Vuexy **`@core/`** and **`@layouts/`** in each app should stay untouched; customize via app config, navigation, and app-level components.
|
||||
|
||||
All frontend apps are built with **Vue 3 + TypeScript** using the [Vuexy Admin Template](https://pixinvent.com/vuexy-vuejs-admin-dashboard-template/).
|
||||
---
|
||||
|
||||
| App | Template | Description |
|
||||
|-----|----------|-------------|
|
||||
| **Admin** | TypeScript Full Version | Complete admin dashboard with all Vuexy features |
|
||||
| **Band Portal** | TypeScript Starter Kit | Lightweight portal for band members |
|
||||
| **Customer Portal** | TypeScript Starter Kit | Lightweight portal for customers |
|
||||
|
||||
**Template source:** `resources/vuexy-admin-v10.11.1/vue-version/typescript-version/`
|
||||
|
||||
> **Note:** The `@core/` and `@layouts/` folders should not be modified directly. Customize through `themeConfig.ts` and override styles in `assets/styles/`.
|
||||
|
||||
## URLs
|
||||
|
||||
| App | Development | Production |
|
||||
|-----|-------------|------------|
|
||||
| API | http://localhost:8000/api/v1 | https://api.eventcrew.nl |
|
||||
| Admin | http://localhost:5173 | https://admin.eventcrew.nl |
|
||||
| Band Portal | http://localhost:5174 | https://band.eventcrew.nl |
|
||||
| Customer Portal | http://localhost:5175 | https://customers.eventcrew.nl |
|
||||
|
||||
## Development Commands
|
||||
## Quick start
|
||||
|
||||
```bash
|
||||
make services # Start MySQL, Redis, Mailpit
|
||||
make services-stop # Stop Docker services
|
||||
make api # Start Laravel API
|
||||
make admin # Start Admin SPA
|
||||
make band # Start Band Portal
|
||||
make customers # Start Customer Portal
|
||||
# 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 admin # optional
|
||||
make app # optional
|
||||
make portal # optional
|
||||
```
|
||||
|
||||
Detailed setup: **[docs/SETUP.md](docs/SETUP.md)**.
|
||||
|
||||
---
|
||||
|
||||
## Development URLs
|
||||
|
||||
| Service | Development | Env / notes |
|
||||
|---------|-------------|-------------|
|
||||
| API | http://localhost:8000/api/v1 | Base path `/api/v1` |
|
||||
| Admin | http://localhost:5173 | `FRONTEND_ADMIN_URL` in Laravel CORS |
|
||||
| Organizer | http://localhost:5174 | `FRONTEND_APP_URL` |
|
||||
| Portal | http://localhost:5175 | `FRONTEND_PORTAL_URL` |
|
||||
| Mailpit | http://localhost:8025 | Local mail capture |
|
||||
|
||||
Production hostnames are placeholders until you deploy; configure `config/cors.php` via `.env`.
|
||||
|
||||
---
|
||||
|
||||
## Makefile commands
|
||||
|
||||
```bash
|
||||
make services # MySQL, Redis, Mailpit
|
||||
make services-stop
|
||||
make api # Laravel on :8000
|
||||
make admin # Admin on :5173
|
||||
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/](resources/design/) | **Canonical product specs** — place design documents here (often Word). Referenced by `.cursor` as source of truth for features and data model. Expected names include `EventCrew_Design_Document_v1.3.docx`, `EventCrew_Dev_Guide_v1.0.docx`, `EventCrew_Start_Guide_v1.0.docx` (adjust versions if you update files). |
|
||||
| [.cursor/ARCHITECTURE.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](.cursor/instructions.md) | Quick reference, phased roadmap, module build order |
|
||||
| [.cursor/rules/](.cursor/rules/) | Workspace, Laravel, Vue, testing conventions |
|
||||
| [docs/SETUP.md](docs/SETUP.md) | Environment and local setup |
|
||||
| [docs/API.md](docs/API.md) | API notes (if maintained) |
|
||||
| [docs/SCHEMA.md](docs/SCHEMA.md) | Schema notes (if maintained) |
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
```bash
|
||||
cd api && php artisan test
|
||||
```
|
||||
|
||||
Feature tests should cover happy paths plus **401** (unauthenticated), **403** (wrong organisation), and **422** (validation) where applicable.
|
||||
|
||||
Reference in New Issue
Block a user