20-modules/events/overview.md

Module: Events (`events` / `events`)

Status: 🟢 Production (ticketing live; commission wired) · Last validated: 2026-09-06 · Priority: P1

Event listings, RSVP, ticketing (seat bookings), comments, nominees. Validated against classs/EventsModule.php + schema.

A. Purpose

Organizers list events and sell tickets; users RSVP and book seats. Revenue = 5% commission (18 processed rows in commission_transactions for order_table='events_ticket_orders', 2026-09-06; was miscited as 17 and against the wrong table name — see the table-name correction below).

B. Actors

Attendee; event organizer; admin. Enrollment events.

C. Entry points

/eventlist.php, /eventdetail.php.

E. Feature registry (prefix `EVT-`)

ID	Feature	Actor	Method	Tables	Status
EVT-001	Create event	organizer	`createEvent` `:392`	`events_master`	🟢
EVT-002	List / detail	anon+user	`listEvents` `:717`, `getEventDetail` `:880`	`events_master`	🟢
EVT-003	RSVP	user	`setRsvp` `:974`, `listRsvps` `:1001`	`events_rsvp`	🟢
EVT-004	Comments	user	`addComment` `:1033`, `listComments` `:1074`	`events_comments`	🟢
EVT-005	Nominees (awards)	user	`addNominee` `:1097`	`events_nominees`	🟢
EVT-006	Book ticket	user	`bookTicket` `:1180`	`events_ticket_orders`	🟢 (money)
EVT-007	Cancel ticket	user	`cancelTicket` `:1623`	`events_ticket_orders`	🟢
EVT-008	My bookings	user	`getMyBookings` `:33`	`events_ticket_orders`	🟢

Correction (2026-09-06): an earlier pass of this page named the ticket-order table events_seat_bookings throughout EVT-006/007/008, the flow diagram, and the data model. That table exists (17 rows) but is never referenced anywhere in classs/EventsModule.php (checked bookTicket, cancelTicket, getMyBookings, and every other method — grep for events_seat_bookings returns zero hits in the file). The real, live write/read table for tickets is events_ticket_orders (bookTicket INSERTs into it at :1335; getMyBookings SELECTs from it at :43; cancelTicket UPDATEs it at :1662). events_seat_bookings is dormant/legacy — treat it like the hotel_rooms/hotel_master dormant tables in the StayGo page: present in schema, not on any live code path. Code wins; the table name below is corrected accordingly.

F. Ticket flow (EVT-006)

eventdetail.php → bookTicket(userId, data)  :1180 → wallet debit (wallet-first)
  → escrow credit to CLASSIFIED_ESCROW_BUCKET_USER_ID (:1319, mirrors the Food/Hotel escrow pattern)
  → INSERT events_ticket_orders (header, single flat row — no separate ticket-type/seat table) :1335
  → generateInvoice()  :1355 → central payments ledger (PaymentsModule::recordWalletPayment) :1369
  → 5% commission (CommissionEngineModule::computeAndRecord, order_table='events_ticket_orders') :1511
  → notify organizer

G. Data model (2026-09-06)

Table	Rows	Role
`events_master`	0	event header
`events_ticket_orders`	0	ticket bookings (the real live table — see correction above)
`events_seat_bookings`	17	dormant/legacy — not referenced by any code in `EventsModule.php`; do not use
`events_ticket_types`	0	ticket tiers

Data-state anomaly (requires verification): events_master = 0 AND events_ticket_orders = 0, yet commission_transactions carries 18 processed rows with order_table='events_ticket_orders' (2026-09-06 live count). Bookings clearly happened — commission was computed and recorded per booking — but both the event header and the order header table are now empty. This is a harder version of the FoodVerse/StayGo header-purge pattern (there the header is empty but the child/payment rows survive; here the child table itself is also empty and only the downstream commission ledger still shows the activity). Reconcile before quoting any event/ticket count. Note this is a different anomaly than what an earlier pass of this page described (it pointed at events_seat_bookings, which was never the live table — see correction above).

K. State machine

Event: draft → published → live → completed / cancelled. Booking: booked → confirmed → attended / cancelled (refund) .

L / M / N

Errors: EVT-E001 booking without event header (see anomaly). Depends on wallet, commission, notifications. Change-impact: ticket booking touches money — re-test book→pay→commission→cancel/refund.

Module: Events (events / events)