diff --git a/apps/events/docs/HANDOVER.md b/apps/events/docs/HANDOVER.md index 5ce3ddd..8d46bb3 100644 --- a/apps/events/docs/HANDOVER.md +++ b/apps/events/docs/HANDOVER.md @@ -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` 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 diff --git a/apps/events/docs/ROADMAP-v2.md b/apps/events/docs/ROADMAP-v2.md index 14a52c8..c84a9b9 100644 --- a/apps/events/docs/ROADMAP-v2.md +++ b/apps/events/docs/ROADMAP-v2.md @@ -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). diff --git a/apps/events/docs/ROADMAP-v3.md b/apps/events/docs/ROADMAP-v3.md index 5e84d50..e5119e5 100644 --- a/apps/events/docs/ROADMAP-v3.md +++ b/apps/events/docs/ROADMAP-v3.md @@ -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 + `.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).