# Cuppa Events Module Plan

## Decision

Events will exist **only inside the Business Panel**. It is not an Admin Panel module, it will not appear beside the existing global **Businesses** navigation item, and it will not change any unrelated feature.

This follows the Kuppa-main ownership pattern:

```text
Kuppa-main
app/Http/Controllers/Business/EventController.php
app/Http/Controllers/Business/Api/EventController.php
resources/js/Pages/Business/Events/

Cuppa
src/app/[locale]/(dashboard)/dashboard/business/events/
src/app/api/businesses/[id]/events/
src/components/business/
src/lib/events/
```

## Sidebar placement

Only the **Business Panel sidebar** will contain the item:

```text
Business Panel
Overview
Locations
Franchises
Events                 <- new Business Panel item only
Staff
Roles
```

The item is visible only when the active Business Panel role has `VIEW_EVENTS` or `MANAGE_EVENTS`. It is editable only with `MANAGE_EVENTS`.

No new global/admin permission, Admin sidebar item, public user page, ticket flow, chat, gallery, map, invitation, notification, or payment behavior is included in this scope.

## Folder structure

```text
src/
├── app/
│   ├── [locale]/(dashboard)/dashboard/business/events/
│   │   └── page.tsx                 # Business event list and management screen
│   └── api/businesses/[id]/events/
│       ├── route.ts                 # List and create events in one business
│       └── [eventId]/route.ts       # Read, update, delete an event in that business
├── components/business/
│   ├── BusinessPanelEvents.tsx
│   └── EventFormModal.tsx
└── lib/events/
    └── recurrence.ts                # Optional recurrence calculation helper
```

## Database ownership

The Event belongs to one Business and one Location. Business Panel access always filters by the active business; there is no global cross-business event screen.

```text
Business
  -> Location
    -> Event
      -> Event
```

`EventRegistration` may be retained for a later Business Panel attendee count, but RSVP UI and all other event subsystems are out of scope.

## Roles

| Actor | Access |
| --- | --- |
| Business owner | Can manage events belonging to their business. |
| Business manager | Can manage events when assigned `MANAGE_EVENTS`. |
| Business staff | Can view events when assigned `VIEW_EVENTS`; write access is explicit. |
| Super Admin / Admin | No new Events navigation or workflow is added for them in this phase. |
| Regular user | No Event feature is added for them in this phase. |

## Complete Business Panel feature catalogue

All features below remain inside `/dashboard/business/events`. They do not add an Admin Panel, public/mobile Events screen, or changes to unrelated modules.

### A. Event dashboard

- Upcoming, past, draft, published, and cancelled event counts.
- Search by event title, location, category, or organiser name.
- Filters by status, location, date range, recurrence, indoor/outdoor, and free/paid type.
- Sort by nearest date, newest created, highest attendance, capacity, or status.
- Compact cards/table showing cover image, title, location, schedule, status, recurrence, attendee count, and capacity.
- Empty state with a direct **Create Event** action.
- Optional calendar view for a single business’s events.

### B. Event creation and editing

- Event title, short summary, and detailed description.
- Cover image upload and replacement using the existing business-upload rules.
- Select one active business location as the host.
- Indoor event defaults to the selected location address.
- Outdoor event can store a custom venue name, address, latitude, longitude, and map link.
- Date, start time, end time, and business timezone.
- Draft, published, cancelled, and archived lifecycle status.
- Event category and type, for example tasting, live music, workshop, launch, happy hour, festival, or private event.
- Tags for internal filtering.
- Capacity, wait-list toggle, minimum age, and visibility notes.
- Free event or internal ticket-price information; payment processing is not included unless explicitly approved later.
- Daily, weekly, and monthly recurrence with a recurrence end date.
- Validation: title required, active location required, valid date/time order, future dates for new published events, positive capacity, and valid recurrence end date.

### C. Publishing lifecycle

```text
Draft -> Published -> Cancelled / Archived
```

- Draft: visible only to authorised Business Panel staff.
- Published: operational event available to the business team.
- Cancelled: retained for history; it cannot accept new attendance actions.
- Archived: hidden from the default list but kept for reporting.
- Duplicate an event to reuse its details for a future date.
- Cancel reason and internal staff note.
- Change history: creator, last editor, creation time, and last update time.

