Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Ls1vMdg2GYqbnKZmPaX1ot
1071 lines
66 KiB
Markdown
1071 lines
66 KiB
Markdown
# Cross Events — Road to 2.0.0
|
||
|
||
Planned features and platform work to take Cross Events from 1.32.x to 2.0.0.
|
||
Each section covers what the feature does, who uses it, how it fits the
|
||
existing platform, and the edge cases to handle. See [FEATURES.md](../FEATURES.md)
|
||
for what already exists, and [FEATURES-ROUND-1.md](./FEATURES-ROUND-1.md) for the
|
||
previous round (1.12.0 – 1.23.0). Where to pick up: [HANDOVER.md](./HANDOVER.md).
|
||
|
||
**Theme for 2.0:** turn a feature-rich church app into a product that can be
|
||
sold — trustworthy (POPIA), flexible (multi-day events, several payment
|
||
providers), maintainable (tests, CI, typed backend, versioned API), and with
|
||
**AI helpers** as the headline feature (§15).
|
||
|
||
**Status (2026-10-27):** all features in this document are approved. Shipped
|
||
so far: 1.32.0 early-bird ribbon on event cards; 1.33.0 multi-day events
|
||
phase A (sessions, late joining, per-session check-in, attendance register,
|
||
reminders, certificates); 1.34.0 job queue (pg-boss), Playwright E2E tests, Gitea CI
|
||
workflow (waiting for a runner) and deploy script; 1.35.0 multi-day events phase B
|
||
(pick sessions, per-session capacity), with 1.35.1 adding the per-session waitlist, the session
|
||
picker at the door and session choice on "All sessions" tickets; 1.36.0 payment provider interface
|
||
(Yoco moved behind it, Site settings → Payments); 1.37.0 PayFast and the "Pay online" page;
|
||
1.37.1 "Pay online" hidden when it can't be used; 1.37.2 payment status checks for missing
|
||
notifications. SnapScan and Zapper are dropped — Yoco and PayFast are enough (2026-10-23);
|
||
1.38.0 POPIA toolkit part 1 (privacy page, unsubscribe, WhatsApp STOP, data requests); 1.39.0 part 2 (privacy notice editor and versions, operator register, consent and access logs); 1.40.0 part 3 (retention policies and job, breach register, children’s-data flags, readiness page).
|
||
1.41.0 the Hub connection (licence, heartbeat, read-only mode, `/health`, install script) with Hub 1.0.0 (`joshua/events-hub`);
|
||
1.41.1–1.41.2 licence and job-time fixes; 1.41.3 renamed **Hope Events → Cross Events** (Hub 1.0.1:
|
||
Cross Events Hub); 1.42.0 **Request update** button instead of the deploy command, with Hub 1.1.0
|
||
(update requests); 1.42.1 the production Hub key built in. Later versions moved up by one
|
||
(2026-10-27). Multi-campus is split in two — 1.43.0 campuses, 1.44.0 campus-scoped staff — so
|
||
everything after moves up by one more (2026-10-27). 1.43.0 **campuses** shipped (settings, events
|
||
per campus, public filter and campus pages, home campus, filters, campus broadcasts and summaries);
|
||
1.44.0 **campus-scoped staff** shipped (Admin → Users "Limit to campuses", every staff route checked).
|
||
Wallet passes are removed from scope (2026-10-28), so everything after volunteer rosters moves
|
||
up by one. 1.45.0 **kids check-in** shipped (fully digital: pickup codes, sticker panel, rooms with
|
||
ratios, offline desk). 1.46.0 **volunteer rosters** shipped (roles per event or session, sign-ups and
|
||
assigning, swaps on accept, QR self check-in, kids-room roles on duty, optional volunteer ticket).
|
||
Event series and cloning ships as 1.47.0–1.47.3 (2026-10-28); 1.47.0 **copy an event** and 1.47.1 **event series** (series page, Next in this series, follow) 1.47.2 **year-on-year
|
||
report** and 1.47.3 **season passes** shipped — §6 is done. 1.48.0 **outbound webhooks** shipped. 1.49.0 **dashboard (Today, Waiting for you) and Ctrl+K palette**
|
||
shipped; 1.49.1 **bulk actions** and 1.49.2 **saved filters** shipped — §9 is done. Languages
|
||
(Afrikaans) are removed from scope (2026-10-28), so everything after moves up by one. 1.50.0 **accessibility
|
||
pass** shipped. 1.50.1 **pagination and search on long lists** and 1.50.2 **event picker and webhook guide** shipped. **Next: 1.51.0 TypeScript
|
||
backend / `/api/v2`.**
|
||
|
||
**Repositories:**
|
||
|
||
| Repo | What |
|
||
|------|------|
|
||
| `joshua/hope-events` (this repo) | The church app. Everything in this document except the Hub app itself — including the Hub *client* (licence step, "Connect to Hub", heartbeat, licence checks) |
|
||
| `joshua/events-hub` (new) | The Hub app (§13): its own versions, CHANGELOG, releases and server |
|
||
|
||
---
|
||
|
||
## Contents
|
||
|
||
1. [Multi-day events (sessions)](#1-multi-day-events-sessions) ← **first**
|
||
2. [Payment providers: PayFast](#2-payment-providers-payfast)
|
||
3. [POPIA toolkit](#3-popia-toolkit)
|
||
4. [Kids check-in (digital pickup codes)](#4-kids-check-in-digital-pickup-codes)
|
||
5. [Volunteer / serving rosters](#5-volunteer--serving-rosters)
|
||
6. [Event series and cloning](#6-event-series-and-cloning)
|
||
7. ~~[Apple and Google Wallet tickets](#7-apple-and-google-wallet-tickets)~~ — removed from scope
|
||
8. [Outbound webhooks](#8-outbound-webhooks)
|
||
9. [Admin dashboard, command palette, bulk actions](#9-admin-dashboard-command-palette-bulk-actions)
|
||
10. ~~[Languages (Afrikaans first)](#10-languages-afrikaans-first)~~ — removed from scope
|
||
11. [Accessibility pass (WCAG 2.2 AA)](#11-accessibility-pass-wcag-22-aa)
|
||
12. [Multi-campus (one install per church)](#12-multi-campus-one-install-per-church)
|
||
13. [Central management platform (Cross Events Hub)](#13-central-management-platform-cross-events-hub)
|
||
14. [Foundations (platform work)](#14-foundations-platform-work)
|
||
15. [AI helpers (2.0 headline)](#15-ai-helpers-20-headline)
|
||
16. [AI: later stages](#16-ai-later-stages)
|
||
17. [Suggested build order](#suggested-build-order)
|
||
18. [Decisions](#decisions-2026-10-22)
|
||
|
||
---
|
||
|
||
## 1. Multi-day events (sessions)
|
||
|
||
One event that runs over several dates, e.g. **"Alpha Course — every Wednesday
|
||
18:30–20:30 for 5 weeks"**, a 3-day conference, or a camp with an evening
|
||
session each day. People register and pay **once**, get **one ticket**, and are
|
||
checked in **per session**.
|
||
|
||
> Not the same as [Event series](#6-event-series-and-cloning). A series groups
|
||
> *separate* events (Camp 2026, Camp 2027) that each have their own
|
||
> registrations. Sessions are dates *inside one* event.
|
||
|
||
**Who:** Supervisors set up the schedule. Users see it on the event page, in
|
||
their tickets and in their calendar. Staff check in per session.
|
||
|
||
### Event setup
|
||
|
||
New **Schedule** section on the event form:
|
||
|
||
| Setting | Options |
|
||
|---------|---------|
|
||
| Schedule type | Single date (today's behaviour) · Multiple sessions |
|
||
| Pattern builder | Repeat **daily / weekly / every N weeks** on chosen weekday(s), start date, time from–to, **number of sessions** or **until date** |
|
||
| Generated sessions | Editable list: change date/time/location/label of any one session, delete, or add an extra one-off date |
|
||
| Session label | Optional, e.g. "Week 1 — Is there more to life?" (defaults to "Session 1, 2, …") |
|
||
| Session location | Optional; falls back to the event location |
|
||
| Attendance mode | **Whole course** (one registration covers all sessions) · **Pick sessions** (see phase B below) |
|
||
| Late joining | Per event: Off (registration closes when the first session starts) · Allow until the start of session N |
|
||
| Late-joiner price | Per event, only when late joining is on: Full price · **Pro-rata** (price × remaining sessions ÷ total sessions, rounded to the **nearest R10**, e.g. R183 → R180, R185 → R190) · Fixed late price |
|
||
| Check-in window | Per event: **Whole day** (default — any time on the session's date, in case someone was let in without being scanned) · Session time only (2 h before start until the session ends) |
|
||
| Session reminders | Per event, **off by default**: when on, choose timing (e.g. 3 h before, the day before at 18:00, or both) and channels (email / WhatsApp) |
|
||
| Certificates | Per event, **off by default**: when on, choose a template and the completion rule (see [Certificates](#certificates)) |
|
||
|
||
The pattern builder is only a helper: it generates rows, then the session list
|
||
is the source of truth. Typing "every Wednesday for 5 weeks" and then skipping
|
||
a public holiday is just deleting one row.
|
||
|
||
### How it works
|
||
|
||
- `Event.startDate` / `endDate` **stay** and are kept in sync automatically
|
||
(first session start, last session end). Everything that already reads them —
|
||
consent age checks, transfer cut-off, early-bird, feedback timing, ICS,
|
||
listings, sitemap — keeps working unchanged. Only places that need
|
||
per-session behaviour are updated.
|
||
- **Public event page:** shows the full schedule, with past sessions greyed out
|
||
and a "Next session" highlight. Event cards show "5 sessions · Wed 4 Nov –
|
||
Wed 2 Dec".
|
||
- **Event listings:** a multi-session event stays "upcoming / running" until
|
||
its **last** session ends, and sorts by its **next** session.
|
||
- **Tickets (PDF, email, WhatsApp):** list all session dates. One QR code.
|
||
- **Calendar (ICS):** one VEVENT per session (not an RRULE, so edited or
|
||
skipped sessions are exact).
|
||
- **Check-in:** the scanner auto-selects today's session (on a day with more
|
||
than one session, the one happening now or next), with a dropdown to
|
||
override. Whether a scan is accepted depends on the event's **check-in
|
||
window** (whole day or session time only). A ticket can be checked in
|
||
**once per session** (per person for group tickets). Scanning again in the
|
||
same session shows "Already checked in for Session 3 at 18:42".
|
||
- **Manual check-in:** supervisors can tick someone as present for a session
|
||
from the attendance register afterwards (e.g. let in without a scan), logged
|
||
in the audit log with who marked it.
|
||
- **Reminders:** off by default; when switched on for the event, a reminder
|
||
goes out before **each** session (email/WhatsApp, via the scheduled-message
|
||
worker), e.g. "See you tonight at 18:30".
|
||
- **Late joiners:** when late joining is on, the registration page shows which
|
||
sessions are left and the late price ("3 of 5 sessions left — R180").
|
||
- **Changes:** moving or cancelling a session after people registered prompts
|
||
the supervisor to notify registrants (pre-filled broadcast), and updates the
|
||
ICS/tickets.
|
||
|
||
### Phase B: pick sessions (drop-in)
|
||
|
||
Second step, released separately. Lets people register for **some** sessions,
|
||
e.g. a conference where each day is sold separately or a weekly drop-in class.
|
||
|
||
- Ticket options can be scoped to sessions: "Day pass (pick days)" priced per
|
||
session, "Full conference pass" covering all.
|
||
- Optional **capacity per session** on top of the option stock limit.
|
||
- The ticket stores which sessions it covers; scanning on a session it doesn't
|
||
cover shows "Not registered for this session" (with "Add & charge" at the
|
||
door for supervisors).
|
||
- Waitlist works per session when sessions have their own capacity.
|
||
|
||
### Reporting
|
||
|
||
- **Attendance register:** grid of attendees × sessions with ticks, totals per
|
||
session, attendance % per person. Export to Excel and PDF.
|
||
- **Completion filter:** "attended at least 4 of 5" — useful for certificates
|
||
and for follow-up ("missed the last 2 weeks").
|
||
- Daily summary email includes "Sessions today".
|
||
- Funnel stats unchanged (they are per event).
|
||
|
||
### Certificates
|
||
|
||
Optional completion certificates (PDF), chosen per event.
|
||
|
||
- **3–4 built-in templates**, e.g. *Classic* (border, serif), *Modern* (clean,
|
||
accent colour bar), *Church* (logo-led, scripture line), *Kids* (playful,
|
||
for children's programmes). All use the site logo and brand colour from Site
|
||
settings.
|
||
- **Event settings:** Certificates on/off · Template · Title ("Certificate of
|
||
Completion") · Body text with placeholders (`{name}`, `{event}`,
|
||
`{sessionsAttended}`, `{totalSessions}`, `{endDate}`) · Signature name and
|
||
role (optional uploaded signature image) · **Completion rule**: attended at
|
||
least N sessions or N % (default: all sessions).
|
||
- **Preview** button in the event form renders a sample PDF.
|
||
- **Who gets one:** attendees meeting the completion rule after the last
|
||
session. Supervisors can issue/withdraw one manually (audit logged).
|
||
- **Delivery:** download from My Events, bulk download (ZIP) from the
|
||
attendance register, and optional email/WhatsApp send.
|
||
- Each certificate has a short verification code + QR linking to a public
|
||
"certificate valid" page (name, event, date only).
|
||
- Generated with `pdfkit`, like tickets and receipts (`utils/pdfDocs.js`).
|
||
- Also usable on single-date events (completion = checked in).
|
||
|
||
### Edge cases
|
||
|
||
| Case | Behaviour |
|
||
|------|-----------|
|
||
| Delete a session that has check-ins | Blocked; offer **Cancel session** instead (kept for history, hidden from schedule, excluded from attendance %) |
|
||
| Switch Multiple → Single after registrations | Allowed only if no session check-ins exist |
|
||
| Ticket transfer | Allowed until the **first** session starts (current rule). Optional later: allow mid-course transfers with check-in history kept on the original holder |
|
||
| Parental consent | Age is measured at the first session (current `startDate` rule) |
|
||
| Medical details deletion | Runs after the **last** session (end date), as today |
|
||
| Feedback form | Sent after the last session |
|
||
| Cashup | Still per event. At-the-door cash per session is captured with the session on the payment so reports can split it |
|
||
| Offline scanning | Session list and per-session usages are part of the offline lock bundle; sync keeps the session id per scan |
|
||
| Timezones | Sessions stored as UTC instants, same as `Event.startDate` today (see `icsUtils.js`) |
|
||
| Session overlaps / out of order | Allowed (conferences have parallel tracks later), list always sorted by start |
|
||
| Kiosk / At the door | Shows the current session; check-in counts against it |
|
||
|
||
### Data model (sketch)
|
||
|
||
```prisma
|
||
enum ScheduleType { single sessions }
|
||
enum AttendanceMode { whole pick }
|
||
|
||
enum LatePricing { full prorata fixed }
|
||
enum CheckInWindow { whole_day session_only }
|
||
|
||
model Event {
|
||
// ...existing fields
|
||
scheduleType ScheduleType @default(single)
|
||
attendanceMode AttendanceMode @default(whole)
|
||
lateJoinEnabled Boolean @default(false)
|
||
lateJoinUntilSessionId String?
|
||
latePricing LatePricing @default(full)
|
||
lateFixedPrice Float?
|
||
checkInWindow CheckInWindow @default(whole_day)
|
||
sessionReminders Json? // null = off; { offsets: [...], channels: [...] }
|
||
certificatesEnabled Boolean @default(false)
|
||
certificateConfig Json? // template, title, body, signature, completion rule
|
||
sessions EventSession[]
|
||
certificates Certificate[]
|
||
}
|
||
|
||
model Certificate {
|
||
id String @id @default(uuid())
|
||
eventId String
|
||
attendeeId String?
|
||
userId String?
|
||
name String
|
||
code String @unique // verification code
|
||
manual Boolean @default(false)
|
||
issuedAt DateTime @default(now())
|
||
revokedAt DateTime?
|
||
event Event @relation(fields: [eventId], references: [id], onDelete: Restrict)
|
||
|
||
@@index([eventId])
|
||
}
|
||
|
||
model EventSession {
|
||
id String @id @default(uuid())
|
||
eventId String
|
||
label String?
|
||
startsAt DateTime
|
||
endsAt DateTime
|
||
location String?
|
||
capacity Int? // phase B
|
||
cancelledAt DateTime?
|
||
order Int @default(0)
|
||
event Event @relation(fields: [eventId], references: [id], onDelete: Cascade)
|
||
usages TicketUsage[]
|
||
ticketSessions TicketSession[]
|
||
|
||
@@index([eventId, startsAt])
|
||
}
|
||
|
||
model TicketUsage {
|
||
// ...existing fields
|
||
sessionId String? // null on single-date events
|
||
session EventSession? @relation(fields: [sessionId], references: [id], onDelete: Restrict)
|
||
@@index([sessionId])
|
||
}
|
||
|
||
// Phase B only: which sessions a "pick sessions" ticket covers.
|
||
model TicketSession {
|
||
ticketId String
|
||
sessionId String
|
||
@@id([ticketId, sessionId])
|
||
}
|
||
```
|
||
|
||
`Ticket.isUsed` keeps its meaning for single-date events. For session events
|
||
it's not used for check-in decisions; "checked in" is per session
|
||
(`TicketUsage.sessionId`).
|
||
|
||
### Plumbing
|
||
|
||
- Session CRUD + pattern generator in `backend/src/utils/sessions.js` with
|
||
Jest tests (DST-free but still test month boundaries, skipped dates, "until"
|
||
vs "count").
|
||
- Scan endpoint takes an optional `sessionId`; defaults to the current session.
|
||
- Help content, audit log entries (session created/moved/cancelled),
|
||
CHANGELOG, FEATURES.md, SETTINGS.md.
|
||
|
||
---
|
||
|
||
## 2. Payment providers: PayFast
|
||
|
||
Add **PayFast** next to Yoco, and let the admin **enable one or both** in Site
|
||
settings. At checkout the user picks from the enabled ones. (Shipped in
|
||
1.36.0–1.37.2. SnapScan and Zapper were planned too, but dropped on 2026-10-23:
|
||
two providers are enough.)
|
||
|
||
**Who:** Admins configure providers. Users choose at payment. Supervisors
|
||
reconcile.
|
||
|
||
### Site settings → Payments
|
||
|
||
| Setting | Options |
|
||
|---------|---------|
|
||
| Providers | Yoco · PayFast — each with an **Enabled** toggle |
|
||
| Credentials | Per provider (merchant id/key, API key, passphrase, webhook secret…), stored encrypted (`utils/encryption.js`, same as WhatsApp) |
|
||
| Mode | Live / Sandbox per provider (where supported) |
|
||
| Display order / default | Which one is shown first. Default order: Yoco · PayFast |
|
||
| Minimum amount | **R15 for all providers** (one site-wide minimum for online payments) |
|
||
|
||
**Fees are not handled automatically.** Payments are recorded at the full
|
||
amount paid; provider fees are not deducted, estimated or added to the payer's
|
||
total. Fees are dealt with by people during **cashup**, as today. There is no
|
||
"pass fee to payer" option.
|
||
|
||
"Test connection" button per provider, like the WhatsApp setup.
|
||
|
||
### How it works
|
||
|
||
- A single **PaymentProvider interface** in the backend:
|
||
`createCheckout`, `handleWebhook` (verify signature → mark paid),
|
||
`getTransaction`, `refund` (if the provider supports it via API),
|
||
`listTransactions` (for reconciliation).
|
||
- Yoco is moved behind the same interface first (no behaviour change), then
|
||
PayFast is added.
|
||
- `Payment.method` gets the provider name; `YocoTransaction` is generalised to
|
||
`ProviderTransaction` (`provider` column) so the existing reconciliation page
|
||
works for all providers.
|
||
- Refunds: if the provider has no refund API, the supervisor refunds in the
|
||
provider's portal and records it here (existing manual refund flow).
|
||
|
||
### Edge cases
|
||
|
||
- Provider disabled while a checkout is in progress → webhook still accepted
|
||
and processed.
|
||
- Duplicate / late webhooks → idempotent on the provider's transaction id.
|
||
- Webhook never arrives → "Check payment status" button and a periodic
|
||
reconcile job.
|
||
- Amount mismatch (user edits amount in app) → payment held as "needs review".
|
||
- Only enabled providers appear in kiosk / self-service.
|
||
- Amount below R15 → online payment options hidden, with a message to pay at
|
||
the door / contact the organiser.
|
||
- **Before building each one:** get the documentation links from Joshua and
|
||
confirm current API docs for webhooks, sandbox, refunds and QR deep-link
|
||
support.
|
||
|
||
---
|
||
|
||
## 3. POPIA toolkit
|
||
|
||
Tools that make the platform **POPIA-ready** out of the box. This is the main
|
||
selling point for other churches and organisations: "your attendee data is
|
||
handled properly, and you can prove it."
|
||
|
||
> This is tooling to support compliance, not legal advice. Wording and
|
||
> retention periods should be checked by whoever is the customer's
|
||
> Information Officer.
|
||
|
||
**Who:** Admins (and the appointed Information Officer) manage it. Users get
|
||
self-service privacy tools.
|
||
|
||
### For users (data subjects)
|
||
|
||
- **Privacy centre** in My account:
|
||
- **Download my data** — JSON + readable PDF of profile, registrations,
|
||
payments, tickets, form answers, consents, messages sent.
|
||
- **Correct my data** — edit profile; request correction of locked records.
|
||
- **Delete my account** — creates a deletion request (see below).
|
||
- **Communication preferences** — email / WhatsApp / marketing opt-in with
|
||
timestamps (extends the existing notification preferences).
|
||
- **Unsubscribe link** in every bulk email and an opt-out keyword for bulk
|
||
WhatsApp. Opted-out users are skipped automatically in broadcasts.
|
||
- **Privacy notice acceptance** — versioned; users accept the current version
|
||
at registration, and are asked again when it changes.
|
||
|
||
### For admins
|
||
|
||
| Tool | What it does |
|
||
|------|--------------|
|
||
| Information Officer | Name, contact details, shown on privacy notice and contact page |
|
||
| Privacy notice editor | Versioned text, published version history |
|
||
| Consent log | Who consented to what, when, which notice version, how (web, kiosk, WhatsApp) |
|
||
| Data requests inbox | Access, correction and deletion requests with status, due dates and audit trail |
|
||
| Deletion workflow | Admin approves → personal info is **anonymised**; financial records kept (amounts, dates) but unlinked from the person, as tax law requires them to be kept |
|
||
| Retention policies | Per data category (inactive accounts, form answers, medical details, analytics, audit log, backups): keep for N months, then anonymise/delete via nightly job. Sensible defaults shipped |
|
||
| Operator register | List of third parties that process data (Yoco/PayFast/…, WhatsApp provider, email provider, Sentry, hosting) with purpose; feeds the privacy notice |
|
||
| Access log | Who exported or viewed personal data in bulk (exports, attendee lists, medical details) |
|
||
| Breach register | Record a security compromise, affected users, actions taken; templates for notifying users and the Information Regulator |
|
||
| Children's data | Already covered by parental consent; flagged as special/children's info in reports |
|
||
| POPIA readiness page | Checklist with score: officer set, notice published, retention set, operators listed, unsubscribe working… |
|
||
|
||
### Edge cases
|
||
|
||
- Deletion of a user with an open registration / upcoming event → request
|
||
waits until after the event, or the admin cancels and refunds first.
|
||
- Anonymised users still count in historic reports ("Deleted user").
|
||
- Backups contain deleted data until they age out — stated in the notice;
|
||
backup retention is one of the retention policies.
|
||
- Impersonation and exports must be logged in the access log.
|
||
|
||
---
|
||
|
||
## 4. Kids check-in (digital pickup codes)
|
||
|
||
A secure check-in/check-out flow for children's ministry, run from a **staff desk**.
|
||
**Builds on sessions (§1), attendees, allocation groups and campuses (§12).** Fully digital —
|
||
no label printers (2026-10-28).
|
||
|
||
**Who:** Kids-ministry staff at the check-in desk and in the rooms. Supervisors set up rooms.
|
||
Parents manage their family's children in My account and see pickup codes on their phone.
|
||
|
||
### How it works
|
||
|
||
- **Families and children are kept between events** (weekly kids church): a family has one or
|
||
more parent accounts, its children (name, date of birth, allergies, medical notes, custody
|
||
notes — the last three encrypted) and **authorised adults** (name, phone, relationship — no
|
||
account needed). Parents manage them under My account → Kids; staff can find a family by
|
||
phone, name or the parent's QR code and add a family or child on the spot.
|
||
- An event gets a **Kids check-in** switch (single events or one session per Sunday). The first
|
||
check-in makes a free registration under the parent with an attendee and ticket per child, and
|
||
each check-in writes a `TicketUsage`, so the attendance register, reports and campus scoping work
|
||
as they do for tickets.
|
||
- Each check-in gets a **pickup code** (4 characters, no 0/O/1/I, unique per event and day). The
|
||
parent sees it live on their phone (code + QR) and gets it by WhatsApp/email; it can also be
|
||
sent to an authorised adult. **Anyone with the code can collect** the child.
|
||
- **"Write on the sticker" panel** on the desk screen: first name, room, code and a short alert
|
||
(ALLERGY / MEDICAL) in large print, for volunteers to copy onto a blank sticker. The full
|
||
details stay on screen.
|
||
- **Rooms** are a "Kids rooms" allocation set: each room has an age range, capacity and a
|
||
**ratio** (children per leader). The room is suggested from the child's age. Room screens show
|
||
live cards (name, code, allergy/medical icons, custody notes) and counts: children in, leaders
|
||
on duty ("I'm on duty"), over-ratio and full warnings.
|
||
- **Check-out** by scanning the parent's QR or typing the code; the leader records who collected.
|
||
A wrong code alerts the room and is logged; "Override" needs a reason.
|
||
- **Page a parent:** "Call parent" → WhatsApp (email fallback) and a notice on the parent's page.
|
||
|
||
### Plumbing / edge cases
|
||
|
||
- Medical and custody notes: room leaders, supervisors and admins only; never in messages;
|
||
room lists showing them are written to the access log.
|
||
- POPIA: families and children in `anonymiseUser` / `exportUserData`; retention rule — a child's
|
||
profile is deleted after **6 months** without a check-in; readiness flags children's data.
|
||
- Offline: the desk caches the event's families and checks in offline (device-prefixed codes,
|
||
synced later). Check-out offline only for children checked in on the same device.
|
||
- Audit log: overrides, wrong codes and custody-note changes.
|
||
|
||
---
|
||
|
||
## 5. Volunteer / serving rosters
|
||
|
||
Plan who serves where, for an event or each session. (Shipped in 1.46.0 — decisions below.)
|
||
|
||
- **Serving roles** per event/session: Welcome, Parking, Kids, Sound, Kitchen…
|
||
with the number of people needed.
|
||
- Volunteers **sign up** for open slots, or supervisors **assign** people.
|
||
- Reminders via email/WhatsApp before their slot; "can't make it" → swap
|
||
request to others in the role.
|
||
- **Volunteer check-in** on the day (separate from attendee check-in).
|
||
- Volunteers can get a free/discounted ticket automatically (uses coupons/comp).
|
||
- Reports: roster sheet per session, fill rate, hours served per person.
|
||
|
||
---
|
||
|
||
## 6. Event series and cloning
|
||
|
||
Four releases, one per part (2026-10-28): **1.47.0** clone, **1.47.1** series, **1.47.2**
|
||
year-on-year reports, **1.47.3** season pass.
|
||
|
||
- **Clone event (1.47.0 ✅):** "Copy" opens the **New event popup filled in** from the source, so
|
||
everything can be changed before saving: options, variants, early-bird tiers, form, consent
|
||
text, feedback form, sections, notification recipients, certificates, reminders, allocation
|
||
groups, cost template (admins) and sessions. A "New start" moves every date with it. Of the
|
||
newer features only the **campus** is copied — not kids check-in or volunteer roles. No
|
||
registrations, **no coupons**.
|
||
- **Series (1.47.1 ✅):** group separate events (Camp 2025, Camp 2026; monthly Men's
|
||
Breakfast) on one series page, with "Next in this series" and a series
|
||
follow/notify option. **A series can span several campuses.** Following is **News &
|
||
announcements** (opted-in only, unsubscribe link); followers get one email when a new event in the
|
||
series goes live.
|
||
- **Year-on-year reports (1.47.2 ✅):** registrations, income and attendance compared
|
||
across events in a series.
|
||
- **Season pass (1.47.3 ✅):** a bundle across events in a series. One checkout registers the buyer at
|
||
every event on the pass; the supervisor picks the events (and ticket at each); the price is split
|
||
in proportion to the events' normal prices for each event's cashup (2026-10-28).
|
||
|
||
---
|
||
|
||
## 7. Apple and Google Wallet tickets
|
||
|
||
> **Removed from scope (2026-10-28).** Kept here for reference only; not planned for 2.0.
|
||
|
||
- "Add to Apple Wallet" / "Add to Google Wallet" buttons next to the PDF
|
||
ticket, in email and in My Events.
|
||
- Pass shows event, date (next session for multi-day), location, holder name,
|
||
QR code.
|
||
- Passes **update** when the event/session changes (time, venue, cancelled).
|
||
- Requires an Apple Developer account (pass signing certificate) and a Google
|
||
Wallet issuer account; both configured in Site settings and **optional** —
|
||
hidden when not configured.
|
||
|
||
---
|
||
|
||
## 8. Outbound webhooks
|
||
|
||
Let other systems react to what happens in Cross Events. (Shipped in 1.48.0: Site settings →
|
||
Webhooks; events noticed through a Prisma client extension; each endpoint added to the operator
|
||
register; deliveries kept 30 days.)
|
||
|
||
- Admin adds endpoints and picks events: `registration.created`,
|
||
`registration.paid`, `registration.cancelled`, `payment.refunded`,
|
||
`ticket.checked_in`, `user.created`, `event.published`…
|
||
- Payloads signed with HMAC (secret per endpoint), retries with back-off,
|
||
delivery log with "Resend".
|
||
- Enables integrations (ChurchSuite, Planning Center, Google Sheets via
|
||
Zapier/Make) without building each one. Native integrations can follow later.
|
||
|
||
---
|
||
|
||
## 9. Admin dashboard, command palette, bulk actions
|
||
|
||
Three releases (2026-10-28): **1.49.0** dashboard (Today, Waiting for you) and the Ctrl+K command
|
||
palette ✅; **1.49.1** bulk actions ✅; **1.49.2** saved filters ✅.
|
||
|
||
- **Dashboard** as supervisors' home: today's events/sessions, check-ins so
|
||
far, money in (today/week), pending items (unreconciled payments, consent
|
||
outstanding, waitlist offers, data requests), alerts.
|
||
- **Command palette (Ctrl+K):** jump to any event, user, registration,
|
||
ticket or setting; quick actions ("New event", "Find payment R450").
|
||
- **Bulk actions** on registration/attendee lists: message, export, mark
|
||
paid, move option, cancel, allocate.
|
||
- **Saved filters** per user on list pages.
|
||
|
||
---
|
||
|
||
## 10. Languages (Afrikaans first)
|
||
|
||
> **Removed from scope (2026-10-28).** Kept here for reference only; not planned for 2.0.
|
||
|
||
- i18n framework on the frontend (e.g. `next-intl`); English + Afrikaans.
|
||
- User language preference; emails, WhatsApp messages and PDFs sent in the
|
||
user's language, with per-language templates.
|
||
- Event content stays as typed by the supervisor (optional translated title /
|
||
description fields later).
|
||
|
||
---
|
||
|
||
## 11. Accessibility pass (WCAG 2.2 AA)
|
||
|
||
- Audit public pages, registration, payment, My Events and the kiosk.
|
||
- Keyboard navigation, focus states, labels, colour contrast (light and
|
||
dark), screen-reader names for icon buttons, error messages linked to
|
||
fields.
|
||
- Automated `axe` checks in the Playwright suite so it doesn't regress.
|
||
|
||
**Shipped in 1.50.0** for the pages above. The app has no dark mode, so only the light theme is
|
||
checked. Staff/supervisor/admin screens are left for when they're next worked on (see HANDOVER).
|
||
|
||
---
|
||
|
||
## 12. Multi-campus (one install per church)
|
||
|
||
**Decision: one install per church.** Each customer gets their own install
|
||
and database (the `/setup` wizard already makes this possible). This gives
|
||
full data separation — which also helps the POPIA story — and lets each
|
||
church run on a different server. **True multi-tenant is out of scope.**
|
||
|
||
**Multi-campus** is in scope: one church with several campuses inside one
|
||
install. It ships in **two releases** (2026-10-27):
|
||
|
||
| Release | What | Why separate |
|
||
|---------|------|--------------|
|
||
| **1.43.0 Campuses** | Campuses in Site settings, events per campus, public filter and `/campus/<slug>` pages, home campus, campus on cards and tickets, campus filters on reports/cashup/dashboard/funnel, "everyone at campus X" messages, per-campus summary recipients | Adds features and filters; who can see what doesn't change |
|
||
| **1.44.0 Campus-scoped staff** | Supervisors and staff limited to campuses, across every staff/supervisor endpoint (115 in 27 route files at 1.42.1) and their dashboards | Security-heavy: anything missed lets staff see another campus's data, so it gets its own release and testing |
|
||
|
||
### Setup
|
||
|
||
- Site settings → **Campuses**: off by default. When on, admins add campuses
|
||
(name, address, contact, optional logo/colour accent, default location for
|
||
events).
|
||
- Single-campus churches never see campus fields anywhere.
|
||
|
||
### How it works
|
||
|
||
- **Events** belong to one campus, or to **All campuses** (church-wide
|
||
conferences, camps).
|
||
- **Public site:** campus filter on the events list, remembered per visitor;
|
||
campus shown on event cards and tickets. Campus landing pages
|
||
(`/campus/<slug>`) are part of 1.43.0.
|
||
- **Users** can set a home campus (used as the default filter and for
|
||
broadcasts). Accounts stay shared across campuses — one login for the
|
||
church.
|
||
- **Campus-scoped roles (1.44.0):** a supervisor or staff member can be limited to
|
||
one or more campuses (sees and manages only those events, registrations,
|
||
scanning, cashups). Admins and unscoped supervisors see everything.
|
||
**"All campuses" events:** scoped staff can view and scan them; only admins
|
||
and unscoped supervisors can edit them.
|
||
- **Reports, cashup, dashboard, funnel stats:** filter by campus plus a
|
||
church-wide total. (Report PDFs/Excel are rendered from data the page sends,
|
||
so the filters go on the data endpoints.)
|
||
- **Broadcasts:** target "everyone at campus X" — people whose home campus is X,
|
||
plus (tick box) people registered for campus X's events in the last 12 months.
|
||
Still filtered by news consent.
|
||
- **Kids check-in rooms** and **volunteer roles** are per campus.
|
||
- **Notification recipients** per campus (e.g. the campus pastor gets that
|
||
campus's daily summary).
|
||
|
||
### Edge cases
|
||
|
||
- Turning campuses off with campus data present → hidden, not deleted.
|
||
- Deleting a campus with events → blocked; archive instead.
|
||
- Moving an event to another campus → scoped supervisors of the old campus
|
||
lose access; logged in the audit log.
|
||
|
||
### Plumbing (1.44.0)
|
||
|
||
- Today access depends only on role — nothing limits staff to particular
|
||
events — so scoping is a new layer: one helper (`utils/campusScope.js`) that
|
||
works out a user's campuses once per request, gives a `where` for event lists
|
||
and checks single records (registrations, tickets, payments… traced back to
|
||
their event).
|
||
- A test lists **every** staff/supervisor route and fails unless each is
|
||
campus-checked or explicitly marked campus-independent (the same pattern as
|
||
the read-only route test), so new endpoints can't skip the check.
|
||
- The heartbeat's `features.campuses` / `stats.campuses` report the real setting
|
||
(hard-coded `false` until 1.43.0).
|
||
- **How each kind of endpoint is checked:** event id in the URL → a route middleware
|
||
(`scopeEvent`); a record that belongs to an event (registration, ticket/QR, waitlist
|
||
entry, option, bundle, allocation set…) → traced back to its event, same check;
|
||
lists across events → the controller adds the scope `where` (route marked so the
|
||
test knows); an event named in the body → checked before saving; nothing to do with
|
||
an event → allowed or unscoped-only, listed with a reason.
|
||
- **Rules (decided 2026-10-27):**
|
||
- Admins are never scoped. Scoped supervisors and staff see their campuses' events
|
||
plus "All campuses" events.
|
||
- "All campuses" events: scoped staff can view, scan, take payments at the door and
|
||
do manual registrations; event setup, options, bundles, cashup and refunds stay with
|
||
admins and unscoped supervisors.
|
||
- Site banner, payment-provider reconciliation and donations not linked to an event:
|
||
admins and unscoped supervisors only. Ad-hoc broadcasts: scoped supervisors only to
|
||
their campuses' audiences and their events' attendees. Coupons: only for their
|
||
campuses' events.
|
||
- Another campus's records answer "not found" (nothing leaks); the scanner instead
|
||
says which campus the ticket is for.
|
||
- While campuses are off, scopes are ignored (everyone sees everything); the Campuses
|
||
tab warns which staff are limited before turning campuses off.
|
||
- Scopes are set by admins in Admin → Users ("Limit to campuses"); changes are audited
|
||
(`user_campus_scope_changed`).
|
||
|
||
### Data model (sketch)
|
||
|
||
```prisma
|
||
model Campus {
|
||
id String @id @default(uuid())
|
||
name String
|
||
slug String @unique
|
||
address String?
|
||
contactName String?
|
||
contactEmail String?
|
||
contactPhone String?
|
||
colour String?
|
||
logoUrl String?
|
||
defaultLocation String?
|
||
order Int @default(0)
|
||
archivedAt DateTime? // archive instead of delete when it has events
|
||
events Event[]
|
||
notifyRecipients User[] // daily summary for this campus's events
|
||
}
|
||
// Event.campusId String? (null = all campuses) — 1.43.0
|
||
// User.homeCampusId String? — 1.43.0
|
||
// AppSetting campuses_enabled — 1.43.0
|
||
// UserCampusScope { userId, campusId } — empty = unscoped — 1.44.0
|
||
```
|
||
|
||
### Running many installs
|
||
|
||
Because every church is a separate install, a few tools make that manageable:
|
||
|
||
- **Install script:** fresh server → Node, Postgres, PM2, reverse proxy,
|
||
`.env`, migrations, then `/setup` in the browser.
|
||
- **Update script:** pull a tagged version, back up the database, run
|
||
migrations, build, restart; roll back on failure.
|
||
- **Version and health:** current version shown in admin and on a `/health`
|
||
endpoint (version, DB, jobs, last backup), reported to the
|
||
[Hub](#13-central-management-platform-cross-events-hub).
|
||
|
||
---
|
||
|
||
## 13. Central management platform (Cross Events Hub)
|
||
|
||
A separate app, run by Joshua, to see and manage **every Cross Events
|
||
install** from one place: who the customers are, which version each runs,
|
||
whether they're healthy, basic usage stats, and their **licence** status.
|
||
|
||
**Who:** Joshua (and any future support staff). Customers never log in to it.
|
||
|
||
### Separate app, separate repo, separate server
|
||
|
||
- **Its own git repository:** `joshua/events-hub` (https://c-git.crosscode.co.za/joshua/events-hub.git) on the same Gitea
|
||
server (c-git.crosscode.co.za), with its own semver tags, CHANGELOG and
|
||
deploys. It is never shipped to churches, so none of its code (customers,
|
||
licence signing key, other churches' data) ends up on a customer's server.
|
||
- Same stack (Next.js + Express + Prisma + Postgres) so it's familiar.
|
||
- **What lives where:**
|
||
- Hub repo: dashboard, customers, licences, licence **signing** (private
|
||
key — only ever on the Hub server), `/api/installs/register`,
|
||
`/api/installs/heartbeat` and `/api/installs/update-request` endpoints, alerts.
|
||
- Cross Events repo: the Hub **client** — licence step in `/setup`,
|
||
"Connect to Hub" in Site settings, heartbeat job, licence verification
|
||
with the Hub's **public** key, read-only mode, banners, "Request update".
|
||
- **The contract between them** (register / heartbeat payloads, licence token
|
||
format) is versioned with a `protocolVersion` field and documented in both
|
||
repos (`docs/hub-protocol.md`). The Hub accepts the current and previous
|
||
protocol version, so churches on older versions keep reporting while they
|
||
wait to update.
|
||
- Runs on its own server at **`events-hub.crosscode.co.za`**. If the Hub is
|
||
down, **no church install is affected**.
|
||
- **Licence keys are generated by the Hub:** Joshua clicks "Generate" on a
|
||
customer and the Hub creates the key (not typed by hand).
|
||
- Hope Family Church's own site is the first registered install.
|
||
|
||
### Registration (setup → Hub)
|
||
|
||
1. The `/setup` wizard gets a **Licence** step: the customer enters the
|
||
**licence key** Joshua issued (created in the Hub first).
|
||
2. When setup completes, the install sends `POST /api/installs/register`
|
||
with: licence key, site name, URL, admin contact, version, server info
|
||
(Node/Postgres version, OS), timezone, enabled features.
|
||
3. The Hub checks the key, links the install to the customer, and returns an
|
||
**install id + install secret** (stored encrypted in AppSettings) and a
|
||
**signed licence token**.
|
||
4. Existing installs (already past setup) get a **"Connect to Hub"** button
|
||
in Site settings → Licence.
|
||
|
||
All later calls are signed with the install secret (HMAC) and go over HTTPS.
|
||
|
||
### Heartbeat (install → Hub)
|
||
|
||
- Every 15 minutes (job queue) the install POSTs a heartbeat:
|
||
- **Health:** version, uptime, DB OK, job queue OK, last successful
|
||
backup, disk free, last error count (from Sentry or local logs), pending
|
||
migrations.
|
||
- **Basic stats (aggregate counts only):** users, active/upcoming events,
|
||
registrations and tickets (30 days / all time), check-ins, WhatsApp/email
|
||
sent, enabled payment providers, campuses on/off.
|
||
- **Income in ranges, never exact amounts:** total payments received (30
|
||
days / all time) reported as a band — R0–R1 000, R1 001–R5 000,
|
||
R5 001–R20 000, R20 001–R50 000, R50 001–R100 000, over R100 000. The
|
||
band is worked out on the install; the exact figure never leaves it.
|
||
- **Install → Hub only.** The install pushes; the Hub never needs to reach
|
||
into the install, so it works behind firewalls and the Hub has no access
|
||
to church data.
|
||
- **No personal information is ever sent** (no names, emails, phones,
|
||
attendee data). Listed in the install's POPIA operator register and
|
||
privacy notice as "aggregate usage statistics to the software provider".
|
||
|
||
### Hub dashboard
|
||
|
||
- **Installs list:** customer, URL, version (flag if behind the latest tag),
|
||
licence status, last heartbeat (red if > 1 h ago), health status.
|
||
- **Install detail:** health history, stats charts, version history,
|
||
licence history, notes, contacts.
|
||
- **Alerts** (email/WhatsApp to Joshua): install offline > 1 h, backup
|
||
failed or older than 48 h, disk low, errors spiking, licence expiring.
|
||
- **Releases:** latest version and changelog; installs see "Update
|
||
available" in their admin with a **Request update** button (1.42.0 / Hub 1.1.0).
|
||
The request is signed like a heartbeat, shows as an alert (emailed once) and
|
||
clears when the install reports a newer version. Joshua does the update.
|
||
- **Customers:** contact details, plan, licence(s), billing notes.
|
||
|
||
### Licences
|
||
|
||
| State | What the install does |
|
||
|-------|----------------------|
|
||
| **Active** | Everything works |
|
||
| **Grace** (expired or Hub unreachable) | Everything works; **only site admins** see a banner "Licence needs renewing — X days left" (on their dashboard pages — never supervisors, staff, users or the public site). Default 14 days |
|
||
| **Suspended** | **Read-only:** no new events, no new registrations or payments. Existing tickets **still scan**, and admins can still view and **export all data** |
|
||
| **Revoked** | Same as suspended, with a permanent banner |
|
||
|
||
- Joshua turns a licence on/off, sets expiry dates and plan in the Hub; the
|
||
install picks up the change on its next heartbeat.
|
||
- The licence is a **signed token** (Ed25519: the Hub signs with its private
|
||
key, installs only hold the public key). Installs verify it **offline**, so
|
||
a Hub outage never switches a church off, and a token can't be faked by
|
||
editing the database.
|
||
- **Never a hard kill:** a church must always be able to scan tickets for
|
||
events people already paid for, and get its own data out (POPIA access
|
||
rights). Suspension blocks *new* activity only.
|
||
- **One plan for now.** Plan limits (e.g. number of campuses, WhatsApp) can
|
||
be carried in the token later. The first per-licence limit comes with 2.0: the
|
||
**monthly AI cap in rand** (§15), kept and enforced on the Hub, since the Hub meters AI.
|
||
|
||
### Things to be aware of
|
||
|
||
- Code runs on the customer's server, so a determined developer could patch
|
||
out the licence check. Real protection is the **contract** plus updates and
|
||
support only being available to valid licences — the licence check keeps
|
||
honest customers honest.
|
||
- The Hub should not offer remote commands (run updates, impersonate,
|
||
database access) in v1: it's the most valuable target an attacker could
|
||
hit, so keeping it read-only toward installs keeps every church safe if it
|
||
is ever compromised. Updates stay that way: the install *asks* (Request update)
|
||
and Joshua updates the server; the Hub never runs anything on an install.
|
||
- The Hub itself needs 2FA, backups and the same audit log approach.
|
||
|
||
### Data model (Hub, sketch)
|
||
|
||
```prisma
|
||
model Customer { id, name, contactName, email, phone, notes, licences, installs }
|
||
model Licence { id, customerId, key, plan, status, expiresAt, graceDays, issuedAt }
|
||
model Install { id, customerId, licenceId, name, url, secretHash, version,
|
||
lastHeartbeatAt, health Json, registeredAt }
|
||
model Heartbeat { id, installId, receivedAt, version, health Json, stats Json }
|
||
// rolled up to daily after 30 days
|
||
model InstallEvent { id, installId, type, message, createdAt } // alerts, version changes, update requests
|
||
// 2.0, AI (§15): Licence gets aiMonthlyCapCents; usage per call, no prompt/response text
|
||
model AiUsage { id, installId, helper, model, inputTokens, outputTokens, costCents, createdAt }
|
||
```
|
||
|
||
---
|
||
|
||
## 14. Foundations (platform work)
|
||
|
||
Not visible to users, but this is what makes 2.0 a safe product to sell and
|
||
keep adding to.
|
||
|
||
| Item | What |
|
||
|------|------|
|
||
| CI (Gitea Actions) | Lint, typecheck, Jest, build on every push; deploy on tag |
|
||
| Playwright E2E | Register → pay (sandbox) → ticket → scan → cashup; multi-day check-in; kiosk |
|
||
| Job queue | Move `setInterval` jobs out of `index.js` into `pg-boss` (uses Postgres): retries, no double runs, job history in admin |
|
||
| Split big controllers | `registrationController` (2.3k lines), `eventController`, `paymentController` → services by domain. Done **as each feature touches them**, not as a big-bang rewrite |
|
||
| TypeScript backend | Incremental (`allowJs`), new code in TS first; share zod schemas/types with the frontend |
|
||
| API v2 | `/api/v2` with consistent errors, pagination and an OpenAPI spec (replaces the hand-written API docs). `/api` (v1) kept during the transition |
|
||
| Dependencies | Express 5, native `fetch` instead of `node-fetch`, password hashing upgrade with rehash-on-login |
|
||
|
||
---
|
||
|
||
## 15. AI helpers (2.0 headline)
|
||
|
||
Small, one-button AI helpers in the places people already work. **No chat** in 2.0:
|
||
each helper is one request with a predictable cost, and a person always reviews
|
||
the result before anything is saved or sent.
|
||
|
||
**Who:** Supervisors and admins (the people who create events and read reports).
|
||
|
||
### The helpers
|
||
|
||
| Helper | Where | What it does |
|
||
|--------|-------|--------------|
|
||
| **Draft an event** | Event wizard, first step: "Describe your event" | *"Youth camp 14–16 March at Camp Wartburg, R450, 60 places, kids need consent"* → fills in title, description, dates/sessions, location, ticket options and prices, capacity, consent settings. The supervisor checks every field and saves as usual |
|
||
| **Summarise this report** | Every report (Reports page) | A few plain-language insights under the report: trends, outliers, comparisons with the previous period |
|
||
| **Draft a message** | Email / WhatsApp attendees, broadcasts | Turns a short note (*"remind them to bring a sleeping bag, bus leaves 7:30"*) into a friendly message in the right tone and length (shorter for WhatsApp), with placeholders like `{{name}}` |
|
||
| **Summarise feedback** | Post-event feedback results | Themes, what people liked, what to improve, notable comments |
|
||
| **Improve this text** | Event description, banner, message boxes | Rewrite for clarity, fix spelling, shorten |
|
||
|
||
Every helper shows **"AI suggestion — check before saving"**, can be undone, and
|
||
never saves, sends or publishes by itself.
|
||
|
||
### Provider and model
|
||
|
||
- **One provider: Claude (Anthropic), model Claude Haiku 5.5** — the cheapest
|
||
current model ($0.10 per million input tokens, $0.50 per million output, for
|
||
prompts under 100K tokens; prices as of 2026-10). Good enough for drafting and
|
||
summarising; a helper can move to a bigger model later if quality needs it.
|
||
- **Rough cost:** a helper call is ~2,000–10,000 tokens in and ~500 out, so well under
|
||
US$0.002 per click — about R1.50–R3 per thousand clicks. Fixed instructions are
|
||
prompt-cached, which makes repeat calls cheaper still.
|
||
- Structured output (a JSON schema) for "Draft an event", so the reply maps straight
|
||
onto the event form and is validated before it's shown.
|
||
|
||
### Key, caps and billing — through the Hub
|
||
|
||
Joshua provides the API key; churches don't need their own. The key must never sit on
|
||
an install (one leaked install would leak it for everyone), so:
|
||
|
||
- **Installs call AI through the Hub:** `POST /api/ai/complete` on the Hub, signed with
|
||
the install secret like the heartbeat. The Hub adds the key, calls Claude, and returns
|
||
the result. Still **install → Hub only** — the Hub never reaches into an install.
|
||
- **The Hub meters every call** in rand: tokens used × the model's price × an exchange rate
|
||
Joshua sets in the Hub × **(1 + markup)**. Usage is kept per install per month, as both the
|
||
real cost and the charged (marked-up) amount.
|
||
- **Markup** (decided 2026-10-29): one percentage set in the Hub (a default for every licence,
|
||
with an override per licence), e.g. 40%. It does two jobs: it covers Joshua if a month's real
|
||
usage runs a little over (exchange-rate moves, a last call that costs more than expected), and
|
||
it is his profit on AI. Churches only ever see the charged amount in rand. The real cost, the
|
||
markup and the profit are shown only in the Hub.
|
||
- **Monthly rand cap per licence**, set by Joshua in the Hub to match what the church pays
|
||
(e.g. R0 = AI off, R50, R200). The licence's cap is the first per-plan limit. The cap is
|
||
counted in **charged** rand, so the real spend can never be more than cap ÷ (1 + markup).
|
||
- **Hard stop, checked before each call:** the Hub refuses a call when *charged so far + the
|
||
worst case for this call* (its prompt plus the helper's `max_tokens`, priced with markup) would
|
||
pass the cap. A month can't run over by more than the markup already covers, even with
|
||
several people clicking at once (the check and the usage record happen in one transaction).
|
||
At 80% the install's admins get a warning email. Optional per-user daily limit against
|
||
runaway use.
|
||
- **The buttons follow the cap** (decided 2026-10-29):
|
||
- **Cap R0** (or AI off on the licence, or the install not connected to the Hub): the AI
|
||
buttons are **not shown at all**, anywhere.
|
||
- **Cap above R0, room left:** the buttons show and work.
|
||
- **Cap reached:** the buttons stay where they are but are **disabled**, with a tooltip like
|
||
"This month's AI allowance is used up — it renews on 1 December". They come back by
|
||
themselves next month, or as soon as Joshua raises the cap.
|
||
- The install learns this from `GET /api/v2/ai/status` → `{ enabled, capReached, renewsOn,
|
||
helpers }`. The answer is cached briefly from the Hub and refreshed after every call.
|
||
Every AI call also returns the new status, so the buttons disable straight after the call
|
||
that used up the cap. The backend checks again on each request, so a stale page can't get
|
||
past the cap.
|
||
- **Admins see their usage** in Site settings → AI: used this month (R and number of uses),
|
||
the cap, a daily chart, use per helper and per person, and an on/off switch per helper.
|
||
- If the Hub or Claude is unavailable, the buttons say so; nothing else in the app is affected.
|
||
|
||
### POPIA
|
||
|
||
- Anthropic is added to the **operator register** (and Joshua's Hub, which relays the
|
||
requests) and to the privacy notice: processing outside South Africa (POPIA s72),
|
||
for drafting and summarising only.
|
||
- **Send as little personal information as possible:** reports and feedback are sent as
|
||
counts, totals and anonymised comments — no names, contact details, medical or
|
||
children's information. Drafting an event or a message needs none.
|
||
- The Hub stores **no prompt or response text** — only the install, helper, tokens, cost
|
||
and time. Check Anthropic's commercial terms on retention and training before launch.
|
||
- Uses that include personal information (e.g. feedback comments) go in the access log.
|
||
|
||
### Plumbing
|
||
|
||
- Install: `backend/src/ai/` — one client for the Hub's AI endpoint, one prompt + schema
|
||
per helper, usage shown from the Hub. Feature flag per helper, all off when the licence
|
||
has no AI or the Hub isn't connected. The AI endpoints exist **only in `/api/v2`**
|
||
(`/api/v2/ai/status`, `/api/v2/ai/<helper>`), built on 1.51's schemas and error format.
|
||
The frontend has one `useAiStatus()` hook and an `<AiButton>` that hides, enables or
|
||
disables itself from it.
|
||
- Hub: real cost and charged amount per call; the markup default and per-licence override;
|
||
a per-install month view with **cost, charged and profit**; the cap check before each call.
|
||
- Hub: the AI proxy, metering, caps, warnings, an exchange-rate setting, and a per-install
|
||
usage view for Joshua (alongside the existing install detail page).
|
||
- A small **eval set** (example event descriptions, reports, notes, with what a good answer
|
||
looks like) to check quality when changing the prompt or model.
|
||
- Help content, audit log entries (AI settings changed), CHANGELOG, FEATURES.md, SETTINGS.md.
|
||
|
||
---
|
||
|
||
## 16. AI: later stages
|
||
|
||
Ideas for after 2.0, in rough order. **Not tied to versions** — each is decided when it's
|
||
picked up, and all of them reuse the Hub proxy, metering and caps from §15.
|
||
|
||
### Ask AI (read-only assistant)
|
||
|
||
A chat panel for supervisors and admins: *"How many paid for Camp compared with last
|
||
year?"*, *"Which events this month are under half full?"*, *"Who hasn't paid yet for
|
||
Men's Breakfast?"*.
|
||
|
||
- The AI can only call **tools the app defines** — the existing stats and report queries,
|
||
"find an event", "registrations by week" — never its own SQL. It runs with the
|
||
logged-in person's permissions, so it sees nothing they couldn't.
|
||
- Answers show the numbers they're based on and link to the matching report.
|
||
- Costs more per question than a button (several tool calls), so it counts against the same
|
||
cap; may need a bigger model for harder questions.
|
||
|
||
### Help and navigation assistant
|
||
|
||
*"How do I add a coupon?"*, *"Where do I see who checked in?"* → a short answer from the
|
||
in-app help content (`frontend/src/content/help/`) with a link straight to the right page.
|
||
No personal information involved, so it's cheap and simple — could also be offered to
|
||
ordinary users.
|
||
|
||
### Actions with confirmation
|
||
|
||
The Ask assistant can also *do* things — create an event draft, schedule a reminder, offer
|
||
waitlist places, record a cash payment — always as **"here's what I'll do → Confirm"**, with
|
||
each confirmed action in the audit log.
|
||
|
||
### More helpers
|
||
|
||
Smaller one-button additions as they come up: suggest an event's price tiers from past
|
||
events, write a post-event thank-you, draft certificate wording, flag unusual payments for the cashup.
|
||
|
||
### Self-hosted AI (long term)
|
||
|
||
Run an open-weight model on Joshua's own GPU server instead of a paid API, once usage and
|
||
income justify the hardware:
|
||
|
||
- Because every install already talks to the **Hub's** AI endpoint, moving to self-hosting
|
||
is a change on the Hub only — the Hub gets a provider adapter (Claude now, self-hosted
|
||
later, or both: simple helpers self-hosted, harder questions on Claude).
|
||
- **POPIA bonus:** the data can stay in South Africa — no cross-border transfer.
|
||
- **When it makes sense:** compare the monthly API bill with the cost of a GPU server
|
||
(hardware or cloud rental, power, upkeep), and check the self-hosted model against the
|
||
eval set from §15 before switching any helper over.
|
||
|
||
---
|
||
|
||
## Suggested build order
|
||
|
||
| Phase | Version | Features | Why |
|
||
|-------|---------|----------|-----|
|
||
| 0 | 1.32.0 ✅ | **Early-bird ribbon** on event cards (shipped 2026-10-22) | Quick win |
|
||
| 1 | 1.33.0 ✅ | **Multi-day events — phase A** (sessions, whole-course tickets, late joining + late pricing, per-session check-in with whole-day window, attendance register, optional reminders, certificates) | Requested first; touches registration/tickets/scanning, so it shapes later work |
|
||
| 2 | 1.34.0 ✅ | CI + Playwright E2E + job queue | Safety net before the riskiest work (payments). Session reminders move to the queue |
|
||
| 3 | 1.35.0 ✅ | Multi-day events — phase B (pick sessions, per-session capacity) | Builds on phase A, now with E2E coverage |
|
||
| 4 | 1.36.0 ✅ – 1.37.2 | Payment provider interface (Yoco moved behind it) → PayFast, then hiding "Pay online" when it can't be used and payment status checks (SnapScan and Zapper dropped) | Payment code gets split out of the big controller as part of this |
|
||
| 5 | 1.38.0 ✅ 1.39.0 ✅ 1.40.0 ✅ | **POPIA toolkit** (1.38.0: user privacy centre, unsubscribe, WhatsApp STOP, data requests inbox; 1.39.0: privacy notice editor + versions, operator register, consent log, access log; 1.40.0: retention jobs, breach register, children’s-data flags, readiness page) | Main selling point; retention jobs use the job queue |
|
||
| 6 | 1.41.0 ✅ – 1.42.0 ✅ + Hub 1.0 ✅ – 1.1 ✅ | Install/update scripts, `/health`, licence step in `/setup`, "Connect to Hub", heartbeat, licence states — plus the **Hub** app (separate repo); rename to Cross Events (1.41.3); Request update (1.42.0 / Hub 1.1.0) | Must exist before the first church is sold; Hope Family Church registers as install #1 |
|
||
| 7 | 1.43.0 ✅ – 1.44.0 ✅ | **Multi-campus**: 1.43.0 campuses (settings, events, public filter and landing pages, home campus, filters, messages, summaries); 1.44.0 campus-scoped staff | Kids rooms and volunteer roles are per campus, so campuses come first; scoping is split out because it's security-heavy |
|
||
| 8 | 1.45.0 ✅ – 1.46.0 ✅ | Kids check-in, Volunteer rosters | Depend on sessions and campuses |
|
||
| 9 | 1.47.0 ✅ – 1.47.3 ✅, 1.48.0 ✅ | Event series & cloning (1.47.0 clone, 1.47.1 series, 1.47.2 year-on-year reports, 1.47.3 season pass), Outbound webhooks (Wallet passes removed from scope) | Smaller, independent wins |
|
||
| 10 | 1.49.0 ✅ – 1.49.2 ✅, 1.50.0 ✅, 1.50.1 ✅, 1.50.2 ✅ | Admin dashboard/Ctrl+K/bulk actions/saved filters, Accessibility pass, pagination and search on long lists, event picker and webhook guide (Afrikaans removed from scope) | Polish before the big release |
|
||
| 11 | 1.51.0 | TypeScript backend + OpenAPI + `/api/v2` alongside v1 | The breaking-change groundwork |
|
||
| 12 | **2.0.0** | **AI helpers** (§15 — headline feature: draft an event, summarise reports and feedback, draft messages, improve text; through the Hub with a rand cap per licence), v1 API removed, migration guide, marketing site/docs for selling | The release. AI needs the Hub (phase 6) for the key, metering and caps |
|
||
|
||
Each phase should add matching help content (`frontend/src/content/help/`),
|
||
audit log entries, Jest tests, a CHANGELOG entry, and updates to FEATURES.md
|
||
and SETTINGS.md — same as the previous round. Branch → merge → tag → push per
|
||
feature.
|
||
|
||
---
|
||
|
||
## Decisions (2026-10-22)
|
||
|
||
| # | Question | Decision |
|
||
|---|----------|----------|
|
||
| 1 | Pick sessions in the first release? | No — whole-course first (1.33.0), pick sessions as a separate release (1.35.0) |
|
||
| 2 | Late joining and late price | Set **per event**: late joining on/off (until session N), and the late price (full / pro-rata / fixed) |
|
||
| 3 | Check-in window | Per event, **whole day** by default (any time on the session's date); "session time only" as the alternative |
|
||
| 4 | Certificates | Yes — four templates (Classic, Modern, Church, Kids); the event creator chooses whether to issue certificates and which template |
|
||
| 5 | Session reminders | Off by default, configurable per event |
|
||
| 6 | Selling model | **One install per church** — data separation, any server. No multi-tenant. **Multi-campus** inside an install is in scope |
|
||
| — | Pro-rata rounding | Nearest R10 |
|
||
| — | Multi-campus | In scope (§12), inside one install |
|
||
| — | Central management | **Cross Events Hub** in its **own git repo** (`joshua/events-hub`): installs register on setup, send heartbeats (health, version, aggregate stats), licences switched on/off centrally |
|
||
| 7 | Payment provider order | Yoco · PayFast. Joshua can supply documentation links |
|
||
| — | SnapScan, Zapper | Dropped (2026-10-23): Yoco and PayFast are enough. Later versions moved up by two |
|
||
| — | Provider fees | Not deducted or estimated automatically; handled by people during cashup. No "pass fee to payer" |
|
||
| — | Minimum online payment | R15 for all providers |
|
||
| — | Scope | All features in this document approved; POPIA toolkit and kids check-in are highlights |
|
||
| — | Early-bird ribbon | Added before everything else; shipped as 1.32.0, all later versions moved up by one |
|
||
| — | Hub domain | `events-hub.crosscode.co.za` (2026-10-23) |
|
||
| — | Licence keys | Generated by the Hub when Joshua clicks "Generate" on a customer (2026-10-23) |
|
||
| — | Grace period / suspension | 14-day grace; suspended = read-only (tickets still scan, data export still works) (2026-10-23) |
|
||
| — | Grace banner, Hub repo, Hub development | The grace-period banner shows **only to site admins**. The Hub repo is `joshua/events-hub` (https://c-git.crosscode.co.za/joshua/events-hub.git); it is developed locally first, then deployed by Joshua (2026-10-24) |
|
||
| — | Income in the heartbeat | Included, as **ranges** only (R0–R1 000, R1 001–R5 000, …), never exact amounts (2026-10-23) |
|
||
| — | Licence plans | One plan for now (2026-10-23) |
|
||
| — | AI in 2.0 | The **headline feature of 2.0**: one-button helpers only (draft an event, summarise reports and feedback, draft messages, improve text) — no chat yet (2026-10-24) |
|
||
| — | AI provider and key | One provider, **Claude** (Haiku 5.5 to start, for cost). Joshua provides the key; installs call AI **through the Hub**, which holds the key and meters usage (2026-10-24) |
|
||
| — | AI cost limits | A **monthly rand cap per install**, set in the Hub per licence to match what the church pays; admins see their usage in Site settings → AI (2026-10-24) |
|
||
| — | AI buttons and markup | AI buttons show only when the licence's monthly cap is **above R0**. When the cap is reached they stay visible but **disabled** until next month or until the cap is raised. Usage is charged at the real cost **plus a markup %** set in the Hub (a default, plus an override per licence). The markup covers small overruns and is the profit. The cap is counted in charged rand, and each call is checked against its worst-case cost before it's sent (2026-10-29) |
|
||
| — | AI later | Ask AI (read-only, tools only), help/navigation assistant, actions with confirmation, more helpers, and long-term **self-hosted** AI behind the same Hub endpoint — not tied to versions (2026-10-24) |
|
||
| — | POPIA: message kinds | Bulk messages are either **Event updates** (to registrants — still sent after unsubscribing) or **News & announcements** (marketing — opt-in, one-click unsubscribe). Every bulk email links to the preferences (2026-10-23) |
|
||
| — | POPIA: existing users | Kept opted in to news (logged as "existing account"), asked once at their next login to confirm or opt out. New sign-ups choose with an unticked box (2026-10-23) |
|
||
| — | POPIA: deleting an account | A request: the account is deactivated at once, personal info is anonymised when an admin approves. Waits while the person has an open registration for an upcoming event (2026-10-23) |
|
||
| — | POPIA part 2 split | 1.39.0: privacy notice editor + versions + re-acceptance, operator register, Information Officer on the contact page, consent log, access log. 1.40.0: retention policies + nightly job, breach register, children's-data flags, readiness page. Hub moves to 1.41.0 (2026-10-23) |
|
||
| — | POPIA: privacy notice | Today's notice becomes the starting template, one editable box per section; org name, Information Officer, retention periods and the operator list fill in automatically. Publishing saves a numbered version (2026-10-23) |
|
||
| — | POPIA: re-accepting the notice | The admin decides per version ("significant change — ask everyone to accept again"); people are asked once after login (2026-10-23) |
|
||
| — | POPIA: inactive accounts | Anonymised after 5 years without a login or registration, **on by default**, with a warning email 30 days before; staff/supervisor/admin accounts never (2026-10-23) |
|
||
| — | Product name | **Cross Events** (was Hope Events), Hub: **Cross Events Hub**. UI text and docs renamed in 1.41.3; technical identifiers (`hope-events` repo, storage keys, encryption salt, migrations, PM2/nginx names) stay, so installs and sign-ins keep working (2026-10-27) |
|
||
| — | Campus-scoped staff (1.44.0) | Scoped staff: their campuses' events plus "All campuses" events, which they can view, scan, take door payments and do manual registrations for, but not set up, cash up or refund. Banner, provider reconciliation and unlinked donations: unscoped only; broadcasts limited to their campuses' audiences and their events' attendees; coupons only for their events. Other campuses' records answer "not found" except the scanner, which names the campus. Scopes ignored while campuses are off, with a warning (2026-10-27) |
|
||
| — | Multi-campus split | Two releases: **1.43.0 campuses**, **1.44.0 campus-scoped staff**; everything after moves up by one. Scoped staff can view and scan "All campuses" events, only admins and unscoped supervisors edit them. "Everyone at campus X" = home campus X, plus (tick box) registrants of campus X's events in the last 12 months. Campus landing pages are in 1.43.0 (2026-10-27) |
|
||
| — | Updates | Sites show **Request update**, never the deploy command: the request goes to the Hub, which tells Joshua; he updates the server. 1.42.0 / Hub 1.1.0; Multi-campus and everything after moves up by one (2026-10-27) |
|
||
| — | Wallet passes | **Removed from scope** (2026-10-28); everything after volunteer rosters moves up by one |
|
||
| — | Languages (Afrikaans) | **Removed from scope** (2026-10-28); the accessibility pass becomes 1.50.0 and the TypeScript backend / `/api/v2` 1.51.0 |
|
||
| — | Kids check-in (1.45.0) | One release. **Fully digital** — no label printers: pickup code on the parent's phone, a "write on the sticker" panel for blank stickers. Staff desk only (no kiosk). Anyone with the pickup code can collect; families list authorised adults without accounts. Child profiles deleted after 6 months without a check-in (2026-10-28) |
|
||
| — | Volunteer rosters (1.46.0) | Anyone with an account can volunteer. Roles are per event (or per session) — rosters cover one event/session and never repeat. A swap needs no approval: it happens once someone accepts, and the event's notify recipients are emailed. Volunteers check in by scanning a QR code or are checked in by staff. The free volunteer ticket is off by default and chosen per event. A role linked to a kids room counts its checked-in volunteers as leaders on duty for the room's ratio (2026-10-28) |
|
||
| — | Event series and cloning (1.47.x) | One release per part: 1.47.0 clone, 1.47.1 series, 1.47.2 year-on-year reports, 1.47.3 season pass. A clone opens the New event popup filled in from the source, so everything is set there before saving. Of the newer features a clone copies only the campus (not kids check-in or volunteer roles); coupons are never copied. A series can span several campuses. Following a series is **News & announcements**; copies keep the source's certificate and reminder settings. Season pass: one checkout registers for every event on it, the supervisor picks the events, the price is split in proportion to normal prices (2026-10-28) |
|
||
| — | POPIA: WhatsApp STOP | In 1.38.0, via WAWP's incoming `message` webhook with a secret in the URL (WAWP doesn't sign webhooks) (2026-10-23) |
|
||
|
||
## Still open
|
||
|
||
Nothing for now.
|