A pass sells a ticket at each of several events in a series for one price. Supervisors set passes up on the Event series page (events and ticket per event; fixed once sold). Buying on the series page registers the buyer at every event at once with one checkout (free passes give tickets straight away; Pay now if online payment isn't possible). The price is split over the events in proportion to their normal prices: each registration line is priced at its share and the webhook records one Payment per event, so cashups stay per event. Pass registrations aren't repriced, take no coupons and can't be edited. Migration 20261028150000_season_pass. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
870 lines
52 KiB
Markdown
870 lines
52 KiB
Markdown
# Cross Events — Feature Overview
|
||
|
||
A complete map of what the platform does, grouped by who uses it. For setup and
|
||
deployment see [README.md](./README.md); for the API see
|
||
[backend/API_DOCUMENTATION.md](./backend/API_DOCUMENTATION.md); for setting
|
||
defaults see [SETTINGS.md](./SETTINGS.md); for history see
|
||
[CHANGELOG.md](./CHANGELOG.md).
|
||
|
||
**Stack:** Next.js (React, Tailwind, shadcn/ui) frontend · Express + Prisma +
|
||
PostgreSQL backend · Yoco for card payments · SMTP for email · WAWP for
|
||
WhatsApp · PM2 for process management · optional Sentry for error monitoring.
|
||
|
||
---
|
||
|
||
## Contents
|
||
|
||
1. [Roles](#roles)
|
||
2. [Public site](#public-site)
|
||
3. [Events](#events)
|
||
4. [Registration](#registration)
|
||
5. [Payments, donations & refunds](#payments-donations--refunds)
|
||
6. [Tickets & check-in](#tickets--check-in)
|
||
7. [Attendee forms](#attendee-forms)
|
||
8. [Messaging & notifications](#messaging--notifications)
|
||
9. [User dashboard (My Events)](#user-dashboard-my-events)
|
||
10. [Staff tools](#staff-tools)
|
||
11. [Supervisor tools](#supervisor-tools)
|
||
12. [Admin tools](#admin-tools)
|
||
13. [Cashup & event costs](#cashup--event-costs)
|
||
14. [Reports](#reports)
|
||
15. [Site settings & setup wizard](#site-settings--setup-wizard)
|
||
16. [Event series](#event-series)
|
||
17. [Multi-campus](#multi-campus)
|
||
18. [Kids check-in](#kids-check-in)
|
||
19. [Volunteer rosters](#volunteer-rosters)
|
||
20. [Accounts & security](#accounts--security)
|
||
21. [Privacy (POPIA)](#privacy-popia)
|
||
22. [Help system](#help-system)
|
||
23. [Background jobs](#background-jobs)
|
||
24. [Operations](#operations)
|
||
25. [Page map](#page-map)
|
||
|
||
---
|
||
|
||
## Roles
|
||
|
||
Four roles, each including everything the roles below it can do:
|
||
|
||
| Role | Can do |
|
||
|------|--------|
|
||
| **User** | Browse events, register, pay, donate, view tickets, fill in forms, manage their own profile |
|
||
| **Staff** | Scan tickets, view/print event tickets, view registrations and form responses |
|
||
| **Supervisor** | Create and manage events, record payments/refunds, assign donations, at-the-door desk, manual registration, bulk email/WhatsApp, reports, site banner, self-service kiosk |
|
||
| **Admin** | Manage users and roles, all registrations, event costs and cashup (close/reopen events), audit log, site settings, WhatsApp connection, backups |
|
||
|
||
---
|
||
|
||
## Public site
|
||
|
||
- **Home page** — hero section with the organisation's name and branding, upcoming
|
||
and in-progress events, and a "Join Us" button (becomes "My Dashboard" when
|
||
logged in).
|
||
- **Events list** (`/events`) — event cards with picture, dates, location,
|
||
price, and a Register / Sold Out / Contact us button. A diagonal "Early bird"
|
||
ribbon in the top-right corner while an early-bird tier is running and
|
||
registration is open.
|
||
- **Event detail** (`/events/[id]`) — description, ticket options with
|
||
variant and early-bird pricing, low-stock and sold-out badges, downloadable
|
||
attachments, embedded Google Map with "Directions" link, and an
|
||
**Add to calendar** (`.ics`) button.
|
||
- **Short links** — events can have an alias (e.g. `/camp-2025`) that redirects
|
||
to the event. Only plausible aliases hit the database, so bot probes are
|
||
rejected cheaply.
|
||
- **Contact page** (`/contact`) — organisation email, phone, address and map.
|
||
- **Legal pages** — Terms of Use and Privacy Policy, filled from Site Settings.
|
||
- **Site banner** — a site-wide announcement bar set by supervisors.
|
||
- **Lockdown rules** (`/lockdown-rules`) — static rules page for the youth
|
||
lockdown event.
|
||
- **SEO** — `sitemap.xml` (every public page and event), `robots.txt`, and
|
||
Open Graph/Twitter link-preview metadata.
|
||
- **Theming** — brand colours, logo and favicon come from Site Settings.
|
||
|
||
---
|
||
|
||
## Events
|
||
|
||
Created and edited by supervisors through a 9-step wizard: **Basic Details →
|
||
Items & Pricing → Sections → Form → Visibility → Notifications → Attachments →
|
||
Feedback → Attendance**.
|
||
|
||
- **Basic details** — title, description, start/end dates, registration
|
||
deadline, picture (upload or URL), location (defaults to the org's address),
|
||
contact person.
|
||
- **Copy an event** — "Copy" on an event card opens the editor filled in from that
|
||
event (details, campus, sessions, options, variants, early birds, sections, form,
|
||
notification recipients, feedback questions, certificates, reminders). Setting
|
||
the **New start** moves every date with it (end, sessions, registration deadline,
|
||
early-bird deadlines, feedback date). Allocation groups are copied on save, and
|
||
for admins the planned costs (matched to options by name). Not copied:
|
||
registrations, coupons, attachments, the short link, the go-live time, kids
|
||
check-in and volunteer roles.
|
||
- **Contact-only events** — for things like baptisms: shown publicly with a
|
||
"Contact us" popup instead of registration, with no tickets.
|
||
- **Multi-day events (sessions)** — one event on several dates, e.g. every
|
||
Wednesday 18:30–20:30 for 5 weeks. A repeat pattern (daily/weekly, every N,
|
||
chosen weekdays, a number of sessions or an end date) creates the sessions,
|
||
which can then be edited one by one (label, times, location), added to, or
|
||
cancelled (kept for history; one with check-ins can't be deleted). People
|
||
register and pay once and get one ticket. The event page shows the schedule
|
||
with the next session highlighted; cards show "5 sessions · Wed 4 Nov – Wed
|
||
2 Dec" and stay listed until the last session. Calendar files get one entry
|
||
per session. Saving moved or cancelled sessions offers to message attendees.
|
||
- **Pick sessions** (multi-day) — instead of the whole course, people can choose
|
||
which sessions to come to (day passes, drop-in classes). Tickets set to "Pick
|
||
sessions" are priced and bought per session — one line and one ticket per session,
|
||
bookable until the session starts (staff: until it ends) — alongside optional
|
||
whole-course tickets. Sessions can have a capacity (picked places plus whole-course
|
||
tickets); a per-session ticket's stock limit is places per session. Picked tickets
|
||
only scan on their own session; reminders, the register and certificates follow
|
||
the sessions each person booked. "All sessions" tickets on such an event also show
|
||
the sessions: people tick the ones they'll come to and pay the ticket's one price; the
|
||
ticket scans, reminds and counts towards capacity for those sessions only. The waitlist
|
||
works per session (a full session shows "Join waitlist"). Bookable from the registration page, Manual registration,
|
||
At the door (today's session is preselected) and the kiosk. Not available on youth
|
||
events.
|
||
- **Late joining** (multi-day) — registration closes when the first session
|
||
starts, or later (until session N) with late joining on. Late joiners pay
|
||
full price, a pro-rata price for the sessions left (rounded to the nearest
|
||
R10), or a fixed late price — main tickets only.
|
||
- **Completion certificates** — optional per event: four designs (Classic,
|
||
Modern, Church, Kids), custom wording with placeholders, signature name/role/
|
||
image, and a completion rule (every session, at least N sessions, or N%).
|
||
Issued automatically when the event ends; each has a code and QR code checked
|
||
on a public verify page.
|
||
- **Ticket options** — multiple options per event (e.g. Adult, Child, Dinner,
|
||
T-shirt), each with a price and optional **stock limit**. One option is marked
|
||
as the main ticket, which is what gets checked in at the door.
|
||
- **Variants** — sub-types of an option (sizes, colours, Adult/Child/VIP), each
|
||
with an optional price override and its own stock limit.
|
||
- **Early-bird tiers** — deadline- and/or stock-limited cheaper prices per
|
||
option or variant. Prices are locked in per purchase ("tranches"), so buying
|
||
more later doesn't re-price what was already bought.
|
||
- **Sections** — named scan points (e.g. "Main hall", "Dinner") limited to
|
||
certain ticket options, so a scanner at that point only accepts those tickets.
|
||
- **Visibility** — active/inactive, hidden (reachable only by link), scheduled
|
||
go-live date, require login vs. allow guest registration, or no registration
|
||
at all.
|
||
- **Attachments** — downloadable files (maps, schedules, waivers) shown on the
|
||
event page.
|
||
- **Notify recipients** — choose which staff get registration/payment alerts and
|
||
the daily summary for the event.
|
||
- **Sold-out handling** — an event is sold out when every stock-limited option
|
||
is exhausted. "X remaining" badges appear at a threshold that scales with
|
||
capacity.
|
||
|
||
---
|
||
|
||
## Registration
|
||
|
||
- **Online registration** (`/register/[eventId]`) — pick options, variants and
|
||
quantities; see early-bird prices and stock warnings; fill in the event form.
|
||
- **Guest registration** — when an event doesn't require login, an inactive
|
||
account is created and an activation link is sent by email or WhatsApp.
|
||
- **Statuses** — Pending, Confirmed, Partially Paid, Paid, Cancelled.
|
||
- **Edit options** — users can add or change items on their registration
|
||
(not for past or closed events).
|
||
- **Self-cancellation** — allowed only before any payment; admins can cancel
|
||
any time.
|
||
- **Pricing refresh** — when an unpaid registration is viewed or paid, expired
|
||
early-bird prices are re-evaluated, and the user is warned if the total
|
||
changed.
|
||
- **Manual registration** (supervisor) — register someone on their behalf,
|
||
creating an account if needed. Includes a "Record Payment" tab.
|
||
- **Duplicate-account protection** — if an email and phone belong to two
|
||
different accounts, the registration is blocked instead of merging them.
|
||
- **Group tickets** — on events with "Named attendees" turned on, someone booking
|
||
several places can name each person (with optional email/phone). Each named person
|
||
gets their own ticket and their own attendee form; unnamed places share one ticket.
|
||
Tickets go all to the payer, or each to the person (falling back to the payer).
|
||
Attendees matching an existing account see their ticket in My Events. Names can be
|
||
added or changed later from My Events, and attendees can be sent a link to fill in
|
||
their own form. Available on the registration page, manual registration, At the
|
||
door and the kiosk.
|
||
- **Waitlist** — on events with a waitlist, sold-out tickets show "Join waitlist"
|
||
(on the event page, the register page and the event list). When places free up — a
|
||
cancellation, a smaller booking or a higher stock limit — the next person is
|
||
emailed/WhatsApped a claim link and the places are held for them (24 hours by
|
||
default) so nobody else can buy them. Unclaimed offers expire and move on; people
|
||
who asked for more than came free can be offered what's free or skipped. Claiming
|
||
works without logging in. People can leave from My Events. On pick-sessions events
|
||
people wait for a particular session; offers never run past the session's start.
|
||
- **Parental consent (youth events)** — on events that require it, every attendee
|
||
gives a date of birth; for anyone under 18, a parent or guardian gets an email and
|
||
a WhatsApp with a consent link. They read the event's consent text, optionally give
|
||
medical info, an emergency contact and photo consent, type their name to sign, and
|
||
give or decline. Tickets are issued but can't be checked in until consent is given
|
||
(supervisors can override, audited). Reminders go after 2 days, then every 3 days.
|
||
Medical details are encrypted and deleted a set number of days after the event.
|
||
- **Coupon codes** — percentage, fixed-amount or free (comp) codes, entered under
|
||
"Have a code?" on the registration page, in My Events (for unpaid registrations),
|
||
manual registration, At the door and the kiosk. Codes can be limited to events,
|
||
ticket options or variants, dates, total and per-person uses, a minimum quantity,
|
||
and specific people, roles or an email domain (restricted codes need a login).
|
||
Early-bird prices either stack or the better price wins. The discount is locked in
|
||
when applied and shows on invoices, receipts, emails and the Yoco checkout;
|
||
cancelling frees the use. Managed from Supervisor → Coupon codes.
|
||
- **Staff price** — a ticket option or variant can have a staff price that Staff and
|
||
above get automatically, without a code.
|
||
|
||
---
|
||
|
||
## Payments, donations & refunds
|
||
|
||
- **Online card payments via Yoco** — checkout for the full outstanding balance,
|
||
confirmed by a signed webhook. Keys and the webhook are set up from
|
||
Site Settings → Payments, where providers are switched on or off and put in order
|
||
(the first one is the default). Online payments are at least R15; payments are
|
||
recorded at the full amount and provider fees are dealt with at cashup.
|
||
- **PayFast** — the second online provider (card, instant EFT…), with sandbox and live
|
||
modes. When several providers are on, payers choose on the "Pay online" page; a
|
||
payment of a different amount from the checkout is held for review instead of being
|
||
recorded. When no provider is on (or the amount is under R15), nothing offers to pay
|
||
online.
|
||
- **Payment status checks** — if a provider's notification never arrives, Payments →
|
||
Reconcile → "Waiting for payment" checks with the provider (PayFast; Yoco's API can't be
|
||
asked) and records what it finds. A job checks recent PayFast checkouts every 15 minutes.
|
||
- **Payment links** — supervisors can generate and send a Yoco link for any
|
||
amount (including partial).
|
||
- **Manual payments** — cash, card, EFT, voucher or other, recorded by staff.
|
||
Each payment records **who recorded it** as well as who it's for.
|
||
- **Refunds** — negative payments against an original payment, netted against
|
||
the original method.
|
||
- **Impersonate user** (Admin → Manage users) — an admin with 2FA can view the site as a
|
||
user, to debug problems.
|
||
- It needs a reason, lasts at most 30 minutes, and shows a bright "Viewing as" banner
|
||
on every page.
|
||
- It is strictly read-only. A server-side guard refuses every write made with the
|
||
impersonation token before it reaches any route, and pages don't even refresh
|
||
prices while viewing.
|
||
- Admins can't be impersonated.
|
||
- The start, end, reason and every page and API call are in the audit log, with each
|
||
session's trail.
|
||
- Optional email to the user (`notify_user_on_impersonation`).
|
||
- **Registration funnel stats** — first-party and consent-based, with no third-party analytics.
|
||
- A cookie notice asks once. Only visitors who allow it get a random visit id.
|
||
- We record event page views and registration starts. Submits and payments come
|
||
from the registration itself.
|
||
- Each record holds only the stage, the traffic source (utm_source, or the short-link
|
||
alias, which short links now pass as `?src=`) and the device type.
|
||
- The Registration funnel report shows counts and conversion per stage over a date
|
||
range, a daily trend, and breakdowns by source, device and ticket option.
|
||
- A "Conversion (past month)" tile on the supervisor/admin dashboards covers live
|
||
events.
|
||
- Raw rows are rolled up into daily totals after 90 days.
|
||
- **Post-event feedback** — a Feedback step in the event wizard.
|
||
- Questions use the form builder, with new **star rating (1–5)** and **multiple
|
||
choice** types (also available on attendee forms).
|
||
- The form goes out at a chosen time to everyone who checked in, or to everyone
|
||
registered, each with a personal link (`/feedback/<token>`). One reminder goes
|
||
3 days later to anyone who hasn't answered.
|
||
- Answers can be anonymous or named. "Send now" is available, and the questions
|
||
lock once people have answered.
|
||
- **Sponsor a spot** — per-event setting. A "Sponsor a spot" button on the event page
|
||
lets anyone, including guests, pay for one or more spots (at the main ticket price)
|
||
or any amount through Yoco. They can give anonymously or add a name and a message.
|
||
The money is a donation tagged to the event and goes into its sponsorship pool, which
|
||
supervisors assign to registrations with the usual donation flow.
|
||
- An optional public progress bar ("12 of 20 spots sponsored") with an optional goal.
|
||
- Sponsors get a thank-you receipt, and an Automations thank-you can go to all of an
|
||
event's sponsors.
|
||
- The Donations breakdown report shows each pool: received, assigned and remaining.
|
||
- Who is helped is never shown.
|
||
- **Donations** — users can donate from their dashboard (`/dashboard/user/donate`).
|
||
Supervisors can **assign** a donation (fully or partly) to someone's
|
||
registration and **unassign** it later. Assignments are kept as separate
|
||
records, so the original donation never changes.
|
||
- **Online payment reconciliation** — provider (Yoco) transactions can be matched to a
|
||
registration, recorded as a donation (optionally choosing the donor), or
|
||
ignored.
|
||
- **Invoices & receipts** — branded PDFs: an invoice (itemised, early-bird
|
||
discount, balance due, pay-now link and QR code) and a payment receipt. Sent
|
||
automatically and re-sendable on demand by email or WhatsApp.
|
||
- **Method normalisation** — Apple Pay / Google Pay / checkout payments count as
|
||
"Card" in reports and user views.
|
||
|
||
---
|
||
|
||
## Tickets & check-in
|
||
|
||
- **Automatic tickets** — QR-coded tickets are generated when a registration is
|
||
fully paid (or free), and sent as a PDF by email and/or WhatsApp.
|
||
- **Quantity tickets** — one ticket can cover several people and be redeemed
|
||
partially (e.g. check in 2 of 3).
|
||
- **Named tickets** — group bookings can give each person their own ticket, shown
|
||
with their name on the PDF, the scanner and the staff ticket list.
|
||
- **QR scanner** — works in any mobile browser. A preview checks the ticket is
|
||
for the selected event/section, then a confirmation screen shows holder, type
|
||
and remaining quantity.
|
||
- **Check-in confirmation** — holders get an email/WhatsApp saying how many were
|
||
checked in and how many remain.
|
||
- **Per-session check-in** — multi-day tickets are checked in once per session.
|
||
The scanner uses today's session (or one picked from a list). Check-in is open
|
||
the whole day of a session, or only from 2 hours before it until it ends, per
|
||
event. Optional reminders (1 h / 3 h / 1 day before each session) by email
|
||
and/or WhatsApp.
|
||
- **Attendance register** — attendees × sessions with ticks, totals per session,
|
||
completion, filters (completed, missed the last two), Excel/PDF export.
|
||
Supervisors can tick someone present or absent (audit-logged), and issue,
|
||
send, download or revoke certificates.
|
||
- **Scan stats** — recent scans and per-event scan counts.
|
||
- **Offline scanning** — while online, a staff member locks an event section (or the
|
||
whole event) to their device and downloads its tickets. They can then keep scanning
|
||
with no connection; scans are queued on the device and sync automatically when it's
|
||
back online (never redeeming more than is left). Only one device can hold a section,
|
||
and while it's locked nobody else can scan it, online or offline. Problems found
|
||
while syncing go into a report for a supervisor. Supervisors can force-release a
|
||
lost device. The scanner can be added to the home screen (PWA) and opens offline.
|
||
- **Printing** — A4 sheets (8 tickets per page) and A6 single tickets.
|
||
- **Resend** — send tickets to a different email/phone at the door.
|
||
|
||
---
|
||
|
||
## Attendee forms
|
||
|
||
- **Form builder** per event — field types: Yes/No, Text, Paragraph, Number,
|
||
Date, plus Statement and Heading blocks; required/optional, help text,
|
||
reordering. The whole form can be marked required.
|
||
- **Drafts** — partially filled forms are auto-saved.
|
||
- **Responses** — view, filter (event, user, past/inactive) and print one
|
||
response per A4 page. Supervisors can edit responses.
|
||
|
||
---
|
||
|
||
## Messaging & notifications
|
||
|
||
Every user picks a **notification preference**: Email, WhatsApp, or Both.
|
||
|
||
**Automatic notifications**
|
||
|
||
| Trigger | Goes to |
|
||
|---------|---------|
|
||
| Registration created / updated | Registrant (with invoice if unpaid) + event notify recipients |
|
||
| Payment recorded / donation applied / unassigned | Registrant (with receipt) + admins |
|
||
| Refund processed | Registrant + admins |
|
||
| Tickets generated | Registrant (ticket PDF) |
|
||
| Ticket checked in | Ticket holder |
|
||
| Daily summary, 07:00, for each live event that hasn't started yet | Registrations inbox + event notify recipients |
|
||
| Account registered, activation, login, password changed/reset, account closed | The account holder |
|
||
|
||
**Bulk messaging** (supervisor)
|
||
|
||
- **Email attendees** and **WhatsApp attendees** — filter by status or pick
|
||
specific attendees, preview, send now or schedule for later.
|
||
- **Placeholders** — `{{name}}`, `{{event.title}}`, `{{event.link}}`,
|
||
`{{event.start}}`, `{{balance}}`, and `{{payment.link}}` (a live Yoco link for each recipient's
|
||
outstanding balance).
|
||
- **Broadcasts** — ad-hoc email/WhatsApp to any users or addresses, not tied to
|
||
one event.
|
||
- **Message type** — Event update or News & announcements; news only reaches people
|
||
who opted in (see [Privacy](#privacy-popia)).
|
||
- **Automations** — schedule a sequence of lifecycle emails for an event
|
||
(pre-event, final reminder, thank-you, promo for another event).
|
||
- **Manage scheduled** — view, edit or delete queued jobs per channel. Sends
|
||
run in the background and are purged 24 h after sending.
|
||
|
||
**WhatsApp** is connected through the WAWP API: an admin links a number in
|
||
Site Settings → WhatsApp (QR code or pairing code), with status, restart and
|
||
logout controls. Disconnected sessions are recovered automatically.
|
||
|
||
---
|
||
|
||
## User dashboard (My Events)
|
||
|
||
- Registrations with status badges, event thumbnails, and Closed/Past/Inactive
|
||
tags. Past and closed events are hidden by default.
|
||
- Registration detail: itemised bill (early-bird lines grouped), payments,
|
||
**Invoice** and **Receipt** buttons, edit, cancel, **Make payment**.
|
||
- Upcoming events and tickets side by side, with bulk ticket email/WhatsApp.
|
||
- **Ticket transfer** — offer a ticket to someone else before the event by typing
|
||
their name and email/phone (no user search, and nothing reveals whether they have an
|
||
account). They get a link to accept or decline; the ticket only moves once they
|
||
accept, and the sender can cancel until then (offers expire after 7 days or at the
|
||
event start). On accepting they get a new ticket and QR code, and an inactive account
|
||
with an activation link if they're new. The old code stops working, and scanning it says it
|
||
was transferred, both online and in offline-mode sync reports. One place can be split
|
||
off a ticket covering several people. Billing stays with the payer. It's not allowed
|
||
once a ticket has been scanned, and it can be turned off per event (supervisors can
|
||
always transfer, from At the door → Tickets). On youth events the new holder needs
|
||
their own parental consent, and the previous holder's form answers are removed.
|
||
Every transfer is in the audit log.
|
||
- **Payment history** (`/dashboard/user/payments`) — paginated, with filters by
|
||
date, method and payment/refund.
|
||
- **Donate** page.
|
||
- **Forms** — complete outstanding attendee forms.
|
||
- **Profile & Security** — edit details and notification preference, change
|
||
password, see recent account activity (logins, password changes, device),
|
||
sign out everywhere, deactivate or delete my data.
|
||
|
||
---
|
||
|
||
## Staff tools
|
||
|
||
- **Staff dashboard** — scan stats and quick actions.
|
||
- **Ticket scanning** (`/dashboard/staff/ticket-scanning`) — camera QR scanner
|
||
with event and section filters.
|
||
- **Event tickets & printing** (`/dashboard/staff/event-tickets`) — list, search
|
||
and print an event's tickets.
|
||
- **Kids check-in** (`/dashboard/staff/kids`) and the **room screen**
|
||
(`/dashboard/staff/kids/rooms`) — see [Kids check-in](#kids-check-in).
|
||
- **Volunteers** (`/dashboard/staff/volunteers`) — today's roster, ticking volunteers in and the
|
||
check-in QR code — see [Volunteer rosters](#volunteer-rosters).
|
||
|
||
---
|
||
|
||
## Supervisor tools
|
||
|
||
- **Dashboard** — KPIs (active events, revenue, donations, registrations,
|
||
tickets sold, each vs. the previous month), revenue trend chart, top events,
|
||
and recent scans. Tiles link to the matching report.
|
||
- **Manage events** — the 9-step event wizard, ticket options, variants,
|
||
sections, form and attachments.
|
||
- **At the door** — search by name/phone/ticket ID, walk-in registration,
|
||
payments, a **Check-In** tab for redeeming main tickets by quantity, and
|
||
ticket printing/resending.
|
||
- **Self-service kiosk** (`/self-service`) — a touchscreen page a supervisor
|
||
unlocks for an event, where visitors register themselves. Existing accounts
|
||
are matched by email/phone, and any change to their details needs
|
||
confirmation.
|
||
- **Manual registration** — register someone on their behalf and record their
|
||
payment.
|
||
- **Payments** — tabs for Payment, Refund, Donations (assign/unassign),
|
||
Reconcile (Yoco transactions), and Payment Link.
|
||
- **Coupon codes** (`/dashboard/supervisor/coupons`) — create, edit and turn off
|
||
discount codes, and see who used each one.
|
||
- **Rooms & groups** (`/dashboard/supervisor/allocations`):
|
||
- Per event, allocation sets such as "Rooms", "Small groups" or "Buses". Each set
|
||
has groups with an optional capacity, gender restriction and leader (staff).
|
||
- A drag-and-drop board, plus auto-allocate: fill evenly, respecting capacity and
|
||
gender, keeping bookings together or splitting them.
|
||
- Printable per-group and master lists. On youth events they can include medical
|
||
details, and viewing those is audited.
|
||
- The group can show on tickets and in My Events.
|
||
- Email and WhatsApp attendees can be filtered to one group.
|
||
- Leaders see their people under Staff → **My groups**.
|
||
- Works on named attendees. Events can ask each person's gender.
|
||
- **Offline scanning** (`/dashboard/supervisor/offline-scans`) — devices holding
|
||
offline locks (with force release) and sync reports to review.
|
||
- **Waitlist** (`/dashboard/supervisor/waitlist`) — the queue per event: offer a
|
||
place now, move people up or down, or remove them.
|
||
- **Parental consent** (`/dashboard/supervisor/consent`) — consent status per
|
||
attendee on youth events, resend (one or all pending), re-request after the
|
||
consent text changes, and a printable medical & emergency list (audited).
|
||
- **Email attendees / WhatsApp attendees** — bulk and scheduled messaging.
|
||
- **Forms** — view, filter, edit and print form responses.
|
||
- **Reports** — see [Reports](#reports).
|
||
- **Site banner** (`/set-banner`) — set the announcement bar.
|
||
|
||
---
|
||
|
||
## Admin tools
|
||
|
||
- **Admin dashboard** — same KPIs as supervisor, plus admin quick actions.
|
||
- **Manage users** — server-side search and filters (role, active), paging,
|
||
edit role and notification preference, revoke sessions, delete or
|
||
**anonymise** personal data.
|
||
- **Data requests** — POPIA correction and deletion requests (see
|
||
[Privacy](#privacy-popia)).
|
||
- **Registrations** — all registrations, with filters (event, status, text),
|
||
status counts, revenue and outstanding totals, and per-registration options,
|
||
form answers and payments (with who recorded each one).
|
||
- **Cashup** — see below.
|
||
- **Audit log** (`/dashboard/admin/audit-log`) — who did what and when for
|
||
refunds, donation assign/unassign, manual registrations, staff
|
||
cancellations, event create/update/delete, settings changes, and coupon codes
|
||
(created, edited, turned off, applied or removed by staff).
|
||
- **Site settings** — see below.
|
||
|
||
---
|
||
|
||
## Cashup & event costs
|
||
|
||
- **Event costs** — once-off or per-item costs (optionally linked to a ticket
|
||
option), with a "paid from takings" method so cash on hand is correct.
|
||
- **Expected vs. actual** — expected takings per method (cash/card/EFT/other)
|
||
compared with actual amounts, with variance shown.
|
||
- **Cash denomination counts** — entered per staff member, at any time. The
|
||
event's actual cash is the sum of these counts.
|
||
- **Payment accountability by staff member** — what each person recorded, by
|
||
method, with live cash variance.
|
||
- **Close / quick close / reopen** an event — closing locks it from further
|
||
edits and hides it from the kiosk and user actions. Drafts are saved as you
|
||
go.
|
||
- **Report tab** — a read-only cashup summary, shown automatically once the
|
||
event is closed.
|
||
- **Cashup audit trail** — every close/reopen with totals and who did it.
|
||
|
||
---
|
||
|
||
## Reports
|
||
|
||
A full-width workspace with shared filters (events, date range with presets,
|
||
include past/inactive/closed) and a searchable grid of reports, each opening in
|
||
a viewer with its own filters, stat tiles and bar charts.
|
||
|
||
| Category | Reports |
|
||
|----------|---------|
|
||
| Financial | Payments between dates · Revenue summary (by method) · Revenue detailed · Finance report (revenue & costs, after discounts) · Profit report · Discounts (coupon codes) |
|
||
| Registration | Registration funnel (views → started → submitted → paid, daily trend, by source / device / ticket option) · Attendees per event (grouped by option) · Registration type counts · Master orders breakdown · Registration status breakdown (count by registration or ticket quantity) · Parental consent status · Medical & emergency list · Feedback summary (response rate, average ratings, choice breakdowns, comments; compare events) |
|
||
| Ticketing | Ticket usage summary |
|
||
| Donations | Donations breakdown (used / unused per event, plus the sponsorship pool) |
|
||
| Cashup | Cashup reconciliation · Cashup audit trail |
|
||
| Other | Series: year on year (a series' events side by side — registrations, tickets, income, checked in, attendance rate, change from the one before) |
|
||
|
||
**Export:** Print, branded PDF download, styled Excel (`.xlsx`) workbook,
|
||
Email (to yourself), or WhatsApp (the PDF to your own number). Dashboard tiles
|
||
deep-link into reports with `?report=&range=`.
|
||
|
||
---
|
||
|
||
## Site settings & setup wizard
|
||
|
||
**Setup wizard** (`/setup`) — on a fresh database, walks through organisation
|
||
details, the first admin account and branding. No manual seeding needed.
|
||
|
||
**Site Settings** (`/dashboard/admin/settings`) — stored in the database and
|
||
applied without a restart. Secrets are encrypted with AES-256-GCM.
|
||
|
||
| Tab | Contains |
|
||
|-----|----------|
|
||
| Organisation | Name, tagline, contact email/phone, address (with map link) |
|
||
| Campuses | Off by default. Turn on, then add, order, archive or delete campuses (name, web address, address, contact, colour, logo, default event location, daily-summary recipients) |
|
||
| Branding | Primary/secondary/accent colours, logo, favicon, colours suggested from the logo, live website/email preview on desktop and mobile |
|
||
| Notifications | Registrations inbox and admin notification emails |
|
||
| Email | SMTP host/port/TLS/user/password/from, with a "Test connection" button |
|
||
| Legal | Operator, Information Officer, website, effective date for the Terms/Privacy pages |
|
||
| WhatsApp | WAWP credentials, connect a number, status/restart/logout |
|
||
| Payments | Online payment providers: Enabled toggle and order; PayFast merchant ID/key, passphrase and sandbox/live; Yoco's secret key (masked, test/live), webhook secret (generate by registering with Yoco, or enter), list/delete the account's webhooks |
|
||
| Backups | List, run now, download database backups |
|
||
|
||
See [SETTINGS.md](./SETTINGS.md) for the default of every setting.
|
||
|
||
---
|
||
|
||
## Event series
|
||
|
||
Separate events grouped on one page — every year's camp, the monthly men's breakfast (each event
|
||
keeps its own registrations; for one event on several dates see multi-day events).
|
||
|
||
- **Event series** page (supervisors): name, web address (`/series/<slug>`), description, picture;
|
||
each series lists its events (campus-scoped supervisors see only their campuses' events in it)
|
||
and its number of followers. Admins can delete a series (its events stay).
|
||
- **Series box** in the event editor's Basic details. A copied event keeps its series. A series can
|
||
have events at several campuses.
|
||
- **Public series page**: upcoming events as cards, then past events. Event pages in a series show
|
||
"Part of …" and **Next in this series** (the next public event in it).
|
||
- **Follow a series**: signed-in people follow on the series page; when a new event in it goes live
|
||
(before it starts) they get one email, sent as News & announcements (opted-in only, with an
|
||
unsubscribe link). The `series` job runs every 15 minutes.
|
||
- **Year on year**: Reports → Series: year on year (or **Compare** on the Event series page)
|
||
compares the series' events — registrations, tickets, income, checked in (average per session on
|
||
multi-session events), attendance rate — each against the one before.
|
||
- **Season passes**: on the Event series page, a pass gives a ticket (and variant) at each event
|
||
ticked, at one price (optional sale end; stops when its first event starts; no youth events,
|
||
staff-only or per-session tickets). Buyers choose how many on the series page and are registered at
|
||
every event at once with one payment (or tickets at once when free; "Pay now" later if online
|
||
payment isn't possible). The price is split over the events in proportion to their normal prices;
|
||
each event gets its own registration line and payment for its share, so cashups stay per event.
|
||
Pass registrations aren't repriced, take no codes and can't be edited. Events and price lock once
|
||
sold.
|
||
|
||
## Multi-campus
|
||
|
||
For a church with several campuses in one install (Site settings → Campuses, off by
|
||
default — single-campus churches never see campus fields).
|
||
|
||
- **Events** belong to one campus or to **All campuses** (church-wide). Choosing a campus fills in
|
||
its default location. Moving an event to another campus is in the audit log.
|
||
- **Public site:** a campus filter on the events page, remembered per visitor and starting on their
|
||
home campus; a campus shows its own events plus church-wide ones. The campus shows on event cards,
|
||
the event page and ticket PDFs. Each campus has a page at `/campus/<slug>` (also in the sitemap).
|
||
- **People** choose a home campus on their profile.
|
||
- **Reports and dashboards:** a campus filter on Reports (every report and the funnel) and on the
|
||
admin/supervisor dashboards' month-over-month tiles, with a church-wide total.
|
||
- **Messages:** "Everyone at a campus" in Email and WhatsApp broadcasts — home campus, plus (ticked)
|
||
people who registered for its events in the last 12 months. News consent still applies.
|
||
- **Daily summary:** campus recipients get the summary of their campus's events.
|
||
- **Turning it off** hides everything campus-related; nothing is deleted. A campus with events can't
|
||
be deleted, only archived.
|
||
- **Staff for some campuses** (Admin → Users → "Limit to campuses"): a supervisor or staff member
|
||
sees only their campuses' events plus events for all campuses — every list, report, dashboard
|
||
and scanner follows it. For church-wide events they can scan, register people and take payments
|
||
at the door, but not change, cash up or refund them. The site banner, payment reconciliation and
|
||
donations not linked to an event are for admins and unscoped supervisors; broadcasts only reach
|
||
people at their campuses or their events' attendees; coupons only for their campuses' events.
|
||
Another campus's records answer "not found"; the scanner says which campus a ticket is for.
|
||
Admins are never limited; limits are ignored while campuses are off.
|
||
|
||
---
|
||
|
||
## Kids check-in
|
||
|
||
Secure check-in and pickup for children's ministry, run from a staff desk and fully digital — no
|
||
label printers.
|
||
|
||
- **Setup** (Supervisor → Kids check-in setup, `/dashboard/supervisor/kids`): per event, a
|
||
**kids ticket** (a main ticket covering the whole event — "Add a free Kids check-in ticket"
|
||
makes one) and **rooms** (an allocation set; each room has an age range, capacity and children
|
||
per leader), then switch it on. Weekly kids church = one event with a session per Sunday.
|
||
- **Families** are kept between events: parents add their children under My account → **Kids**
|
||
(`/dashboard/user/kids`) — date of birth, allergies, medical and custody notes — and their
|
||
**authorised adults** (name, phone, relationship; no account needed). The page shows a family QR
|
||
code for the desk.
|
||
- **Desk** (`/dashboard/staff/kids`): find the family (name, phone or family QR) or add one, tick
|
||
the children (room suggested from the age: the narrowest range that isn't full), check in. The
|
||
family gets a **4-character pickup code** for the day or session (no 0/O/1/I), sent to the parents
|
||
by WhatsApp/email and shown on their Kids page with a QR code; it can also go to an authorised
|
||
adult. A **"write on the sticker"** panel shows first name, room, code and ALLERGY/MEDICAL in
|
||
large print to copy onto a blank sticker.
|
||
- **Check-out:** type or scan the code, see the children on it, the parents, the authorised adults
|
||
and any custody notes, record who collected. Anyone with the code can collect. A **wrong code**
|
||
is refused, raises an alert on the room screens and is audited; **without the code** needs who
|
||
and why (audited).
|
||
- **Room screen** (`/dashboard/staff/kids/rooms`): live cards per room — code, allergies, medical
|
||
and custody notes, parents and authorised adults — "I'm on duty", counts and full/over-ratio
|
||
warnings, **Call parent** (WhatsApp/email, shown on the parent's page), move to another room,
|
||
check out without code, wrong-code alerts.
|
||
- **Offline desk:** "Get ready for offline" downloads the families and 20 pickup codes reserved for
|
||
the device. Offline, the desk checks in (no messages) and checks out children it checked in
|
||
itself; "Sync" uploads everything and says if a family got another code elsewhere.
|
||
- **Attendance:** each child gets a free place on the kids ticket under the parent the first time
|
||
(registration, attendee, ticket), and each check-in is a ticket usage — so the attendance
|
||
register, reports and campus scoping include them.
|
||
- **Privacy:** allergies, medical and custody notes encrypted, never in messages; custody notes
|
||
changed only by parents, supervisors and admins (audited); opening the desk/room screens and
|
||
offline downloads are in the access log; a child's profile is deleted after **6 months** without
|
||
a check-in (Admin → Privacy → Retention).
|
||
- **Volunteers in kids rooms:** a serving role linked to a room puts its volunteers on duty there
|
||
when they check in; the room screen lists who is rostered but not in yet.
|
||
- The kids ticket is never offered publicly (left out of public event pages, refused on public
|
||
registration).
|
||
|
||
---
|
||
|
||
## Volunteer rosters
|
||
|
||
Who serves where, for an event or each session.
|
||
|
||
- **Roles** (Supervisor → Volunteer rosters, `/dashboard/supervisor/volunteers`): name, people
|
||
needed, optional shift times (default: the session's or event's times), description, and
|
||
optionally a kids room. On a multi-session event each role is for one session. A role can't be
|
||
deleted once someone has checked in for it.
|
||
- **Volunteering** (My account → Serving, `/dashboard/user/serving`): anyone with an account signs
|
||
up for a role that isn't full; supervisors can also put people on (beyond the number needed).
|
||
Nobody can be in two roles whose shifts overlap. `?event=<id>` opens one event (the sign-up link
|
||
supervisors share, also for hidden events). Volunteers are told when they're put on, taken off,
|
||
or a role is deleted, and get a **reminder the day before**.
|
||
- **Swaps:** "Can't make it" asks for cover — the event's other volunteers are told and the request
|
||
shows on everyone's Serving page; the first to accept takes the place at once (no approval). The
|
||
event's notification recipients (or its creator) are emailed about every swap and withdrawal.
|
||
- **Check-in:** volunteers scan the event's **check-in QR code** (Check-in QR tab, or Staff →
|
||
Volunteers) with their phone camera → `/serve/check-in` → every shift of theirs on that day is
|
||
checked in. Staff can tick people in by hand (and undo). Check-in opens on the day of the shift
|
||
and closes when it ends.
|
||
- **Kids rooms:** checking in for a role linked to a kids room puts the volunteer on duty in that
|
||
room (counted for the ratio, like "I'm on duty"); undoing the check-in takes them off.
|
||
- **Volunteer ticket** (off by default): choose a main ticket of the event, or add a free
|
||
"Volunteer" ticket. Volunteers without a ticket get a free place on it (in My Events); it's
|
||
cancelled when they leave the roster (unless it was scanned), moves with a swap, and is never
|
||
offered publicly.
|
||
- **Reports:** roster sheet (phone numbers, check-in time and how), printable; fill rate per event;
|
||
**hours served** per person (checked-in shifts × shift length) over all events or one.
|
||
- **Read-only licence:** new roles and sign-ups are blocked; check-ins, swaps and withdrawals keep
|
||
working.
|
||
|
||
---
|
||
|
||
## Accounts & security
|
||
|
||
- Register, log in, forgot/reset password, activate account (for accounts
|
||
created on someone's behalf).
|
||
- JWT authentication (HS256 pinned) with **session revocation** (token
|
||
versioning) — users can sign out everywhere, and admins can do it for any user.
|
||
- **Two-factor authentication** — a 6-digit login code by email or WhatsApp
|
||
(10-minute expiry, 5 attempts, resend), with "Trust this device for 30 days".
|
||
**Required for Admins and Supervisors**: their next login sends a code that turns
|
||
it on, and they can change the channel but not turn it off (skipped only when no
|
||
email or WhatsApp channel can deliver a code; `TWO_FACTOR_REQUIRED_ROLES=false`
|
||
is the emergency switch). Optional for everyone else from Profile & Security.
|
||
Admins can reset it for a locked-out user, and the kiosk asks for the code at
|
||
setup.
|
||
- **Login lockout** after repeated failed attempts, plus login rate limiting
|
||
(`TRUST_PROXY` to read real IPs behind a proxy).
|
||
- **Security event log** — logins, password changes and resets, with device
|
||
and IP.
|
||
- **Account closure** — deactivate, or close and ask for the personal data to be
|
||
deleted (see [Privacy](#privacy-popia)).
|
||
- **Upload hardening** — server-generated filenames, and uploads served with a
|
||
sandbox CSP and `nosniff`.
|
||
|
||
---
|
||
|
||
## Privacy (POPIA)
|
||
|
||
Tools that help a church handle personal information the way POPIA expects. They
|
||
support compliance; wording and retention choices are for the church's Information
|
||
Officer.
|
||
|
||
**For everyone** — the **Privacy** page (`/dashboard/user/privacy`):
|
||
|
||
- **News & announcements** opt-in per channel (email, WhatsApp), with the history of
|
||
every choice: when, and how (sign-up, privacy page, unsubscribe link, STOP reply…).
|
||
Sign-up has an unticked opt-in box; accounts that never answered are asked once
|
||
after logging in.
|
||
- **Download my data** — readable PDF, or the complete copy as JSON.
|
||
- **Correct my data** — profile fields directly; anything else as a correction request.
|
||
- **Delete my account** — closes the account at once and files a deletion request.
|
||
|
||
**Bulk messages** are either an **Event update** (about an event the recipients
|
||
registered for; always sent) or **News & announcements** (only to people who opted in
|
||
on that channel and haven't unsubscribed). News emails carry an unsubscribe link and
|
||
one-click `List-Unsubscribe` headers; news WhatsApps end with "Reply STOP" and a link.
|
||
Event updates say why they were sent and link to the preferences. A STOP reply on
|
||
WhatsApp turns off WhatsApp news (through WAWP's `message` webhook, checked against a
|
||
secret in the webhook URL).
|
||
|
||
**Privacy notice** (`/legal/privacy`) — edited in **Admin → Privacy (POPIA)**
|
||
(`/dashboard/admin/privacy`): sections start from the built-in text; drafts, preview,
|
||
and published, numbered versions (earlier ones stay readable with `?version=N`).
|
||
Placeholders (`{org}`, `{ioName}`, `{ioEmail}`, `{website}`, `{orgEmail}`,
|
||
`{medicalRetentionDays}`, `{operators}`) are filled in from Site settings and the
|
||
operator register. A version marked as a significant change is accepted once by everyone
|
||
after their next login; sign-up records the version accepted. The contact page shows the
|
||
Information Officer.
|
||
|
||
**Registers and logs** (same admin page):
|
||
|
||
- **Operators** — the services that process personal information (payment, WhatsApp,
|
||
email, hosting, maps, error monitoring), what each receives and where; those in use
|
||
are listed in the notice.
|
||
- **Consent log** — news opt-ins/opt-outs, privacy notice acceptances and parental consent
|
||
answers, searchable.
|
||
- **Access log** — every bulk export or view of personal information (reports, attendance
|
||
registers, certificates, group lists, form answers, consent and medical lists, backups)
|
||
and every "view as" session, with the number of records. Children's and medical
|
||
information is flagged (medical lists, and anything about a youth event).
|
||
- **Retention** — how long each kind of personal information is kept, applied by a nightly
|
||
job: inactive accounts anonymised after 5 years (warning 30 days before; never staff
|
||
roles or people with an upcoming registration), form answers deleted 12 months after
|
||
the event, login history kept 24 months, payer details in payment notifications removed
|
||
after 24 months, audit/access logs kept 5 years. The notice's `{retention}` placeholder
|
||
lists them.
|
||
- **Breaches** — the register of security compromises, with when the Information Regulator
|
||
and the people affected were told, and drafts of both notifications.
|
||
- **Readiness** — a scored checklist of what's set up, each item linking to its fix.
|
||
|
||
**For admins** — **Data requests** (`/dashboard/admin/data-requests`): correction and
|
||
deletion requests with a 30-day due date, emailed to the Information Officer and
|
||
admins, reminded daily when due within a week. Completing a deletion anonymises the
|
||
person: name, contact details, the people they registered, form answers, consent
|
||
details, sponsor names, login history and payer details in provider notifications are
|
||
removed; payments, registrations, tickets and check-ins stay as "Deleted User". It
|
||
waits while they have a registration for an upcoming event. Everything is in the audit
|
||
log.
|
||
|
||
---
|
||
|
||
## Help system
|
||
|
||
A floating **"Need help?"** button on every page opens a page-specific guide
|
||
(tabs, quick links). Every page has dedicated content (`frontend/src/content/help/`),
|
||
falling back to a general guide.
|
||
|
||
---
|
||
|
||
## Background jobs
|
||
|
||
Timed jobs run on a job queue in Postgres (pg-boss, `backend/src/jobs/index.js`): each
|
||
runs once per schedule even with several server processes, every run is recorded,
|
||
failed runs are retried twice, and a slow run never overlaps the next. Admin → Site
|
||
Settings → Background jobs shows each job's schedule, next run and last 10 runs, with
|
||
"Run now". Times are in `APP_TIMEZONE` (default Africa/Johannesburg). Change a schedule
|
||
with `JOB_SCHEDULE_<NAME>` (cron); `JOBS_ENABLED=false` turns them all off. If the queue
|
||
can't start, the same jobs run on in-process timers.
|
||
|
||
| Job | Schedule |
|
||
|-----|----------|
|
||
| Scheduled email/WhatsApp worker | Polls every 30 s (`SCHEDULED_EMAILS_INTERVAL_MS`) and purges sent jobs after 24 h (not on the queue) |
|
||
| `daily-summary` — daily event summary email | 07:00 daily (`DAILY_SUMMARY_ENABLED=false` to disable) |
|
||
| `waitlist` — expire unclaimed offers, offer freed places | Every 10 minutes (`WAITLIST_JOB_ENABLED=false`) |
|
||
| `payment-status` — look up PayFast checkouts (10 min – 3 days old) whose notification never arrived, and record them | Every 15 minutes (`PAYMENT_STATUS_JOB_ENABLED=false`) |
|
||
| `feedback` — post-event feedback forms and their 3-day reminder | Every 15 minutes (`FEEDBACK_JOB_ENABLED=false`) |
|
||
| `sessions` — session reminders, and certificates for events that ended in the last 14 days | Every 5 minutes (`SESSION_JOBS_ENABLED=false`) |
|
||
| `volunteers` — volunteer reminders the day before a shift | Every 15 minutes (`VOLUNTEER_JOBS_ENABLED=false`) |
|
||
| `series` — email a series' followers when a new event in it goes live | Every 15 minutes (`SERIES_JOBS_ENABLED=false`) |
|
||
| `consent` — parental consent reminders, and deleting medical details after events | 09:00 daily (`CONSENT_JOBS_ENABLED=false`) |
|
||
| `privacy` — remind admins of privacy requests due within a week or overdue | 08:00 daily (`PRIVACY_JOBS_ENABLED=false`) |
|
||
| `retention` — delete/anonymise personal information past its retention period (Admin → Privacy → Retention) | 03:30 daily (`RETENTION_JOBS_ENABLED=false`) |
|
||
| `hub-heartbeat` — check in with the Cross Events Hub and pick up licence changes (only once connected) | Every 15 minutes (`HUB_HEARTBEAT_ENABLED=false`) |
|
||
| `analytics-rollup` — roll raw visit rows older than 90 days into daily totals | 04:15 daily (`ANALYTICS_ROLLUP_ENABLED=false`) |
|
||
| `backup` — database backup (`pg_dump`, gzipped, 14-day retention) | 02:00 daily (`BACKUP_ENABLED=false`) |
|
||
| `temp-cleanup` — temp files older than 7 days in `/temp` | 03:00 daily |
|
||
|
||
---
|
||
|
||
## Operations
|
||
|
||
- **Install script** (`scripts/install.sh`) — a fresh Ubuntu server to a running site: Node 20,
|
||
PostgreSQL, PM2, nginx, HTTPS, configuration, migrations and build; then `/setup`.
|
||
- **Cross Events Hub** — every install connects with a licence key (`/setup`, or Site settings →
|
||
Licence) and checks in every 15 minutes with its version, health and totals (no personal
|
||
information; income as a range). Licences are signed tokens checked on the site, so a Hub outage
|
||
never switches it off: past the end date there's a grace period (banner for site admins only),
|
||
then — or when suspended, revoked or not licensed — the site is read-only (events can't be
|
||
created or edited; no new registrations or payments; tickets still scan, data can be exported).
|
||
The site checks in 30 seconds after starting and after a licence key is connected. Admins see when an update is available, with
|
||
**what's new** in each version, and press **Request update**, which tells the provider through the Hub (the site never updates
|
||
itself). A request can be **withdrawn**. **Not now** hides the update banner until the next version; urgent updates (security or
|
||
serious bug fixes) can't be put off and show a red banner.
|
||
- **Notices from the provider** — maintenance and other messages the provider posts in the Hub show as a banner on the dashboard
|
||
for site admins and supervisors, in their time window; each can be closed (per browser) and stays listed on Site settings →
|
||
Licence. The provider can email them to the church too.
|
||
See `docs/hub-protocol.md`.
|
||
- **`/health`** — status, version, database, background jobs and last backup.
|
||
- **PM2** (`ecosystem.config.js`) runs backend and frontend, restarting either
|
||
one above 500 MB of memory.
|
||
- **Sentry** error monitoring when `SENTRY_DSN` / `NEXT_PUBLIC_SENTRY_DSN` are
|
||
set.
|
||
- Unhandled promise rejections are logged and don't crash the server.
|
||
- Backend status page (`/`) and built-in API docs page (`/docs`).
|
||
- **Tests** — Jest unit tests in `backend/tests` (`npm test`), and Playwright
|
||
end-to-end tests in `e2e/` (`npm run test:e2e`) that start their own backend and
|
||
frontend against a separate, freshly seeded database: public pages, free and paid
|
||
registration through to check-in and cashup, multi-day check-in, the attendance
|
||
register and certificates, the event wizard, the kiosk, and the admin jobs page.
|
||
- **Deploy script** — `scripts/deploy.sh [tag]`, run on the server, backs up the
|
||
database, checks out the release, migrates, builds and reloads PM2, and goes back to
|
||
the previous version if a step fails before the reload.
|
||
- Versioning via git tags and [CHANGELOG.md](./CHANGELOG.md).
|
||
|
||
---
|
||
|
||
## Page map
|
||
|
||
| Path | Who | What |
|
||
|------|-----|------|
|
||
| `/` | Public | Home |
|
||
| `/events`, `/events/[id]` | Public | Event list and detail |
|
||
| `/campus/[slug]` | Public | A campus's page and its events (while campuses are on) |
|
||
| `/series/[slug]` | Public | A series' page: upcoming and past events, Follow |
|
||
| `/[alias]` | Public | Event short link |
|
||
| `/register/[eventId]` | Public / User | Registration |
|
||
| `/registration/success` | Public / User | Confirmation, form and pay |
|
||
| `/pay/[id]` | Public | Pay online: choose a provider, or go on to PayFast |
|
||
| `/payment/success`, `/payment/failure`, `/payment/cancel` | Public | Return pages after paying online |
|
||
| `/forms` | Public / User | Attendee forms |
|
||
| `/contact`, `/legal/terms`, `/legal/privacy`, `/lockdown-rules` | Public | Info pages |
|
||
| `/login`, `/register`, `/forgot-password`, `/reset-password`, `/activate-account` | Public | Accounts |
|
||
| `/setup` | First run | Setup wizard |
|
||
| `/consent/[token]` | Parent/guardian | Give or decline parental consent |
|
||
| `/waitlist/claim/[token]` | Public | Claim a waitlist place |
|
||
| `/certificates/verify/[code]` | Public | Check a completion certificate |
|
||
| `/unsubscribe?t=…` | Public | Unsubscribe from news (link in news emails/WhatsApps) |
|
||
| `/serve/check-in?code=…` | User (logs in first) | Volunteer check-in (where the event's check-in QR code leads) |
|
||
| `/self-service` | Supervisor-unlocked | Kiosk |
|
||
| `/set-banner` | Supervisor | Site banner |
|
||
| `/dashboard/user` (+ `/payments`, `/donate`, `/forms`, `/profile`, `/privacy`, `/kids`, `/serving`, `/reset-password`) | User | My Events |
|
||
| `/dashboard/staff` (+ `/ticket-scanning`, `/event-tickets`, `/my-groups`, `/kids`, `/kids/rooms`, `/volunteers`) | Staff | Staff tools |
|
||
| `/dashboard/supervisor` (+ `/events`, `/event-options`, `/at-the-door`, `/manual`, `/manual-registration`, `/payments`, `/coupons`, `/waitlist`, `/attendance`, `/consent`, `/offline-scans`, `/allocations`, `/kids`, `/volunteers`, `/email-attendees`, `/whatsapp-attendees`, `/forms`, `/reports`) | Supervisor | Supervisor tools |
|
||
| `/dashboard/admin` (+ `/users`, `/registrations`, `/forms`, `/cashup`, `/cashup/[id]`, `/audit-log`, `/data-requests`, `/privacy`, `/settings`) | Admin | Admin tools |
|