### D. Staff permissions

| Permission | Business Panel ability |
| --- | --- |
| `VIEW_EVENTS` | Open dashboard, list, search, filter, and view event details. |
| `MANAGE_EVENTS` | Create, edit, publish, cancel, archive, duplicate, and delete own-business events. |
| Future `VIEW_EVENT_ATTENDEES` | View attendee list and summary only. |
| Future `MANAGE_EVENT_ATTENDEES` | Manage attendee status, check-in, wait-list, and bans. |

The current role templates should grant Owner full Event access, Manager management access, and Staff view-only access. Custom business roles can be assigned Event permissions later.

### E. Attendee management — optional Business Panel enhancement

This can be added later without creating a public Event module:

- Internal attendee/guest list.
- RSVP status: going, maybe, declined, wait-listed, checked in, no-show, or banned.
- Manual attendee creation by staff for walk-ins, phone bookings, or guest lists.
- Capacity indicator and remaining-space count.
- Check-in action at the venue.
- Bulk import/export CSV for guest list management.
- Notes, dietary/accessibility requirements, and internal staff notes.
- Ban/unban attendee from a specific event.
- Recurring-event attendance stored against the selected occurrence date.

### F. Business collaboration — optional Business Panel enhancement

For multi-location or partner events, still only inside the business workspace:

- Invite another location or franchise in the same business.
- Invite external business partners only after a dedicated cross-business permission is approved.
- Invitation status: pending, accepted, declined, cancelled.
- Booth/table/space name and operational notes.
- Assign an internal event lead and supporting staff.
- Task/checklist items: setup, suppliers, staff briefing, cleanup, and follow-up.

### G. Event content and assets — optional Business Panel enhancement

- Multiple event images, documents, menus, and approved promotional assets.
- Image ordering and cover-image selection.
- Internal gallery approval/rejection queue.
- Event-specific announcement text and reusable copy snippets.
- Downloadable event brief for staff.

### H. Operations and reporting — optional Business Panel enhancement

- Attendance totals and check-in rate.
- Capacity utilisation.
- Events by location, category, and date range.
- Draft/published/cancelled/archive totals.
- Basic internal revenue field/report only if the business records ticket revenue manually.
- Event audit log: who created, edited, cancelled, published, or checked in attendees.
- CSV export for event list, attendance, and internal reporting.

### I. Explicitly excluded unless separately approved

These are Kuppa-main features but are **not** part of the Business Panel-only Event module by default:

- Public/mobile event discovery, nearby search, and public event detail pages.
- User-facing RSVP or social/event posts.
- Public event chat.
- Stripe checkout, paid ticket sales, ticket gifting, QR tickets, and QR redemption.
- Push/email reminders or notifications.
- Boosts, ads, social-media publishing, and public analytics.
- Public live maps or external business invitations.

## Recommended delivery order

| Release | Included Business Panel features |
| --- | --- |
| Release 1 | Dashboard, create/edit/delete, host location, schedule, status, capacity, recurrence, role permissions. |
| Release 2 | Categories, tags, cover image, filters, duplicate/archive, audit fields. |
| Release 3 | Internal attendee list, manual RSVP, check-in, wait-list, CSV import/export. |
| Release 4 | Assets/gallery, internal task checklist, partner/location collaboration, reporting. |

## Delivery phases

1. **Business Panel Events:** sidebar item, event list, create, edit, delete, status, location assignment, and recurrence.
2. **Optional later Business Panel-only enhancement:** attendee count and basic RSVP reporting, only if explicitly requested.

## Non-negotiable rules

- A business user may only read or mutate events within their active business scope.
- The Business Panel sidebar hides Events when the role lacks both Event permissions.
- No event data is exposed through a global, public, or admin API in this phase.
- Recurrence, where enabled, is limited to schedule display and management inside the Business Panel.
- Deleting an event is limited to event records belonging to the active business.

## First implementation change

Keep the current Business Panel route: `/dashboard/business/events`. Do not add a top-level `/dashboard/events` route or any Admin Panel navigation.