Roadmap v3: decisions, pricing and authenticator-app 2FA; handover updated

One install of each product per customer; House of Prayer booking
defaults; email and WhatsApp only (no push); Accounts hidden from
members. Pricing: Website R99 with 5 GB plus storage add-on, App from
R99, address once per church (own domain, crosscode.co.za address R10,
domain included R25). Authenticator app 2FA as Cross Events 2.2.0.
Handover now points at ROADMAP-v3; nothing left open in ROADMAP-v2.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-03 16:48:23 +02:00
co-authored by Claude Opus 5.5
parent 545880fdc7
commit ca7a14bcf8
3 changed files with 142 additions and 39 deletions
+21 -17
View File
@@ -1,8 +1,9 @@
# Handover — where things stand and how to carry on
Last updated: 2026-11-03, after **2.1.1** and Hub **1.7.0**. The plan itself is in
[ROADMAP-v2.md](./ROADMAP-v2.md) (decisions table at the end); the previous round of
features is in [FEATURES-ROUND-1.md](./FEATURES-ROUND-1.md).
Last updated: 2026-11-03, after **2.1.1** (deployed) and Hub **1.7.0**. **The plan from here is
[ROADMAP-v3.md](./ROADMAP-v3.md)** (Accounts, Church Website, Church App, Cross Code Hub; decisions
table near the end). How Cross Events got to 2.x is in [ROADMAP-v2.md](./ROADMAP-v2.md); the round
before that in [FEATURES-ROUND-1.md](./FEATURES-ROUND-1.md).
The product is called **Cross Events** (renamed from Hope Events in 1.41.3); the Hub is the
**Cross Events Hub**. Technical names keep `hope-events` on purpose — the repo, browser storage
@@ -88,24 +89,27 @@ encrypted settings unreadable or break existing installs.
## Next up
1. **After 2.0.x** (order decided 2026-11-02, roadmap §18: 2.0.1 → the marketing site → 2.1.0):
- **Deploy:** `bash scripts/deploy.sh --check`, then `bash scripts/deploy.sh v2.0.1` on each server
(installs on 1.52.x ask through Request update as usual). Before updating an install that has
its own integration, look in the nginx access log for `/api/` calls that aren't `/api/v2/`,
the webhooks or the old links — those get 410 after the update (MIGRATING-TO-2.md).
1. **Roadmap v3** ([ROADMAP-v3.md](./ROADMAP-v3.md), decided 2026-11-03). Everything in
ROADMAP-v2 is done: 2.1.1 is deployed, and the marketing site (`../crosscode-site`,
crosscode.co.za, with prices) is live. Build order (§9):
- **0 — contracts 1.0.0:** `crosscode.event/1`, `crosscode.church/1`, `crosscode.identity/1`,
Hub protocol v3, in the new `joshua/crosscode-platform` monorepo (`packages/contracts`).
- **1 — Hub 2.0.0** (`../events-hub`): Cross Code Hub — products, one licence per product,
**one install of each product per customer**, domain per customer, bundles, sibling discovery.
- **1b — Cross Events 2.2.0:** **authenticator app 2FA** (TOTP + recovery codes) next to email
and WhatsApp (`TwoFactorMethod` enum in `prisma/schema.prisma`).
- **2 — Cross Events 2.3.0:** protocol v3, Linked products, the event feed (publish and show).
- **3 — Accounts 1.0.0**, **4 — Church Website 1.0.0**, **5 — Cross Events 3.0.0** (sign-in
moves to Accounts), **6 — Church App 1.0.0** (House of Prayer).
- **Before selling the Website or App:** put the prices decided in ROADMAP-v3 §10 in
`crosscode-site/src/data/pricing.mjs` and the Hub's `frontend/src/lib/tiers.ts`.
- Servers stay **PM2 + nginx** (no Docker); one database per product per church.
- **AI for a church:** set the licence's monthly AI cap above R0 on the Hub (Hub 1.6.0+); with
no cap the buttons don't show.
- **Marketing site — next, and before 2.1.0** (roadmap §17, all decided 2026-11-02): **crosscode.co.za**, Cross Code's
main site with a Cross Events page; church website and church app as "coming later"; repo
**`joshua/crosscode-site`** (create it on Gitea first); Joshua's own server (nginx); no prices;
a **contact form to info@crosscode.co.za** (needs a small send endpoint on the server — see
§17's building notes); a privacy notice and terms of use; no cookies or analytics. Logo,
colours, wording and screenshots come from Joshua later — start with placeholders.
- **2.1.0** (roadmap §18): the **Feedback page** — results per event, each response, who
hasn't answered and a "remind" action. AI helpers on the privacy pages were dropped
(2026-11-03).
- Testing AI locally: run the Hub (`../events-hub`, port 5200), set Settings → AI there, give a
test licence an AI cap, and start Cross Events with `HUB_URL=http://localhost:5200`.
- **Deploying:** `bash scripts/deploy.sh --check`, then `bash scripts/deploy.sh v<version>` on
each server (installs ask through Request update as usual).
2. **AI rules** (decided 2026-10-29, roadmap §15): the AI buttons show only when the licence's
monthly cap is above R0, and are disabled (not hidden) once it's reached. The Hub charges the
real cost plus a markup % (a default and a per-licence override) and counts the cap in charged
+2 -2
View File
@@ -1200,5 +1200,5 @@ feature.
## Still open
- **Marketing site (§17):** built; waiting on Joshua's real logo, wording and photos where
placeholders remain.
Nothing. The marketing site (§17) is done (2026-11-03). The plan from here is
[ROADMAP-v3.md](./ROADMAP-v3.md).
+119 -20
View File
@@ -23,8 +23,9 @@ whatever direction the church chooses.
7. [Church App](#7-church-app)
8. [Servers and deployment](#8-servers-and-deployment)
9. [Build order](#9-build-order)
10. [Decisions](#decisions-2026-11-03)
11. [Still open](#still-open)
10. [Pricing](#10-pricing)
11. [Decisions](#decisions-2026-11-03)
12. [Still open](#still-open)
---
@@ -105,7 +106,7 @@ touching anyone's account.
| Accounts | Each product (keyed by the account's `sub`, a UUID) |
|----------|-----------------------------------------------------|
| Name, email, phone, password (Argon2id), 2FA, lockout, password reset, login history | Roles in that product. An Events supervisor isn't automatically an App prayer coordinator |
| Name, email, phone, password (Argon2id), 2FA (email, WhatsApp or an authenticator app), lockout, password reset, login history | Roles in that product. An Events supervisor isn't automatically an App prayer coordinator |
| Privacy notice versions and acceptance, news consent (email / WhatsApp) | Product data: registrations and tickets (Events), prayer commitments (App), content edits (Website) |
| "Download my data" and "Delete my account" entry points | Its share of the export and the anonymising, when Accounts asks |
| Inactive-account retention | — |
@@ -114,6 +115,14 @@ touching anyone's account.
- Sign-in is the standard authorisation-code flow with PKCE. People sign in once at
`accounts.church.co.za` and are signed in to every product of that church.
- **Accounts stays in the background** (decided 2026-11-03). Members never see it as a product:
the sign-in page carries the church's name and branding ("Sign in to Hope Family Church"), and
they manage their account from whichever product they're in. Only **admins** see Accounts as
such (people, sign-in settings, linked products), and **account holders** see their own
account page (profile, password, 2FA, privacy).
- **2FA methods:** email, WhatsApp, or an **authenticator app** (TOTP, e.g. Google or Microsoft
Authenticator), with one-time recovery codes. Cross Events gets the authenticator option first
(2.2.0), and the migration carries it over (below).
- Each product keeps a local copy of the profile (name, email) for lists and messages, updated on
sign-in and by `user.updated`.
- **POPIA:** the church is one responsible party. "Download my data" asks every linked product for
@@ -128,7 +137,7 @@ touching anyone's account.
This is a breaking change, so it's a major version.
- A migration copies every Events user into Accounts **with their existing password hash**, 2FA
setting, consent and notice acceptance, so nobody has to reset anything. The Events `User`
setting (including authenticator secrets and unused recovery codes), consent and notice acceptance, so nobody has to reset anything. The Events `User`
table keeps its id (now equal to the account `sub`), role, campus scope and product data.
- Sign-in, forgot password, 2FA, the news question and the notice re-acceptance move to Accounts.
The Events privacy centre links to Accounts for account-level items.
@@ -225,7 +234,14 @@ product's customers, licences, stats, AI usage and billing.
- **Customer → installs.** Each install has a `product` (`events` · `website` · `app` ·
`accounts`) and its **own licence**. Accounts is licensed with whatever else the church has
(no charge of its own).
(no charge of its own). **A customer has at most one install of each product** (decided
2026-11-03): the Hub refuses a second licence for the same product, so "the church's website"
or "the church's Events" is never ambiguous.
- **Address per customer:** own domain, Cross Code address (`church.crosscode.co.za`) or domain
included (§10), recorded on the customer, since one address covers all its products. The
Hub reminds Joshua before an included domain is due for renewal.
- **Add-ons per customer:** the address (R10 or R25) and extra website storage, billed with the
products but never bundle-discounted. Website installs report storage used in the heartbeat.
- **Billing per customer:** prices per product on the income bands, bundles at **15% off two
products** and **25% off all three**, founding prices and the free month (as on
crosscode.co.za). Invoices are recorded in the Hub (sent / paid / overdue). A payment provider
@@ -286,11 +302,18 @@ release. From the app spec, adjusted.
### House of Prayer (the headline)
- **24/7 coverage view:** a 24-hour timeline, coverage % and gaps, slot length set by the church
(15 / 30 / 60 min), in the church's timezone. Live updates through server-sent events, with
polling as a fallback.
- **24/7 coverage view:** a 24-hour timeline, coverage % and gaps, in the church's timezone.
Live updates through server-sent events, with polling as a fallback.
- **Commitments:** one-off and recurring slots, change or cancel your own, optional reminders
(email / WhatsApp / push), a voluntary "I prayed" marker clearly shown as self-reported.
by **email or WhatsApp**, a voluntary "I prayed" marker clearly shown as self-reported.
- **Booking rules** (defaults decided 2026-11-03; the church can change them):
| Rule | Default |
|------|---------|
| Slot length | **1 hour** (church can choose 15, 30 or 60 minutes) |
| Book ahead | Up to **12 months** in advance |
| Recurring bookings | Daily or weekly, for up to **12 months from the day of booking**. Before it runs out the member gets an email/WhatsApp to renew it for another year |
| Cancelling | Up to **8 hours before** the slot. Within 8 hours the slot can't be cancelled in the app (the member is shown who to contact) |
- **Anonymous:** public views show coverage only, never names. Admin access to bookings is
permission-controlled and goes in the access log.
- **Prayer requests:** private by default (submitter and prayer team only). Public or group
@@ -305,7 +328,11 @@ Announcements, devotionals, reading plans, sermons (shared with the Website wher
connect groups, pastoral care (restricted access, audited), serving opportunities, giving links,
an opt-in directory, and **events** (simple events plus the feed, §4).
**Every module is available to every church.** Pricing follows the income bands, not features.
**Every module is available to every church.** Pricing follows church size (§10), not features.
**Notifications are email and WhatsApp only** (decided 2026-11-03), using the same email and
WhatsApp setup as Cross Events. No push notifications. Members choose their channel per kind of
message (prayer reminders, announcements).
### Roles
@@ -325,8 +352,9 @@ browsed without an account. Personal actions need sign-in through Accounts.
install, then a tagged update with a database backup, migrations, build, restart and roll back
on failure. An `add-church` script runs them for the products a church has bought and prints
the nginx config and DNS records.
- **Domains:** `www.`, `events.`, `app.` and `accounts.` on the church's own domain. Certificates
through certbot. Only configured domains are served (no trusting arbitrary Host headers).
- **Domains:** `www.`, `events.`, `app.` and `accounts.` on the church's own domain, or on
`<church>.crosscode.co.za` for the Cross Code address (a wildcard DNS record and certificate
for `*.crosscode.co.za` subdomains, so no DNS work per church). Certificates through certbot. Only configured domains are served (no trusting arbitrary Host headers).
- Every product has `/health` (version, DB, jobs, last backup), reported to the Hub.
- Several churches can share a server at first. Any church can move to its own server later
without code changes. The Hub stays on a separate server from church installs.
@@ -351,12 +379,13 @@ Playwright, Jest), so code and habits carry over.
|-------|---------|------|----------------|
| 0 | contracts 1.0.0 | `crosscode.event/1`, `crosscode.church/1`, `crosscode.identity/1`, Hub protocol v3: schemas, docs, sample payloads, the monorepo set up | Everything else depends on them |
| 1 | **Hub 2.0.0** | Cross Code Hub: products, licence per product, per-customer billing with bundles, protocol v3 (v2 still accepted), sibling discovery, AI usage per product | Must exist before a second product is sold |
| 2 | **Cross Events 2.2.0** | Reports `product: "events"` (protocol v3), **Linked products**, the event feed (publish + show events from siblings) | Small; ready for when the Website exists |
| 3 | **Accounts 1.0.0** | OIDC provider, sign-in, 2FA, password reset, consent and notice, export / delete fan-out, admin, install script | The Website is built on it from day one |
| 1b | **Cross Events 2.2.0** | **Authenticator app 2FA** (TOTP) next to email and WhatsApp, with recovery codes; admins can see which method each staff account uses | Independent and useful now; the Accounts migration later carries it over |
| 2 | **Cross Events 2.3.0** | Reports `product: "events"` (protocol v3), **Linked products**, the event feed (publish + show events from siblings) | Small; ready for when the Website exists |
| 3 | **Accounts 1.0.0** | OIDC provider, sign-in, 2FA (email, WhatsApp, authenticator app), password reset, consent and notice, export / delete fan-out, admin, install script | The Website is built on it from day one |
| 4 | **Church Website 1.0.0** | Public site, admin, simple events + feed, Hope Family Church as the first church, then a second test church to prove it repeats | More churches need a website than an app; it also covers the "website only" case |
| 5 | **Cross Events 3.0.0** | Sign-in moves to Accounts; user migration keeping password hashes; migration guide | Breaking change, so a major version, after Accounts is proven on the Website |
| 6 | **Church App 1.0.0** | Foundation (PWA, branding, Accounts), House of Prayer, announcements, devotionals, events (simple + feed) | Starts with shared users and the feed already in place |
| 7 | Church App 1.x | Reading plans, sermons, groups, pastoral care, serving, giving links, directory, push notifications | After House of Prayer is in use |
| 7 | Church App 1.x | Reading plans, sermons, groups, pastoral care, serving, giving links, directory | After House of Prayer is in use |
Each phase adds help content, audit log entries, tests, a CHANGELOG entry and updates to the
docs. Branch → merge → tag → push per feature, as before.
@@ -372,6 +401,72 @@ docs. Branch → merge → tag → push per feature, as before.
---
## 10. Pricing
Aimed at small and mid-sized South African churches: the Website and App start well below Cross
Events, since they replace things churches often get cheaply or free today (a basic website,
WhatsApp groups). Prices are rand per month. Decided by Joshua on 2026-11-03.
When the Website and App go on sale, they go in `crosscode-site/src/data/pricing.mjs` and the Hub's
`frontend/src/lib/tiers.ts`.
**The same rules as Cross Events apply to every product:** one month free, yearly billing = 10
months' price, founding churches 35% off for as long as they stay, bundles **15% off** two
products and **25% off** all three, and the tier is checked once a year at renewal. **Add-ons**
(address and storage) are not discounted.
### The church's address: three options
One address covers all of a church's products (`www.`, `events.`, `app.`, `accounts.`), so it's
charged **once per church**, not per product.
| Option | Price | What it means |
|--------|-------|---------------|
| **Own domain** | R0 | The church already has a domain (e.g. `hopefamily.co.za`). They, or whoever manages it, add the DNS records we send. We look after the certificates |
| **Cross Code address** | **+R10 / month** | For churches that don't want a domain of their own: `hopefamily.crosscode.co.za`, with the products at `events.hopefamily.crosscode.co.za`, `app.hopefamily.crosscode.co.za` and so on. Can move to a domain of their own at any time (old addresses redirect for 12 months). Trials use this address for free |
| **Domain included** | **+R25 / month** | We register a `.co.za` or `.org.za` **in the church's name**, renew it every year and manage the DNS. Other endings (`.com`, `.church`, `.org`) are charged at cost on top. If the church leaves, the domain is transferred to them, free |
### Church Website: one price plus storage
| | Price |
|--|------:|
| **Church Website** (5 GB of uploads included) | **R99** |
| Founding (35% off) | R64 |
| **Extra storage** add-on | **+R20 / month per extra 5 GB** |
Uploads are photos, documents and sermon notes. Sermon audio and video are linked (YouTube,
Spotify, SoundCloud…) rather than uploaded, so most churches never need extra storage. Admins see
how much they've used in the website's settings and get an email at 80%. Storage is counted per
church and reported to the Hub, which bills the add-on.
### Church App: on active members
Billed on **active members**: accounts that used the App in the last 90 days, reported to the Hub
as a band (like event income for Cross Events). Visitors browsing without signing in never count.
| Tier | Active members | Price | Founding |
|------|----------------|------:|---------:|
| Mustard Seed | Up to 100 | **R99** | R64 |
| Small Group | 101 – 300 | **R249** | R162 |
| Congregation | 301 – 750 | R399 | R259 |
| Gathering | 751 – 2 000 | R649 | R422 |
| Multitude | 2 001 – 5 000 | R999 | R649 |
| Network | Over 5 000 | From R1 500 | 35% off |
### What churches would pay (no founding discount)
| Church | Products | Products after bundle | + address | Per month |
|--------|----------|----------------------:|----------:|----------:|
| Small, website only | Website | R99 | own domain | **R99** |
| Small, website only | Website | R99 | Cross Code address | **R109** |
| Small, website only | Website | R99 | domain included | **R124** |
| Small, website + app | Website + App (≤100): R198 | R168 (15%) | domain included | **R193** |
| Small, everything | Events Seed + Website + App (≤100): R548 | R411 (25%) | domain included | **R436** |
| Mid-sized, everything | Events Grow + Website + App (301–750): R1 348 | R1 011 (25%) | domain included | **R1 036** |
(Rounded to the rand.)
---
## Decisions (2026-11-03)
| # | Question | Decision |
@@ -386,11 +481,15 @@ docs. Branch → merge → tag → push per feature, as before.
| 8 | Stack | Next.js + Express + Prisma + PostgreSQL + pg-boss, as Cross Events (not the specs' React + Vite, Redis + BullMQ, Socket.IO) |
| 9 | Pricing | Income bands per product, bundles 15% (two) / 25% (three); every App module for every church (not the website spec's Starter / Growth / Pro tiers) |
| 10 | Hub provisioning | Scripts Joshua runs; the Hub records installs but never deploys or rolls back (not the specs' automated provisioning) |
| 11 | Installs per product | **One install of each product per customer**; the Hub refuses a second licence for the same product |
| 12 | House of Prayer defaults | 1-hour slots, book up to 12 months ahead, recurring bookings for up to 12 months from the day of booking, no cancelling within 8 hours of the slot |
| 13 | App notifications | **Email and WhatsApp only.** No push notifications |
| 14 | Accounts visibility | Hidden from members (branded as the church's sign-in). Only admins and the account holder see account pages |
| 15 | 2FA | Add an **authenticator app** (TOTP, with recovery codes) next to email and WhatsApp: in Cross Events 2.2.0 first, then in Accounts |
| 16 | Pricing | Website **R99** with 5 GB, extra storage as an add-on in steps. App **R99** (up to 100 members), then **R249**. Address once per church: own domain R0, **Cross Code address R10**, **domain included R25**. Extra storage R20 per 5 GB; App tiers above 300 members R399 / R649 / R999 / from R1 500. Add-ons aren't bundle-discounted (§10) |
## Still open
- Exact prices for the Website and App on the income bands (`crosscode-site/src/data/pricing.mjs`).
- Whether a church can link more than one install of the same product (e.g. two websites).
- House of Prayer defaults: slot length, booking horizon, recurrence limits, cancellation rules.
- Push notifications in the App (web push support varies by phone) — in 1.0 or 1.x.
- Whether Accounts is shown to people by name ("Hope Family account") or kept invisible.
Nothing. When the Website and App go on sale, put the §10 prices in
`crosscode-site/src/data/pricing.mjs` and the Hub's tiers (the Website and App move from "coming
later" to their own prices).