From 633d65eec9f1c71fb3aa29cf9e45f02dff8e0ff3 Mon Sep 17 00:00:00 2001 From: Joshua Oosthuizen Date: Thu, 5 Nov 2026 09:48:27 +0200 Subject: [PATCH] Docs: roadmap and Hub protocol move here; handover and Events 2.2.0 plan Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 6 + README.md | 17 +- docs/EVENTS-2.2-PLAN.md | 252 +++++++++++ docs/HANDOVER.md | 54 +++ docs/ROADMAP-v3.md | 779 ++++++++++++++++++++++++++++++++++ docs/hub-protocol.md | 328 ++++++++++++++ package.json | 2 +- packages/contracts/src/hub.ts | 2 +- 8 files changed, 1435 insertions(+), 5 deletions(-) create mode 100644 docs/EVENTS-2.2-PLAN.md create mode 100644 docs/HANDOVER.md create mode 100644 docs/ROADMAP-v3.md create mode 100644 docs/hub-protocol.md diff --git a/CHANGELOG.md b/CHANGELOG.md index e18095a..3d8fd11 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,12 @@ Each package and app has its own section and its own tags (`contracts@1.0.0`, `a ## Unreleased +### Docs + +- The roadmap (`docs/ROADMAP-v3.md`) and the Hub protocol (`docs/hub-protocol.md`) move here from + `hope-events/docs/`, since they cover every product. New: `docs/HANDOVER.md` (where each phase + stands) and `docs/EVENTS-2.2-PLAN.md` (phase 1b, Cross Events into the monorepo). + ## contracts@1.1.0 - 2026-11-04 ### Contracts diff --git a/README.md b/README.md index 6f33bda..91b6fc1 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,8 @@ # Cross Code platform The monorepo for the Cross Code products that come after Cross Events, and the formats they share. -The plan is in `hope-events/docs/ROADMAP-v3.md` (decided 2026-11-03). +The plan for every product is in [`docs/ROADMAP-v3.md`](./docs/ROADMAP-v3.md) (decided 2026-11-03); where +things stand is in [`docs/HANDOVER.md`](./docs/HANDOVER.md). | Folder | What | Status | |--------|------|--------| @@ -11,8 +12,18 @@ The plan is in `hope-events/docs/ROADMAP-v3.md` (decided 2026-11-03). | `apps/website` | Church Website | Placeholder (phase 4) | | `apps/app` | Church App (PWA) | Placeholder (phase 6) | -Cross Events (`joshua/hope-events`) and Cross Code Hub (`joshua/events-hub`) stay in their own -repos and install `@crosscode/contracts` from Gitea's package registry. +Cross Events (`joshua/hope-events`) moves in as `apps/events` in Events 2.2.0 +([`docs/EVENTS-2.2-PLAN.md`](./docs/EVENTS-2.2-PLAN.md)). Cross Code Hub (`joshua/events-hub`) stays in +its own repo and gets `@crosscode/contracts` as a packed release committed there (decision 22). + +## Docs + +| File | What | +|------|------| +| [`docs/ROADMAP-v3.md`](./docs/ROADMAP-v3.md) | The plan: products, contracts, Accounts, sync, Hub, servers, build order, pricing, decisions | +| [`docs/HANDOVER.md`](./docs/HANDOVER.md) | Where each phase stands and what's next | +| [`docs/hub-protocol.md`](./docs/hub-protocol.md) | Install ↔ Hub protocol, versions 1 and 2 (a copy lives in `events-hub`) | +| [`docs/EVENTS-2.2-PLAN.md`](./docs/EVENTS-2.2-PLAN.md) | Phase 1b: Cross Events into the monorepo, the `crosscode` script | ## Rules (ROADMAP-v3 §1) diff --git a/docs/EVENTS-2.2-PLAN.md b/docs/EVENTS-2.2-PLAN.md new file mode 100644 index 0000000..dfb73d8 --- /dev/null +++ b/docs/EVENTS-2.2-PLAN.md @@ -0,0 +1,252 @@ +# Cross Events 2.2.0 — moving into the monorepo + +Phase **1b** of [ROADMAP-v3.md](./ROADMAP-v3.md) (§8 "Releases and updates", §9; decisions 21, 23, +24). Written 2026-11-05. + +**What 2.2.0 is:** Cross Events moves from `joshua/hope-events` into this repo as `apps/events`, +with its git history, and the **`crosscode` script** replaces `scripts/deploy.sh` and +`scripts/install.sh`. **It changes no features.** If something breaks, the cause is the move. +Churches see one line in What's new ("Nothing changes for you"). + +**Done when:** + +- `events@2.2.0` is tagged here, and the Hub lists it under Cross Events. +- Every existing install has been moved with `crosscode adopt` and reports 2.2.0. +- `hope-events` is archived. +- The test results match 2.1.1's. + +## Before starting + +- **Hub 2.0.0 is deployed.** Its release sync already reads `events@…` tags from this repo, with + notes in `apps/events/WHATS-NEW.md` (`events-hub/backend/src/utils/releaseSync.js`). It also + keeps the `hope-events` `v…` source for older releases. Hub 1.7 can't see `events@` tags. +- `hope-events` `main` is at 2.1.1 with nothing in flight, and **frozen** from step 1 on. A fix + needed during the move goes in on the `hope-events` side as 2.1.2 and is merged in again + (step 1 can be re-run). +- **Baseline:** the result counts of 2.1.1's backend Jest run, frontend build and Playwright e2e + run, so step 6 has something to compare against. +- `git-filter-repo` installed on the dev machine (`pip install git-filter-repo`). + +## 1. History: merge it in, with paths rewritten + +On a fresh clone, so the working repo is never rewritten: + +```bash +git clone https://c-git.crosscode.co.za/joshua/hope-events.git events-move +cd events-move +git tag -l | xargs git tag -d # v… tags stay in the archived repo +git filter-repo --to-subdirectory-filter apps/events +cd ../crosscode-platform +git checkout -b move/events +git remote add events-move ../events-move && git fetch events-move main +git merge --allow-unrelated-histories events-move/main \ + -m "Cross Events moves into the monorepo (apps/events), from hope-events " +git remote remove events-move +``` + +- **Why `filter-repo` rather than `git subtree add`:** every old commit then already has its + `apps/events/…` path, so `git log` and `git blame` on a file show its whole history without + `--follow`. Commit hashes change. The archived repo keeps the originals, and the merge message + names the last one. +- **Old tags aren't brought over.** Bare `v2.1.1` tags would be ambiguous in a monorepo, and the + Hub reads them from the archived repo. Product tags start at `events@2.2.0`. + +## 2. Workspaces and the lockfile + +- Root `package.json` → `"workspaces": ["packages/*", "apps/*", "apps/events/backend", + "apps/events/frontend"]`. `apps/events` itself is covered by `apps/*` (its root scripts and + Playwright). +- Rename the packages so workspace names are unique: `@crosscode/events` (was `hope-events`), + `@crosscode/events-backend`, `@crosscode/events-frontend`. Nothing reads the names. The Hub + reads the backend's `version` (`backend/src/hub/report.js`), and that stays. All three go to + `2.2.0`. +- **One lockfile at the root.** Delete `backend/package-lock.json` and + `frontend/package-lock.json`, then run `npm install` at the root. **Versions must not drift:** + compare `npm ls --all` before and after (next, react, prisma, @prisma/client, express, + typescript, jest, ts-jest, @sentry/nextjs, pg-boss, and anything else resolved differently). + Pin anything that moved with `overrides`. Keep the existing `shell-quote` override at the root. +- **Hoisting traps to check:** + - Prisma's `prisma-client-js` generates into the hoisted `node_modules/.prisma/client`. That's + fine while Events is the only Prisma app. **Accounts (phase 3) must use its own generator + `output`**, otherwise the two overwrite each other locally. On servers each checkout builds + only one app, so the problem doesn't arise there. Events keeps the default, so no imports + change in 2.2.0. + - Next.js 16 finds the workspace root from the lockfile. Once the nested lockfiles are gone, + there's no "multiple lockfiles" warning, and `next build` traces files from the repo root. + Check that `.next` still builds to `apps/events/frontend/.next`, and that `NEXT_DIST_DIR` + (e2e) still works. + - `@types/node` 20, TypeScript 5, Jest 30 and ESLint 10 are the same majors on both sides. +- **Lint:** the root `eslint .` ignores `apps/events/**` (add it to `globalIgnores`). Events + keeps its own configs: `frontend/eslint.config.mjs`, plus `tsc` for the backend. Moving Events + onto the root lint is a later cleanup, not part of 2.2.0. +- **Root `npm run check`** runs Events' scripts through `--workspaces --if-present`: backend + `test` and `typecheck`, frontend `build`. Make sure the backend tests run with no database, as + they do today. If any need one, give them their own script so the root `check` stays + self-contained. + +## 3. Inside `apps/events` + +Paths mostly carry over, because everything in Events is relative to its own folder: + +- **`.gitignore`** moves to `apps/events/.gitignore`. Git reads a nested `.gitignore` relative to + its own folder, so `/ecosystem.config.js`, `backend/public/uploads/`, `backend/backups/` and + `backend/data/*.json` keep working unchanged. Check with `git status --ignored` on a copy of a + real install. +- **`ecosystem.config.js`** uses `__dirname + '/backend'`. Placed in `apps/events/`, it needs no + change. `adopt` rewrites only installs whose copy has absolute `cwd` paths. +- **Playwright** (`apps/events/playwright.config.ts`) keeps its `cwd: "backend"` / `"frontend"`. + Run it from `apps/events`. +- **Docs:** `ROADMAP-v3.md` and `hub-protocol.md` already live in the root `docs/`. Remove their + pointer stubs from `apps/events/docs/` in the merge. Code comments that cite + `docs/hub-protocol.md` then point at the root copy. `apps/events/docs/HANDOVER.md` keeps the + Events-only parts (where the code lives, known gaps), and the cross-product status lives in the + root [HANDOVER.md](./HANDOVER.md). +- **`CHANGELOG.md` and `WHATS-NEW.md`** stay in `apps/events/` (the Hub reads + `apps/events/WHATS-NEW.md`). The 2.2.0 entry in `WHATS-NEW.md` has no `— requires`. +- **`README.md` and `DEPLOYMENT.md`:** rewrite the deploy and install sections for `crosscode`. + The nginx and PM2 background stays. +- `scripts/deploy.sh` and `scripts/install.sh` are **removed** from `apps/events`. The archived + repo keeps them for installs that haven't moved yet. + +## 4. The `crosscode` script + +It lives in this repo's root `scripts/`. It's bash, like today's scripts, and is checked with +`shellcheck`. On a server it's a checkout of `main` in `/opt/crosscode/tools`, updated with +`git pull --ff-only` at the start of every run, then re-run from a copy (as `deploy.sh` does +today, so a checkout never changes the running script). + +``` +scripts/ + crosscode entry: self-update, re-run from a copy, dispatch, `help` + lib/common.sh logging, root/app-user checks, church.env read/write, tag lookup + lib/deploy.sh checks → per product in order → summary + lib/install.sh new church (from today's install.sh) + lib/adopt.sh existing Events install → monorepo + lib/status.sh + products/events.sh the product's hooks (below); accounts.sh, website.sh, app.sh follow + tests/ bats tests for the parts that don't need a server +``` + +**Product hooks.** Each `products/.sh` defines `backup`, `install_deps` (`npm ci +--include=dev -w apps/events/backend -w apps/events/frontend`), `migrate`, `build`, `pm2_names`, +`health_url` and `rollback_build`. With hooks, adding Accounts in phase 3 means adding a file, +not rewriting the deploy. For Events they come from today's `deploy.sh`: the backup through +`backupUtils.runBackup()`, `prisma migrate deploy`, the backend `tsc` build and `next build`. + +**`church.env`** (`/var/www/sites//church.env`, mode 600, owned by root): + +``` +CHURCH=hopefamily +PRODUCTS="events" # accounts website app as they're added +ADDRESS=hopefamily.co.za # or hopefamily.crosscode.co.za +EVENTS_DIR=/var/www/sites/hopefamily/events +EVENTS_DOMAIN=events.hopefamily.co.za +EVENTS_PM2="hope-events-backend hope-events-frontend" +EVENTS_PORTS="5000 3000" # api web +EVENTS_DB=hope_events +EVENTS_USER=hopeevents +``` + +Secrets stay in each product's own `.env`, never in `church.env`. + +**Commands in 2.2.0:** + +| Command | In 2.2.0 | +|---------|----------| +| `deploy [events]` | Yes. Accounts is skipped while a church has none (§8). Tags are `events@x.y.z`, newest by version (`git tag -l 'events@*' --sort=-v:refname`) | +| `deploy … --version events@x.y.z`, `--main`, `--check` | Yes | +| `deploy --every-church …` | Yes (it's a loop over `/var/www/sites/*/church.env`) | +| `status []` | Yes: version from `/health`, latest tag, DB, jobs, last backup | +| `install --products events --domain …` | Yes, for Events only (from today's `install.sh`: Node 24, PostgreSQL, PM2, nginx, certbot); it writes `church.env` | +| `adopt --events-dir …` | Yes (section 5) | +| `adopt --undo` | **New, proposed:** goes back to the old folder and the 2.1.x it ran, within the days the old folder is kept | +| `add ` | **Later** (phase 3), when there's a second product to add | + +**Requirement check** (decision 24): before anything is touched, read the target version's +heading in `apps//WHATS-NEW.md`. Refuse the deploy if a `— requires ` +isn't met by the installed sibling or by this same run. Nothing in 2.2.0 requires anything, but +the check is built and tested now. + +**A deploy, per product** (as `deploy.sh` today): refuse if files were changed by hand → +database backup → `git fetch --tags` and check out the tag (detached) → install and build that +app only → migrations → `pm2 reload` → poll `/health` until it reports the new version (60 s). +On failure that product goes back to its previous tag and rebuilds, and the run stops. The +summary lists each product as updated, rolled back or not reached. + +## 5. `crosscode adopt` (once per existing install) + +**Proposed change to ROADMAP §8:** build the new checkout **next to** the running install, then +switch over, instead of moving the running folder. Moving the folder underneath running PM2 +processes breaks anything they read from disk later (Next.js pages, uploads), so the site would +be down for the whole build. Building next to it keeps the old install untouched, which makes +rolling back simply "start the old one again". + +1. **Checks:** the old folder is a `hope-events` checkout at a `v2.1.x` tag with no files changed + by hand, and `/var/www/sites//events` doesn't exist (or is already an adopted + checkout, in which case stop: nothing to do). +2. **Read what the install already has:** the PM2 names and ports from `ecosystem.config.js`, and + the database name from `backend/.env` `DATABASE_URL`. Write `church.env`. +3. **New checkout** of this repo at `events@2.2.0` in `/var/www/sites//events`, owned by + the app user. +4. **Copy the install's own files** into `apps/events/`: `backend/.env`, `frontend/.env*`, + `ecosystem.config.js` (with absolute `cwd`s rewritten), `backend/data/*.json`, and + `backend/backups/`. Then `rsync -a backend/public/uploads/`, which may be large; the old site + is still serving meanwhile. +5. **Build** (`npm ci -w …`, backend build, `next build`). The old install keeps running. +6. **Switch over** (the only downtime, a few seconds): database backup → a final + `rsync -a --delete` of the uploads and `data/*.json` → `prisma migrate status` must show + nothing pending (2.2.0 adds no migrations; refuse if it does) → `pm2 delete` the two names → + `pm2 start ecosystem.config.js` from the new folder → `pm2 save` → `/health` reports 2.2.0. +7. **On failure at step 6:** `pm2 delete` → `pm2 start` from the old folder → `pm2 save`. Nothing + in the old folder was changed, so it comes back exactly as it was. +8. **Keep the old folder**, renamed `.pre-2.2.0`, for 14 days. `adopt --undo` uses it. + After that, `crosscode status` reminds you to remove it. + +The nginx config doesn't change (it only proxies to ports), and neither do the PM2 names, the +database or its name. + +## 6. Testing + +- **Events, unchanged behaviour:** backend Jest, `tsc --noEmit`, frontend build and the + Playwright e2e run, all from the monorepo. They should give the same counts as the 2.1.1 + baseline. +- **Script:** `shellcheck`, plus bats tests for tag lookup, the `— requires` parsing, + `church.env` reading and writing, and the rewriting of `ecosystem.config.js`. +- **On a throwaway Ubuntu 24.04 VM** (e.g. multipass), in this order: + 1. `install.sh` from the archived repo at `v2.1.1`. Add demo data and a few uploads. + 2. `crosscode adopt` → 2.2.0 works, the uploads are there, and the database is unchanged. + 3. `adopt --undo` → back on 2.1.1. Then `adopt` again. + 4. `crosscode deploy events --version events@2.2.0-test` with a broken migration on a + test tag → it rolls back to 2.2.0 and the site stays up. + 5. A file changed by hand → `deploy --check` refuses it. + 6. A second church with `crosscode install` on the same VM → separate databases, `.env` files, + uploads and PM2 names. `deploy --every-church` updates both. + 7. `crosscode status` for both. + 8. The Hub (local, port 5200) sees the install's heartbeat as 2.2.0, and `events@2.2.0` under + Releases. + +## 7. Rolling it out + +1. **`hope-events`, last commit on `main`:** README "Moved to `crosscode-platform/apps/events`; + this repo only keeps 2.1.x for installs that haven't moved". No tag. +2. **Here:** merge `move/events` → `npm run check` → tag `events@2.2.0` → push with tags. Remove + any test tags first. +3. **Hub:** run release sync. Check that Cross Events shows 2.2.0 and the older `v…` releases + are still listed. +4. **Servers:** set up `/opt/crosscode/tools`. Adopt a staging copy first, then each real + install one at a time, checking `crosscode status` after each. Installs on 2.1.1 see 2.2.0 on + the Hub. Their "Request update" is answered with `adopt`, not `deploy`. +5. **When every install reports 2.2.0:** archive `hope-events` on Gitea (read-only; cloning and + fetching still work, so `adopt --undo` and old installs keep working). +6. **crosscode-site:** nothing changes (ROADMAP §9). +7. **Docs:** a 2.2.0 entry in `apps/events/CHANGELOG.md` and the root `CHANGELOG.md`, and the + root [HANDOVER.md](./HANDOVER.md) updated with 1b done and 1c (2.3.0, authenticator app 2FA) + next. + +## Open questions + +1. Build next to the old install and switch over (section 5, recommended), or move the folder as + ROADMAP §8 says? If the switch-over is agreed, §8 gets updated to match. +2. `adopt --undo`: build it (recommended; it's small once the old folder is kept) or not? +3. Do any Events backend tests need a database, which would affect the root `npm run check`? + (Answered while doing section 2.) diff --git a/docs/HANDOVER.md b/docs/HANDOVER.md new file mode 100644 index 0000000..1af7ca5 --- /dev/null +++ b/docs/HANDOVER.md @@ -0,0 +1,54 @@ +# Handover — Cross Code, all products + +Last updated: 2026-11-05. **The plan is [ROADMAP-v3.md](./ROADMAP-v3.md)** (decided 2026-11-03, +decisions table near the end). This file says where each phase stands and what comes next. +Product-specific notes (where the code lives, known gaps) stay with each product: Cross Events' +are in `hope-events/docs/HANDOVER.md` (`apps/events/docs/HANDOVER.md` from Events 2.2.0), and +the Hub's are in `events-hub/docs/`. + +The docs for every product are here in `docs/`: the roadmap, the Hub protocol +([hub-protocol.md](./hub-protocol.md), with a copy in `events-hub`), this handover and the plans +for each phase. They moved here from `hope-events/docs/` on 2026-11-05. + +## Repos + +| Repo | What | +|------|------| +| `joshua/crosscode-platform` (this one) | Contracts, the apps (Accounts, Website, App, and Events from 2.2.0), shared packages, the `crosscode` script (from Events 2.2.0), and these docs | +| `joshua/hope-events` | Cross Events up to 2.1.x. Archived after the 2.2.0 move | +| `joshua/events-hub` | Cross Code Hub. Its own server, its own `scripts/deploy.sh` | +| `joshua/crosscode-site` | crosscode.co.za. Updated at the end of every phase that changes what it says (ROADMAP §9) | + +## Where each phase stands (ROADMAP §9) + +| Phase | What | State | +|-------|------|-------| +| 0 | contracts 1.0.0 / 1.1.0 | **Released** 2026-11-04 (`contracts@1.0.0`, `contracts@1.1.0`). Not published to a registry (decision 22): the Hub gets a packed release committed to its repo | +| 1 | Hub 2.0.0 | **Released** 2026-11-05 (`events-hub` `v2.0.0`; `docs/HUB-2.0-PLAN.md` there). **Not deployed yet:** `events-hub/deployment.md` → "Upgrading to 2.0" (run `check-hub2` first). crosscode-site's address prices are merged, **not deployed yet** | +| 1b | Cross Events 2.2.0: moves here as `apps/events`, `crosscode` script | **Next.** Planned in [EVENTS-2.2-PLAN.md](./EVENTS-2.2-PLAN.md) | +| 1c | Cross Events 2.3.0: authenticator app 2FA (TOTP + recovery codes) | Not started (`TwoFactorMethod` enum in Events' `prisma/schema.prisma`) | +| 2 | Cross Events 2.4.0: protocol v2, Linked products, event feed, `packages/seo` | Not started. Events keeps speaking protocol 1 until then | +| 3–7 | Accounts 1.0.0 → Website 1.0.0 → Events 3.0.0 → App 1.0.0 → App 1.x | Not started | + +## Next up + +1. **Deploy Hub 2.0.0** and **crosscode-site** (the address prices). This finishes phase 1 and is + needed before 2.2.0, because Hub 1.7 can't see `events@…` tags. +2. **Cross Events 2.2.0**: [EVENTS-2.2-PLAN.md](./EVENTS-2.2-PLAN.md). Its open questions (how + `adopt` switches over, `adopt --undo`) are settled before the script is written. +3. **Cross Events 2.3.0** (authenticator app 2FA), then 2.4.0, as in ROADMAP §9. + +## Things to remember across phases + +- **Before selling the Website or App:** put the ROADMAP §10 prices in + `crosscode-site/src/data/pricing.mjs` *and* the Hub's `frontend/src/lib/tiers.ts` (plus + `backend/src/utils/billing/tiers.js`) in the same phase, so the site and the Hub never disagree. +- **A phase isn't done until crosscode-site matches it** (ROADMAP §9, "Updating crosscode-site"). +- Servers stay **PM2 + nginx** (no Docker), with one database per product per church, under + `/var/www/sites//`. +- **Prisma in the monorepo:** each app other than Events sets its own generator `output`, so + hoisted clients don't overwrite each other (EVENTS-2.2-PLAN §2). +- **AI for a church:** set the licence's monthly AI cap above R0 on the Hub; with no cap the + buttons don't show (rules in Events' handover, "AI rules"). +- **Releasing:** branch → merge → tag (`@`) → push, with a CHANGELOG entry, and + `npm run check` first. Pushes to c-git often fail authentication the first time; retry once. diff --git a/docs/ROADMAP-v3.md b/docs/ROADMAP-v3.md new file mode 100644 index 0000000..ce6dd49 --- /dev/null +++ b/docs/ROADMAP-v3.md @@ -0,0 +1,779 @@ +# Cross Code — Road to three products + +Planned work to go from one product (Cross Events 2.1.x) to three that can be sold separately or +together: **Cross Events**, a **Church Website** and a **Church App**, all managed from one +**Cross Code Hub**. Based on the two concept specs (church website platform, church app v1.1, +3 November 2026), with the changes decided on 2026-11-03 (see [Decisions](#decisions-2026-11-03)). +See ROADMAP-v2.md (Cross Events: `hope-events/docs/`, `apps/events/docs/` from Events 2.2.0) for how +Cross Events got to 2.x. Where things stand now: [HANDOVER.md](./HANDOVER.md). + +**Moved 2026-11-05** from `hope-events/docs/` to the monorepo's `docs/`, since it covers every +product. The Events 2.2.0 move is planned in [EVENTS-2.2-PLAN.md](./EVENTS-2.2-PLAN.md). + +**Theme:** a church can have any mix of products (Events, Website, App, all, or just the +Website). People sign in to all of them with **one account**, and events flow between them in +whatever direction the church chooses. + +**Updated 2026-11-04:** Cross Events moves into the `crosscode-platform` monorepo (§8), every +product is released and deployed the same way with one `crosscode` script (§8, "Releases and +updates"), the Hub tracks releases per product (§5), and the contracts reach the Hub as a file +committed to its repo instead of through a package registry (§2). Cross Events versions in §9 +moved up by one (the move is 2.2.0). See decisions 21–24. + +--- + +## Contents + +1. [The shape](#1-the-shape) +2. [Contracts (shared JSON formats)](#2-contracts-shared-json-formats) +3. [Accounts (shared users)](#3-accounts-shared-users) +4. [Event sync in any direction](#4-event-sync-in-any-direction) +5. [Cross Code Hub (all products)](#5-cross-code-hub-all-products) +6. [Church Website](#6-church-website) +7. [Church App](#7-church-app) +8. [Servers and deployment](#8-servers-and-deployment) +9. [Build order](#9-build-order) +10. [Pricing](#10-pricing) +11. [SEO (every public site)](#11-seo-every-public-site) +12. [Decisions](#decisions-2026-11-03) +13. [Still open](#still-open) + +--- + +## 1. The shape + +Each church gets its own **church stack**: one install per product it has bought, each with its +own process and its own database. The Hub only sees aggregate stats and licences. + +``` + Cross Code Hub (hub.crosscode.co.za) + customers · licences per product · stats · AI proxy · billing + ▲ register / heartbeat / licence (install → Hub only) + ┌───────────────┼────────────────────────────────────────┐ + │ Church stack (e.g. Hope Family Church) │ + │ │ + │ Accounts (accounts.church.co.za) ◄── sign-in (OIDC) ──┤ + │ ▲ ▲ ▲ │ + │ Website (www.) ◄─feed─► Events (events.) ◄─feed─► App (app.) + └─────────────────────────────────────────────────────────┘ +``` + +**Rules** + +1. **No shared databases, ever.** Products only talk over HTTPS using documented contracts (§2). +2. **The Hub is never on the runtime path.** It stays read-only toward installs: installs push to + it, it never reaches into them, and a Hub outage switches nobody off. +3. **One maintained codebase per product.** Each church runs a tagged release of it. Nothing is + built specially for one church. +4. **The origin of a record owns it.** Copies elsewhere are read-only and link back to the origin. + +**Products and what each one owns** + +| Product | Owns | Doesn't do | +|---------|------|------------| +| **Accounts** | People's accounts: name, email, phone, password, 2FA, privacy notice acceptance, news consent | Anything product-specific | +| **Cross Events** | Events with registrations, tickets, payments, check-in, kids, rosters, POPIA toolkit | Website content | +| **Church Website** | Public pages, leaders, ministries, messages (sermons), service times, simple events | Registrations or payments | +| **Church App** | House of Prayer, announcements, devotionals, reading plans, groups, care, simple events | Registrations or payments | + +--- + +## 2. Contracts (shared JSON formats) + +Everything that crosses between products is defined **once**, in a shared package +`@crosscode/contracts` (zod schemas + generated JSON Schema + TypeScript types + sample payloads). +Every product, including Cross Events and the Hub, uses it. This is what keeps the key fields the +same in every product's JSON. + +| Contract | Used for | +|----------|----------| +| `crosscode.event/1`, `crosscode.event-feed/1` | One event, and the feed every product publishes and reads (with the `event.changed` webhook) (§4) | +| `crosscode.church/1` | The church profile: name, logo, colours, campuses, service times, contact details. Set once and shared | +| `crosscode.identity/1` | The claims Accounts puts in a sign-in token, and the back-channel calls (`user.updated`, `user.deleted`, `user.export`) | +| Hub protocol v2 | Register, heartbeat, licence token, AI calls, for every product (§5). Today's protocol (Cross Events 2.1, Hub 1.7) is v1, in [hub-protocol.md](./hub-protocol.md) | + +**Versioning** + +- Adding an **optional** field keeps the version (`/1`). Consumers ignore fields they don't know. +- Removing or renaming a field, adding a value to an enum (older consumers would refuse it), or changing a meaning needs a new version (`/2`). The old + version is served alongside it until every install has updated, as with `/api/v2`. +- Every payload carries its `schema` name, so a consumer always knows what it's reading. +- The package lives in the platform monorepo (§8). Every product there (Events, Accounts, Website, + App) uses it as a workspace, so no registry is involved. +- **The Hub** (its own repo, §8) uses a packed release committed to its repo + (`vendor/crosscode-contracts-.tgz`, `"@crosscode/contracts": "file:vendor/…"`), so its + deploys only need git and the public npm registry, and the lockfile pins the file's checksum. + Upgrading is a normal commit with the new file. Gitea's package registry isn't used (decided + 2026-11-04): a registry on the deploy path would need a token on every server and could block a + deploy or a roll back. + +--- + +## 3. Accounts (shared users) + +A small per-church **OpenID Connect** provider (`oidc-provider` on the server, `openid-client` in +each product). Every church stack has one, including website-only churches (where it only holds +staff logins). + +**Why a separate service:** if one product held the users, cancelling that product would take +everyone's login with it. With Accounts on its own, products can be added or cancelled without +touching anyone's account. + +### What lives where + +| Accounts | Each product (keyed by the account's `sub`, a UUID) | +|----------|-----------------------------------------------------| +| 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 | — | + +### How it works + +- 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. +- **Sign-in always returns you to where you came from.** When a product sends someone to + `accounts.church.co.za` (they clicked Sign in, or opened a page that needs sign-in), it passes + the exact page they were on (path and query, e.g. `/events/youth-camp/register?ticket=adult`) + in the OIDC `state`. After sign-in, Accounts sends them back to **that product and that page**, + not to a dashboard or the account page. This holds through every step in between: 2FA, + "forgot password" and the reset link, creating a new account, the news question and privacy + notice re-acceptance. (Cross Events works this way today with `?redirect=`; the move to Accounts + keeps it.) + - **Safe redirects only:** Accounts only returns to the registered `redirect_uri` of a linked + product of the same church (exact match, no wildcards), and the product only accepts a + relative path from `state` (starting with a single `/`). Anything else falls back to the + product's home page. No open redirects. + - **Signing out** works the same way (`post_logout_redirect_uri`): you end up back on the + product you signed out from, signed out of all of the church's products. + - Opening `accounts.church.co.za` directly (nothing to return to) shows the account page. + - Tests: Playwright checks for each product that signing in from a deep link (including through + 2FA and a password reset) lands back on that exact page, and that a foreign or absolute + return URL is refused. +- **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.3.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 + its part (`user.export`) and bundles the answers. "Delete my account" deactivates the account at + once, then sends `user.deleted` to each product when an admin approves (the existing Events + rules apply: it waits while the person has an open registration for an upcoming event). +- Back-channel calls are signed with a secret per product link and retried through pg-boss. +- Accounts gets its own access log entries for exports and admin views of people. + +### Moving Cross Events onto Accounts (Cross Events 3.0) + +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 (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. +- Every place Events sends someone to sign in today (`/login?redirect=…`, `useRequireAuth`, the + register / ticket flows) goes to Accounts with the current page as the return target, so + members land back exactly where they were (§3, "Sign-in always returns you to where you came + from"). Old `/login?redirect=…` links keep working by forwarding to Accounts with the same target. +- Staff accounts work the same way: roles stay in Events. + +--- + +## 4. Event sync in any direction + +Every product can **publish** the events it owns and **show** events from its siblings. Each +install has two settings: + +- **Publish my events:** on / off. +- **Show events from:** ☐ Events ☐ Website ☐ App (only linked products are listed). + +That covers every setup: Events → Website and App; Events and App → Website; everything to +everything; or nothing. + +### Rules + +- **Only the origin edits an event.** Imported events are read-only copies with a link back. + Corrections happen at the origin and arrive with the next sync. +- **No loops:** a product only publishes events it *originated*, never ones it imported. +- **No duplicates:** an event is identified by `origin.product` + `origin.id`. +- **Only Cross Events takes registrations and payments.** The Website and App can create + **simple events** (title, dates, place, image, description, and an optional external link or + contact instructions). +- Each product keeps the last good copy of each feed. If a source is down, its events keep + showing, and admins see "last synced 2 hours ago". + +### Transport + +- `GET /api/feed/v1/events?updatedSince=` → `{ schema: "crosscode.event-feed/1", generatedAt, events: [...], deleted: [...] }`. + Public events only, so no personal information ever goes through the feed. +- A signed webhook `event.changed` tells consumers to fetch straight away. +- Consumers also poll every 15 minutes as a fallback (pg-boss job). +- Timeouts, retries with back-off, and one failing source never blocks another. + +### `crosscode.event/1` + +```json +{ + "schema": "crosscode.event/1", + "id": "8f1c2a4e-…", + "origin": { + "product": "events", + "installId": "inst_…", + "url": "https://events.hopefamily.co.za/events/youth-camp" + }, + "status": "published", + "updatedAt": "2026-11-03T10:00:00Z", + "title": "Youth Camp 2026", + "summary": "Three days at Camp Wartburg", + "description": "Sanitised markdown…", + "imageUrl": "https://events.hopefamily.co.za/uploads/…", + "timezone": "Africa/Johannesburg", + "startsAt": "2026-03-14T08:00:00Z", + "endsAt": "2026-03-16T14:00:00Z", + "allDay": false, + "sessions": [ + { "id": "…", "label": "Day 1", "startsAt": "…", "endsAt": "…", "location": null, "cancelled": false } + ], + "location": { "name": "Camp Wartburg", "address": "…", "onlineUrl": null }, + "campus": { "slug": "meyerton", "name": "Meyerton" }, + "series": { "id": "…", "name": "Youth Camp" }, + "tags": ["youth"], + "registration": { + "mode": "origin", + "url": "https://events.hopefamily.co.za/events/youth-camp", + "status": "open", + "opensAt": null, + "closesAt": "2026-03-10T22:00:00Z", + "priceFrom": { "amountCents": 45000, "currency": "ZAR" } + } +} +``` + +| Field | Values / notes | +|-------|----------------| +| `origin.product` | `events` · `website` · `app` | +| `status` | `published` · `cancelled` (unpublished or deleted events go in `deleted`) | +| `sessions` | Empty for a single-date event. `startsAt` / `endsAt` are always the first start and last end | +| `campus` | `null` = all campuses or campuses off | +| `registration.mode` | `origin` (register at the origin, Events only) · `external` (a link) · `contact` (instructions in the description) · `none` | +| `registration.status` | `open` · `not_open` · `closed` · `full` · `waitlist`. Only Events sends anything but `open` | +| `priceFrom` | Lowest current price in cents, or `null` for free / not applicable | + +--- + +## 5. Cross Code Hub (all products) + +The Events Hub (`joshua/events-hub`, Hub 1.7.0) becomes **Cross Code Hub 2.0**: one place for every +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). **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 + integration comes later. +- **Protocol v2:** adds `product` to register and heartbeat, and per-product stats (aggregate + counts only, as today: no personal information). The Hub keeps accepting protocol v1, so Events + installs keep reporting until they update. +- **Sibling discovery:** the licence token carries the `customerId`. The heartbeat reply lists the + church's other installs (product, URL, public key; nothing else). Each product shows them + under **Settings → Linked products** with a **Connect** button that sets up the feed (§4) and + the Accounts client (§3). The list is cached, so a Hub outage changes nothing. +- **AI:** the existing proxy, cap and markup serve every product. Usage is recorded per product, + and the cap stays per customer. +- **Releases per product.** Each product has a release source: repo, tag pattern and notes + file. Releases carry a `product`, so "update available", **Request update** and "versions + behind" work per install. + + | Product | Repo | Tags | Notes | + |---------|------|------|-------| + | Events | `crosscode-platform` | `events@2.2.0` on | `apps/events/WHATS-NEW.md` | + | Events (before the move) | `hope-events` (archived) | `v1.0.0` … `v2.1.x` | its `WHATS-NEW.md` | + | Accounts | `crosscode-platform` | `accounts@1.2.3` | `apps/accounts/WHATS-NEW.md` | + | Website | `crosscode-platform` | `website@1.2.3` | `apps/website/WHATS-NEW.md` | + | App | `crosscode-platform` | `app@1.2.3` | `apps/app/WHATS-NEW.md` | + + `contracts@` tags are ignored (nobody installs them). The Events releases before the move stay + (today's sync removes releases without a tag; with two sources it only removes a release + missing from its own source). +- **Requirements between products.** A release can say what it needs, in its `WHATS-NEW.md` + heading: `## 3.0.0 — requires accounts 1.2.0` (several: `requires accounts 1.2.0, website + 1.1.0`; it can be combined with `— urgent`). The Hub shows it on the install, and **Request + update stays disabled** ("Accounts must be updated to 1.2.0 first") until the church's install + of that product reports that version or later. The `crosscode` script checks the same thing + before it deploys (§8). By default products never need to update together: the contract rules + (§2) and protocol v1 + v2 make that possible, so requirements are only for real breaking moves + such as Events 3.0. +- **Request update** works for every product. The Hub still never runs anything on an install. +- **Domain:** `hub.crosscode.co.za`. `events-hub.crosscode.co.za` stays as an alias so existing + installs keep working. +- Dashboard: installs per product, versions behind latest, health, licence status, monthly + recurring revenue, overdue invoices. + +--- + +## 6. Church Website + +A professional public website the church manages itself. From the website spec, adjusted. + +### Public site + +- **Pages:** Home, New Here? / Plan Your Visit, About (story, mission, vision, values, beliefs), + Leadership, Ministries (overview + one page each), Events (list, detail, calendar, past), + Messages (sermons, series), Give (information and provider links), Contact, Privacy / + POPIA / safeguarding / terms. +- **Homepage order:** hero with Plan Your Visit, service times and location, mission, + introduction, ministries and team, upcoming events, latest message, final invitation (each + template starts from this and arranges it its own way, below). +- Server-rendered, fast on a phone, accessible (WCAG 2.2 AA, axe checks in Playwright), with + the SEO in §11. + +### Templates: each church its own identity + +The website is the most personal of the products, so churches shouldn't all look the same. +The Website ships with **four templates**, each with its own **layout and design**. The church +picks one; its **logo and colours come from the church profile** (`crosscode.church/1`), and its +**content fills into the chosen template**. + +| Template | Character | Layout and design | +|----------|-----------|-------------------| +| **Heritage** | Traditional, dignified | Centred logo and navigation above a framed hero image; serif headings; generous margins; content in a single centred column with thin rules between sections; service times in a formal panel | +| **Bold** | Modern, energetic | Full-screen photo or video hero with large overlaid headline; sticky transparent header; strong sans-serif type; full-bleed alternating image / text bands; large "Plan your visit" call to action | +| **Community** | Warm, friendly, family | Logo left, rounded friendly type; a hero with photo collage; content in cards (ministries, events, messages as a grid); soft shapes and the church colour as tinted backgrounds; people's faces prominent | +| **Clean** | Minimal, calm | Small header, lots of white space; typographic hero (no photo needed, good for churches without good photos); narrow text column; lists rather than cards; colour used sparingly as accent | + +**How it works** + +- **One content model, four presentations.** Content is structured (pages, sections, ministries, + leaders, messages, events, service times), never tied to a template. Every template renders + every section type in its own way, so **switching template never loses content**. +- **The template sets the layout:** header and navigation style, hero type, how each section + type looks, section spacing, typography (with two or three font pairings to choose from per + template), shapes and image treatment, and the default homepage order. Within it, churches can + reorder, hide and show the approved sections, but not edit layout freely, so a site always + looks designed. +- **Colours from the church, made safe:** the template builds its palette (tints, shades, text + colours, buttons) from the church's primary and accent colours, and checks contrast (WCAG AA). + A colour that fails is darkened or lightened automatically, and the admin is told why. +- **Logo** in the template's header and footer positions; the icon (from the profile) for the + favicon and share images. +- **Choosing:** the setup checklist starts with "Choose your template", showing all four + **previewed with the church's own logo, colours and content** (sample content until they have + their own). Switching later goes through preview → publish like any other change. +- **Templates are part of the product**, not per church (§1, rule 3): they improve in each + release for every church using them. More templates can be added in later releases. +- Every template meets the same bar: tested in Playwright (layout at phone / tablet / desktop, + axe accessibility) and with the §11 SEO checks. + +### Admin (`www.church.co.za/admin`, signed in through Accounts) + +- Dashboard with a setup checklist, recent edits and drafts. +- **Template:** choose and preview the template, font pairing, and which homepage sections show + in which order. +- Pages and sections, About, Leadership, Ministries, Messages, Media library, Contact and + service times, Navigation, Settings (including SEO and search engine verification, §11). +- **Events:** simple events, plus the feed settings (§4) and sync health. +- **Draft → preview → publish**, archive instead of delete, an audit log of who changed what. +- **Roles:** Owner, Admin, Editor, Ministry leader (own ministry only), Viewer. + +### Not in the first release + +Prayer requests and other forms with personal information (they belong in the App), a member +directory, online giving processing. + +--- + +## 7. Church App + +A church-branded **web app** (PWA) at `app.church.co.za`, added to the home screen. No app-store +release. From the app spec, adjusted. + +### House of Prayer (the headline) + +- **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 + 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 + prayer needs an explicit choice. Moderation (approve, redact, remove) and a safeguarding + escalation route. Never used for analytics or AI. +- **Campaigns and testimonies:** time-bound campaigns with collective progress (no rankings), + testimonies moderated before publishing. + +### Other modules (each can be switched off by the church) + +Announcements, devotionals, reading plans, sermons (shared with the Website where both exist), +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 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 + +Member, Prayer coordinator, Content admin, Pastoral care, Church admin. Public content can be +browsed without an account. Personal actions need sign-in through Accounts. + +--- + +## 8. Servers and deployment + +**PM2 and nginx, like Cross Events today.** No Docker. + +- **Per church:** one PM2 process (or front/back pair) per product, one PostgreSQL database and + database user per product, its own `.env`, secrets, uploads folder, logs and backups. Names + carry the church slug (`hopefamily-website`, `hopefamily_website` DB, …). +- **One `crosscode` script** installs and updates every product (below, "Releases and updates"), + built from today's `install.sh` and `deploy.sh`: a tagged update with a database backup, + migrations, build, restart and roll back on failure, for whichever products you name. +- **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. + +### Repositories + +| Repo | What | +|------|------| +| `joshua/crosscode-platform` | **Every product a church installs**, and what they share: `apps/events` (Cross Events, moved here in 2.2.0), `apps/accounts`, `apps/website`, `apps/app`, `packages/contracts`, `packages/ui`, `packages/seo` (§11), and the `crosscode` script (`scripts/`) | +| `joshua/hope-events` | Cross Events up to 2.1.x. **Archived** after the move (read-only, README points to the monorepo), and kept so installs that haven't moved yet can still deploy or roll back a `v2.1.x` tag | +| `joshua/events-hub` | Cross Code Hub (renamed in the UI; repo name can stay). Stays on its own: it runs on its own server, is never installed for a church, and is deployed with its own `scripts/deploy.sh`. Gets the contracts as a committed file (§2) | +| `joshua/crosscode-site` | The marketing site (crosscode.co.za). Updated at the end of every phase that changes what's on sale or what a product does (see §9, "Updating crosscode-site") | + +**Stack:** the same as Cross Events (Next.js, Express, TypeScript, Prisma, PostgreSQL, pg-boss, +Playwright, Jest), so code and habits carry over. + +### Releases and updates + +**What doesn't change:** git is how code reaches a server, the Hub only records releases and +passes on update requests (it never deploys, §1 rule 2), and Joshua runs the deploys. + +**Releasing.** Each product is tagged on its own in the monorepo: `events@2.2.0`, +`accounts@1.0.0`, `website@1.0.0`, `app@1.0.0` (and `contracts@1.0.0`, which nobody installs). +Each app keeps its own `CHANGELOG.md` and church-facing `WHATS-NEW.md` in its folder. The release +routine is as today (branch → merge → tag → push), with the product's name in the tag. The Hub +picks the tags up per product (§5). + +**On a server.** Each church gets a folder with a config file and one checkout of the monorepo +per product, each at that product's own tag: + +``` +/var/www/sites/ + hopefamily/ + church.env slug, products, domains, ports, PM2 names, database names, folders + accounts/ crosscode-platform at accounts@1.0.0 + events/ crosscode-platform at events@3.1.0 + website/ crosscode-platform at website@1.2.0 + gracechurch/ + … +/opt/crosscode/tools/ the crosscode script (a checkout of main, updated before every run) +``` + +Every church's installs live under **`/var/www/sites//`** (decided 2026-11-04; the +existing Events installs are in `/var/www` today and move there). The script finds churches by +their `church.env`, so `--every-church` is every folder in `/var/www/sites` that has one. A +product's folder can be somewhere else if `church.env` says so, but the standard layout is the +default for `install` and `adopt`. PM2 names, nginx names and database names keep what an install +already has. Each checkout installs and builds only its own app (`npm ci -w apps/website`, its +own migrations), so a Website install never builds Events. + +**The script** (run as root or the app user; `crosscode help` lists everything): + +| Command | What it does | +|---------|--------------| +| `crosscode deploy [events] [website] [app]` | Updates **Accounts, always**, plus the products named, to their latest released tags. Products not named aren't touched | +| `… --version events@3.1.0` | A specific release instead of the latest (repeatable, one per product) | +| `… --main` | The latest main instead of a tag (for testing on a staging church only) | +| `crosscode deploy --check` | Only the checks below; changes nothing | +| `crosscode deploy --every-church [events] …` | The same deploy for every church on this server, one after the other | +| `crosscode status []` | Each product's version, latest release, health (from `/health`) and last backup | +| `crosscode install --products events,website --domain … ` | A new church (from today's `install.sh`): Accounts always, plus the products named; databases, `.env` files, PM2, nginx and certificates; prints the DNS records needed | +| `crosscode add app` | Adds a product to an existing church | +| `crosscode adopt --events-dir /var/www/` | Once per existing Cross Events install: moves it onto the monorepo and into `/var/www/sites//events` (below) | + +Before Accounts exists (until phase 3), "always Accounts" is skipped for churches that don't have +it yet. + +**How a deploy runs** + +1. **Checks first, for every product named; if one fails nothing is touched:** files changed by + hand in a checkout (as `deploy.sh --check` today), the Node version, and the requirements of + the target releases (§5: `events@3.0.0` needs `accounts@1.2.0`, and Accounts is either already + there or part of this deploy). +2. **In a fixed order: Accounts, then Events, Website, App.** Each product: database backup → + check out its tag → install and build its app → migrations → PM2 reload → `/health` answers + with the new version. If any step fails, **that product rolls back** to its previous tag (as + `deploy.sh` does today) and the deploy stops there. +3. Products already updated in this run stay updated (no product needs its siblings to update + with it, §5), and the summary says which ones were updated, which rolled back and which weren't + reached. + +**Moving existing Cross Events installs (Events 2.2.0, `crosscode adopt`).** Once per server +install, run by Joshua. It: + +1. Moves the install's folder from `/var/www/` to `/var/www/sites//events` + (skipped if it's already there, e.g. moved by hand) and writes `church.env`. +2. Changes the checkout's remote to `crosscode-platform` and moves the install's own files to + the new paths: `backend/.env` → `apps/events/backend/.env`, likewise the frontend `.env`, + `backend/public/uploads/`, `backend/backups/`, `backend/data/*.json`, and + `ecosystem.config.js` with its `cwd` paths updated. +3. Checks out `events@2.2.0`, builds, and **re-registers the PM2 processes** under their existing + names from the new folder (`pm2 delete` + `pm2 start` + `pm2 save`: PM2 remembers the folder a + process was started from, so a reload isn't enough after a move). + +The PM2 names, nginx config (it only proxies to ports, so it doesn't change when the folder +moves), database and its name stay the same. If anything fails it moves everything back, returns +to the `hope-events` remote and the version it was on, and starts PM2 from the old folder again. +Installs that haven't moved yet keep working with `deploy.sh` on the archived repo. + +**Moving a folder by hand before 2.2.0** works too: move it into `/var/www/sites//events`, +then `pm2 delete` its two processes, `pm2 start ecosystem.config.js` from the new folder and +`pm2 save`. `deploy.sh` works from wherever the install is, and `adopt` later sees it's already in +place. + +--- + +## 9. Build order + +| Phase | Version | What | Why this order | +|-------|---------|------|----------------| +| 0 | contracts 1.0.0 | `crosscode.event/1`, `crosscode.church/1`, `crosscode.identity/1`, Hub protocol v2: schemas, generated JSON Schema, docs, sample payloads, the monorepo set up. **Released 2026-11-04** | Everything else depends on them | +| 1 | **Hub 2.0.0** | Cross Code Hub: products, licence per product, per-customer billing with bundles, protocol v2 (v1 still accepted), sibling discovery, AI usage per product, **releases per product with requirements** (§5), contracts as a committed file (§2). **Released 2026-11-05** (crosscode-site address prices merged) | Must exist before a second product is sold, and before Events releases come from the monorepo | +| 1b | **Cross Events 2.2.0** | **Moves into the monorepo** as `apps/events`, with its git history (merged in, not copied); its packages become workspaces; the **`crosscode` script** (`deploy`, `status`, `install`, `adopt`; §8) replaces `scripts/deploy.sh` and `scripts/install.sh`; every install moved with `crosscode adopt`; `hope-events` archived. No feature changes, so a problem is clearly the move | Before more products, so every product is released and deployed the same way from the start | +| 1c | **Cross Events 2.3.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.4.0** | Reports `product: "events"` (protocol v2), **Linked products**, the event feed (publish + show events from siblings), `packages/seo` (§11) with canonical links for imported events | 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 with the **four templates** (§6), admin, simple events + feed, SEO (§11), Hope Family Church as the first church, then a second test church on a different template 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 | 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. **A phase isn't done until +crosscode-site is updated** for it (below), where the phase changes anything the site says. + +### Updating crosscode-site + +The marketing site (`../crosscode-site`, crosscode.co.za) has to match what's actually shipped. +At the end of each phase, update it in the same sitting and deploy it (its `DEPLOYMENT.md`): + +| Phase | What changes on crosscode-site | +|-------|--------------------------------| +| 0 contracts | Nothing | +| 1 Hub 2.0.0 | Bundle discounts (15% / 25%) and the address add-on (own domain R0 · Cross Code address R10 · domain included R25) in `src/data/pricing.mjs`, worded so it's clear the Website and App are still coming. Legal pages if billing terms change | +| 1b Events 2.2.0 | Nothing (the move doesn't change what Cross Events does) | +| 1c Events 2.3.0 | Authenticator app 2FA in the Cross Events feature list (`src/data/cross-events.mjs`) and the security / POPIA wording | +| 2 Events 2.4.0 | "Works with the Church Website and App" (event feed, Linked products) on the Cross Events page, as "coming" until those ship | +| 3 Accounts 1.0.0 | "One sign-in for all your church's products" on the Products page. Accounts isn't sold, so no page or price of its own | +| 4 Website 1.0.0 | **Church Website goes on sale:** `status: "available"` and its own page in `src/data/products.mjs` / `src/pages/products/`, R99 + storage add-on in `pricing.mjs`, **a showcase of the four templates** (a page per template with screenshots of the same demo church in each), screenshots from a demo church (fictional people only), FAQ, home page, contact form product list, `SoftwareApplication` JSON-LD (§11) | +| 5 Events 3.0.0 | Cross Events page: sign-in through the church's shared account. Update screenshots that show the login | +| 6 App 1.0.0 | **Church App goes on sale:** own page, active-member tiers in `pricing.mjs`, House of Prayer screenshots, the bundle examples from §10 | +| 7 App 1.x | New modules added to the App page's feature list as each one ships | + +Prices change in the Hub's `frontend/src/lib/tiers.ts` in the same phase, so the site and the +Hub never disagree. Run the site's tests and build before deploying it. + +### Release checks (before selling a product) + +- Two churches installed from the same tagged release with `crosscode install`, with separate databases, secrets and uploads. +- `crosscode deploy` updates a church from the previous release, and a failure part-way (e.g. a + broken migration) rolls that product back and leaves the others running. +- Church A's admin can't read or change Church B's data through direct API calls. +- Stopping one church's install, or the Hub, leaves the others running. +- A feed source going down: its last events keep showing, the other sources keep working. +- Signing in once works across all of a church's products; deleting an account reaches every product. +- Signing in from any page of any product returns to that same page (including through 2FA and a + password reset), and a foreign return URL is refused. +- crosscode-site shows the product as available, with its page, prices and screenshots. +- The §11 SEO checks pass (Playwright and Lighthouse), for the Website in all four templates. +- A database backup is restored successfully. + +--- + +## 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.) + +--- + +## 11. SEO (every public site) + +Every public site gets search engine optimisation at least as good as Cross Events has today: +the **Church Website**, **Cross Events**, the public parts of the **Church App**, and the +marketing site **crosscode.co.za**. A church should be found when someone searches "church near +me", its name, or an event it's running. + +### The baseline (what Cross Events does now, for every product) + +- **Server-rendered HTML** with a unique `` and meta description on every page. +- **Canonical URL** on every page (tracking tags such as `?src=` dropped). +- **Open Graph and Twitter cards** with an image on every page. Pages without their own image + get a share image generated from the church's logo and colours. +- **`sitemap.xml`** generated from published content and refreshed hourly, and **`robots.txt`** + that points to it and keeps admin, sign-in and personal pages out. +- **schema.org JSON-LD** (e.g. `Event` on event pages, as `frontend/src/lib/eventSchema.ts` does, + checked with Google's Rich Results Test). +- Readable slugs, with **301 redirects** when a slug changes; real 404 status for missing pages; + `lang="en-ZA"`. +- **Fast and accessible:** responsive images with required alt text, good Core Web Vitals on a + phone (LCP under 2.5 s, CLS under 0.1), WCAG 2.2 AA. + +The JSON-LD builders and meta helpers live in a shared `packages/seo` in the platform monorepo, +built on `@crosscode/contracts`, so Events, the Website and the App produce the same schema.org +data from the same `crosscode.event/1` and `crosscode.church/1`. Cross Events moves its +`eventSchema.ts` onto it in 2.4.0. + +### Per product + +| Product | SEO | +|---------|-----| +| **Church Website** | JSON-LD `Church` (name, logo, address, geo, phone, service times, social links) on the home and contact pages, so the church shows up in local search and maps; `Event` for its events; `VideoObject` / `PodcastEpisode` for messages; `BreadcrumbList`. Admin: per-page title and description (with a Google-style snippet preview), warnings for a missing description, alt text or a too-long title, and a field for Google Search Console / Bing verification. Setup checklist links to setting up a Google Business Profile. All four templates produce the same markup and pass the same checks | +| **Imported events** | A copy of another product's event (§4) has `<link rel="canonical">` pointing to the **origin's** page, so search engines see one event, not three. Only the origin is in its sitemap | +| **Cross Events** | Already has the baseline. Gains the shared `packages/seo`, `Organization` / `Church` data from the church profile, and the canonical rule for imported events | +| **Church App** | Public content (events, devotionals, sermons, announcements marked public) gets the baseline. Everything signed in, prayer and care is `noindex` and kept out of the sitemap. **Prayer requests are never indexable** | +| **Accounts** | `noindex` everywhere, blocked in `robots.txt`: sign-in pages should never appear in search | +| **Cross Code Hub** | `noindex` everywhere | +| **crosscode.co.za** | Already has canonical URLs, Open Graph, `Organization` / `WebPage` JSON-LD, sitemap and robots. Adds `SoftwareApplication` JSON-LD with prices (`Offer`) on each product page, `FAQPage` on the FAQs, a page per Website template, and Search Console / Bing set up and checked after each site update (§9, "Updating crosscode-site") | + +### Moving addresses + +When a church moves from the Cross Code address to its own domain (§10), every old URL +**301-redirects** to the same page on the new domain for 12 months, so it keeps its search +ranking. + +### Checks (in every product's tests) + +- Playwright: every public page has a title, description, canonical, `og:image`, exactly one + `<h1>`, and JSON-LD that parses; the sitemap lists the published pages and nothing private; + `robots.txt` blocks admin and sign-in; `noindex` pages really are `noindex`. +- Lighthouse (mobile) on a demo church's home, event and message pages, in every template: + SEO 100, accessibility 95+, performance 90+. + +--- + +## Decisions (2026-11-03) + +| # | Question | Decision | +|---|----------|----------| +| 1 | Separate infrastructure | **Yes:** one install and database per product per church, no shared databases, Hub not on the runtime path | +| 2 | Shared users | **A separate Accounts service per church** (OpenID Connect), used by every product. Roles stay per product | +| 3 | Docker | **No.** PM2 and nginx, like Cross Events | +| 4 | Simple events in the Website and App | **Yes.** Only Cross Events takes registrations and payments. (The app spec's "no event creation in the App" is overruled) | +| 5 | Event sync | Any direction, chosen per install ("Publish my events", "Show events from"). One shared format, `crosscode.event/1`. Only originated events are published | +| 6 | Domains | `www.`, `events.`, `app.` (and `accounts.`) on the church's own domain | +| 7 | Hub | Becomes **Cross Code Hub**: every product's licences, stats, AI and billing in one place, still read-only toward installs | +| 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.3.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) | +| 17 | Sign-in return | Signing in through `accounts.church.co.za` always returns to the product and page the person came from (through 2FA, reset, sign-up and notice steps), with exact-match redirect URIs only (§3) | +| 18 | Marketing site | crosscode-site is updated at the end of every phase that changes what's on sale or what a product does (§9) | +| 19 | Website templates | **Four templates** (Heritage, Bold, Community, Clean), each with its own layout and design. Colours and logo come from the church; content fills the chosen template; switching never loses content (§6) | +| 20 | SEO | Every public site (Website, Events, App's public pages, crosscode.co.za) gets at least Cross Events' SEO, through a shared `packages/seo`; Accounts and the Hub are `noindex` (§11) | + +**Added 2026-11-04** + +| # | Question | Decision | +|---|----------|----------| +| 21 | Repos | **Cross Events moves into `crosscode-platform`** (`apps/events`, Events 2.2.0, history kept); `hope-events` is archived. The Hub stays in its own repo (own server, never installed for a church) | +| 22 | Contracts for the Hub | A packed release **committed to the Hub's repo** (`file:vendor/…`), not Gitea's package registry, so no deploy depends on a registry or a token (§2) | +| 23 | Deploying | **One `crosscode` script** for every product, with every church under `/var/www/sites/<church>/<product>`: `crosscode deploy <church> [events] [website] [app]` always updates Accounts and then the products named, in a fixed order, each rolled back on its own if it fails. Still git checkouts of tags, still run by Joshua; the Hub never deploys (§8) | +| 24 | Product requirements | A release can require a minimum version of a sibling (`— requires accounts 1.2.0` in `WHATS-NEW.md`). The Hub **disables Request update** until it's met, and the script refuses to deploy without it (§5, §8) | + +## Still open + +Nothing. crosscode-site is updated at the end of each phase (§9, "Updating crosscode-site"); the +Website and App move from "coming later" to their own pages and prices when they ship. diff --git a/docs/hub-protocol.md b/docs/hub-protocol.md new file mode 100644 index 0000000..0891724 --- /dev/null +++ b/docs/hub-protocol.md @@ -0,0 +1,328 @@ +# Hub protocol (versions 1 and 2) + +The contract between an **install** (one of a church's products: Cross Events, Accounts, Church +Website, Church App) and **Cross Code Hub** (`hub.crosscode.co.za`; `events-hub.crosscode.co.za` +keeps working as an alias). Sections 1–5 describe **version 1**, which Cross Events 2.1 speaks; +**[version 2](#6-protocol-version-2-hub-20)** (every product, Hub 2.0) is section 6. A copy of this +file lives in both repositories (`joshua/crosscode-platform` → `docs/hub-protocol.md`, for every +product; `joshua/events-hub` → `docs/hub-protocol.md`); change both together. (Until 2026-11-05 +the install's copy was in `hope-events/docs/`.) From Hub 2.0 the formats are +defined once, in `@crosscode/contracts` (`crosscode-platform/packages/contracts`, `src/hub.ts`, +with JSON Schema and samples). + +Principles: + +- **Install → Hub only.** The install always starts the conversation; the Hub never calls + into an install. Works behind firewalls, and the Hub has no access to church data. +- **No personal information** is ever sent — counts, versions and health only. Income is + sent as a range, never an amount. +- **A Hub outage never switches a church off.** Licences are signed tokens the install + verifies offline with the Hub's public key. +- Every request carries `protocolVersion`. The Hub accepts the current and the previous + version, so installs waiting to update keep working. + +All bodies are JSON (`Content-Type: application/json`). Times are ISO 8601 UTC strings. +Errors are `{ "message": "...", "code": "..." }` with a 4xx/5xx status. + +--- + +## 1. Public key + +``` +GET /api/public-key +→ 200 { "protocolVersions": [1], "keyId": "k1", "algorithm": "Ed25519", "publicKey": "-----BEGIN PUBLIC KEY-----\n…" } +``` + +Installs ship with the Hub's public key built in (and may refresh it from here). The private +key exists only on the Hub server. + +## 2. Register an install + +Sent once, at the end of `/setup` (licence step) or from Site settings → "Connect to Hub". + +``` +POST /api/installs/register +{ + "protocolVersion": 1, + "licenceKey": "CEH-7K2M-9QXA-P4RT-WD8C", + "install": { + "name": "Hope Family Church", + "url": "https://events.hopefamily.co.za", + "adminContact": { "name": "Jane Admin", "email": "jane@hopefamily.co.za" }, + "version": "1.41.0", + "timezone": "Africa/Johannesburg", + "server": { "node": "20.18.0", "postgres": "16.4", "os": "linux 6.8" }, + "features": { "whatsapp": true, "paymentProviders": ["yoco", "payfast"], "campuses": false } + } +} +→ 201 { + "installId": "inst_…", + "installSecret": "…", // shown once; the install stores it encrypted + "licence": "<licence token>", + "heartbeatIntervalMinutes": 15, + "latestVersion": "1.41.0", + "releases": [ … ], // as in the heartbeat reply (§3); Hub 1.4.0+ + "notices": [ … ] +} +``` + +- `404 LICENCE_NOT_FOUND` — unknown key. `403 LICENCE_REVOKED` — revoked licences can't register. +- One licence = one install. Registering again **from the same URL** re-registers (new + secret, same `installId`). From a different URL → `409 LICENCE_IN_USE` until Joshua releases + the licence in the Hub (e.g. after a move to a new domain). +- The `adminContact` is the one piece of personal information: a work contact for the + church's admin, so Joshua can reach them. It is not used for anything else. +- Rate-limited per IP. + +## 3. Heartbeat + +Every `heartbeatIntervalMinutes` (15) from the install's job queue. + +``` +POST /api/installs/heartbeat +X-Hub-Install: inst_… +X-Hub-Timestamp: 2026-10-24T08:15:00.000Z +X-Hub-Signature: <hex HMAC-SHA256(installSecret, timestamp + "." + rawBody)> +{ + "protocolVersion": 1, + "version": "1.41.0", + "health": { + "uptimeSeconds": 86400, + "db": true, + "jobs": { "mode": "queue", "failedLast24h": 0 }, + "lastBackupAt": "2026-10-24T00:00:12.000Z", // null if none + "disk": { "freeBytes": 21474836480, "totalBytes": 53687091200 }, // null if unknown + "errorsLast24h": 0, // null if not tracked + "pendingMigrations": 0 + }, + "stats": { + "users": 412, + "events": { "active": 3, "upcoming": 5, "total": 61 }, + "registrations": { "last30d": 88, "total": 2310 }, + "tickets": { "last30d": 140, "total": 3901 }, + "checkIns": { "last30d": 96 }, + "messages": { "email30d": 610, "whatsapp30d": 233 }, + "paymentProviders": ["yoco", "payfast"], + "campuses": false, // Site settings → Campuses on/off + "campusCount": 0, // active campuses (0 while off; Cross Events 1.43.0+) + "income": { "last30d": "R5 001–R20 000", "allTime": "R150 001–R250 000", + "eventIncome12m": "R100 001–R150 000" } // eventIncome12m: Cross Events 2.0.2+ + } +} +→ 200 { + "licence": "<fresh licence token>", + "latestVersion": "1.42.0", + "releases": [ // Hub 1.4.0+: newer than the version sent, newest first, at most 20 + { "version": "1.42.0", "releasedAt": "2026-10-27T10:00:00.000Z", "urgent": false, "notes": "- Event series\n- Fixed: …" } + ], + "notices": [ // Hub 1.4.0+: the provider's banners for this install + { "id": "…", "level": "maintenance", "title": "Planned maintenance", "message": "…", + "startsAt": "2026-11-01T16:00:00.000Z", "endsAt": "2026-11-01T16:30:00.000Z", "updatedAt": "…" } + ], + "serverTime": "…" +} +``` + +- **`releases`** — what's new in each version, so the church can decide whether to ask for the + update. The Hub takes the versions from the Cross Events repository's `v*` tags and the notes from + its `WHATS-NEW.md`. `notes` is plain text; lines starting with `- ` are + a list. `urgent` marks security or serious bug fixes: the install shows those in red and doesn't let + admins put them off. The highest release is `latestVersion`. +- **`notices`** — banners Joshua posts on the Hub's Notices page (`level`: `info`, `maintenance` or + `warning`). Sent until `endsAt`, including ones that haven't started, so the install shows each one + from `startsAt` without waiting for a heartbeat. The install shows them to site admins and + supervisors. Notices can also be emailed; that happens on the Hub, not through the install. +- A Hub older than 1.4.0 sends neither field; the install then shows no notes and no notices. +- The signature covers the exact bytes sent. Requests more than **5 minutes** off the Hub's + clock are refused (`401 STALE_REQUEST`); a bad signature is `401 BAD_SIGNATURE`; an unknown or + released install is `404 INSTALL_NOT_FOUND` (the install should show "Reconnect to Hub"). +- **Income bands** (worked out on the install; the amount never leaves it): `R0–R1 000`, + `R1 001–R5 000`, `R5 001–R20 000`, `R20 001–R50 000`, `R50 001–R100 000`, + `R100 001–R150 000`, `R150 001–R250 000`, `R250 001–R400 000`, `R400 001–R700 000`, + `R700 001–R1 000 000`, `R1 000 001–R2 500 000`, `R2 500 001–R5 000 000`, + `R5 000 001–R10 000 000`, `over R10 000 000`. Before Cross Events 2.0.2 the bands stopped at + `over R100 000`, and donations applied to a registration were counted twice. +- **`eventIncome12m`** (Cross Events 2.0.2+) is the band of the last 365 days' event income: + payments less refunds, without donations or sponsorships. Cross Code's licence tiers are billed + on it, so every tier edge is a band edge. Older installs don't send it. +- The Hub keeps every heartbeat for 30 days, then one per install per day. + +## 3a. Update request + +Sent when a site admin presses **Request update** (Site settings → Licence). Installs never update +themselves and never show the deploy command; the request tells Joshua, who updates the server. +Signed exactly like the heartbeat. + +``` +POST /api/installs/update-request +X-Hub-Install / X-Hub-Timestamp / X-Hub-Signature (as in §3) +{ "protocolVersion": 1, "version": "1.41.2" } +→ 201 { "requestedAt": "2026-10-27T09:00:00.000Z", "version": "1.42.0", "alreadyRequested": false, "changed": false } +→ 200 { …, "alreadyRequested": true, "changed": false } // a request for the latest is already open: not emailed again +→ 200 { …, "alreadyRequested": true, "changed": true, "previousVersion": "1.42.0" } + // the open request was for an older version: it now asks for the latest +``` + +- The Hub opens an `update_requested` alert on the install (shown under Alerts) and emails the + alert address once. It is resolved when a heartbeat reports a newer version than before. +- **Changing a request (Hub 1.5.0):** when a request is open for a version that has since been + overtaken, asking again moves it on to the latest version — the alert says "latest is 1.47.3 + (changed from 1.47.0)" and the alert address is emailed once about the change. `version` is + always the version now asked for. A Hub before 1.5.0 doesn't send `changed`; installs then + withdraw the request and ask again (two emails, same result). +- `409 UP_TO_DATE` — the install already runs the Hub's latest version (or none is set). +- Errors as in §3 (`INSTALL_NOT_FOUND`, `STALE_REQUEST`, `BAD_SIGNATURE`). Rate-limited (10 an + hour per IP). A Hub older than this section answers `404 NOT_FOUND`. +- No personal information: not who pressed the button (the Hub already has the admin contact). + +### Withdrawing it + +Sent when a site admin presses **Withdraw request**. Signed like the heartbeat. + +``` +POST /api/installs/update-request/cancel +X-Hub-Install / X-Hub-Timestamp / X-Hub-Signature (as in §3) +{ "protocolVersion": 1 } +→ 200 { "cancelled": true } // the open request was resolved, and Joshua is emailed +→ 200 { "cancelled": false } // there was no open request +``` + +- The Hub resolves the `update_requested` alert and records `update_request_withdrawn` in the install's + history. Rate-limited with update requests. A Hub older than 1.4.0 answers `404 NOT_FOUND`. +- **"Not now"** (no reminders until the next version) stays on the install; the Hub isn't told. + +## 3b. AI (Cross Events 2.0, Hub 1.6.0) + +Installs never hold the Claude API key. Each AI helper call goes through the Hub, which adds the +key, checks the licence's monthly cap, calls Claude and meters the call. Both requests are signed +exactly like the heartbeat. The install keeps its prompts; the Hub stores **no prompt or response +text** — only the install, helper name, tokens, cost and time. + +### Status + +``` +POST /api/installs/ai/status +X-Hub-Install / X-Hub-Timestamp / X-Hub-Signature (as in §3) +{ "protocolVersion": 1 } +→ 200 { "enabled": true, "capReached": false, "capCents": 5000, "usedCents": 812.4, + "usedPercent": 16, "renewsOn": "2026-12-01" } +``` + +- **`enabled: false`** — hide the AI buttons everywhere: the licence's cap is R0, the licence isn't + active (suspended, revoked, or past its grace days), or the Hub's AI isn't set up. +- **`capReached: true`** — show the buttons **disabled** ("This month's AI allowance is used up — it + renews on 1 December"). Reached means there isn't room left for even a small call. +- Amounts are cents (rand) as **charged** to the church, with fractions (a call costs a fraction of a + cent). The month is South African time; `renewsOn` is the 1st of the next month. + +### A helper call + +``` +POST /api/installs/ai/complete +X-Hub-Install / X-Hub-Timestamp / X-Hub-Signature (as in §3) +{ + "protocolVersion": 1, + "helper": "draft_event", // lower-case name, for usage reports + "system": "…", // the helper's fixed instructions (cached by Claude) + "input": "…", // this request's text + "schema": { … }, // optional JSON schema: the reply is JSON in that shape + "maxTokens": 2000, // 1–8000 + "effort": "low" // optional: low (default) | medium | high +} +→ 200 { "output": "…" | { … }, // text, or the parsed JSON when a schema was given + "usage": { "inputTokens": 1840, "outputTokens": 420 }, + "chargedCents": 0.31, + "status": { …as above… } } +``` + +- **Errors** are `{ code, message, status }` — `status` is the new AI status, so buttons can disable + straight after the call that used up the allowance: + - `402 AI_CAP_REACHED` — this call could pass the cap (checked before calling Claude). + - `403 AI_OFF` (cap R0) · `403 LICENCE_INACTIVE` · `503 AI_NOT_CONFIGURED` (Hub not set up). + - `422 AI_REFUSED` — Claude declined. `502 AI_INCOMPLETE` — the answer hit `maxTokens`. + `502 AI_FAILED` — not usable (e.g. JSON in the wrong shape). These still cost what was used. + - `503 AI_BUSY` / `503 AI_UNAVAILABLE` — Claude unreachable or rate-limited; nothing is charged. + - `400 BAD_REQUEST`, `413 AI_INPUT_TOO_LARGE` (about 90 000 tokens), and the §3 errors. +- **Metering:** real cost = tokens × the model's price × the exchange rate set in the Hub; charged = + real × (1 + markup). The cap counts charged rand. Before calling Claude the Hub holds the worst + case (an over-estimate of the prompt, plus `maxTokens`) against the cap in one transaction per + install, so calls at the same moment can't pass it; afterwards the hold becomes the real amount. +- Rate-limited to 60 a minute per IP (against runaway loops; money is limited by the cap). +- A Hub older than 1.6.0 answers `404 NOT_FOUND`: the install treats that as "AI off". + +## 4. Licence token + +`hel1.<payload>.<signature>` — `payload` is base64url JSON, `signature` is the base64url +Ed25519 signature of the ASCII string `hel1.<payload>`. + +```json +{ + "v": 1, + "licenceId": "lic_…", + "installId": "inst_…", + "customer": "Hope Family Church", + "plan": "standard", + "status": "active", // active | suspended | revoked + "licenceExpiresAt": "2027-10-31T21:59:59.000Z", // null = no end date + "graceDays": 14, + "issuedAt": "2026-10-24T08:15:00.000Z", + "validUntil": "2026-11-23T08:15:00.000Z", // issuedAt + 30 days + "limits": { "aiMonthlyCapCents": 0 } // the AI cap (§3b); 0 = AI off +} +``` + +### What the install does with it + +The install keeps the newest valid token (signature checks out, `installId` matches) and works +out its state: + +| State | When | What happens | +|-------|------|--------------| +| **active** | `status` is active and now is before `min(licenceExpiresAt, validUntil)` | Everything works | +| **grace** | after that date, for up to `graceDays` | Everything works; **only site admins** see a banner "Licence needs renewing — X days left" | +| **suspended** | `status` is suspended, or grace has run out | Read-only: events can't be created or edited; no new registrations or payments. Tickets still scan; admins can view and export all data; privacy requests still work | +| **revoked** | `status` is revoked | Same as suspended, with a permanent banner | +| **unlicensed** | never connected, or the Hub answered `INSTALL_NOT_FOUND` (the install drops its token) | Same as suspended (events can't be created or edited either); admins see "Connect to Hub" | + +`validUntil` is refreshed by every heartbeat, so a Hub outage only matters after 30 days (then +grace starts). Blocking the Hub can't keep a suspended licence active for more than 30 days. + +## 5. Versioning + +- `protocolVersion` goes up only for changes an older install can't handle. Adding optional + fields to a heartbeat or a token doesn't need a new version — both sides ignore fields they + don't know. +- The Hub accepts protocol `N` and `N-1`; anything else is `400 UNSUPPORTED_PROTOCOL`. + +## 6. Protocol version 2 (Hub 2.0) + +The formats are in `@crosscode/contracts` (`hub.registerRequestSchema`, `hub.heartbeatRequestSchema`, +… with JSON Schema in `schemas/hub-*.json` and samples in `samples/hub-*.json`). The Hub accepts +versions 1 and 2 (`/api/public-key` lists `[1, 2]`); a v1 request is treated as Cross Events and +answered exactly as in sections 1–5. Signing, offline licence checks, update requests and AI calls +are as in version 1. + +What version 2 changes: + +| | Version 1 | Version 2 | +|---|---|---| +| Who | Cross Events | Every product: `product` is `events`, `accounts`, `website` or `app` | +| Licence keys | `CEH-…` | `CEH-` Events, `CCA-` Accounts, `CCW-` Website, `CCP-` App | +| Register | as §2 | adds `product` (must match the licence: `409 WRONG_PRODUCT`) and `install.publicKey` (the install's Ed25519 public key, PEM) | +| Heartbeat | as §3 | adds `product` (must match the install: `409 WRONG_PRODUCT`); `stats` per product (Events as v1; Website: pages, messages, events, editors, `storage`; App: `activeMembers90d` band, modules, prayer coverage; Accounts: accounts, 2FA methods) | +| Replies | as §2, §3 | add `linkedProducts`: the church's other installs in use that have a public key, as `{ product, installId, url, publicKey }`, nothing else. Releases carry `requires` (below) | +| Bodies | checked by hand | checked against the contract schemas: `400 INVALID_REQUEST` with the field that's wrong; unknown fields are dropped | +| Licence token | as §4 | also `customerId` and `product` (still `v: 1`; a v1 install ignores them). `limits.aiMonthlyCapCents` is the church's cap | + +**Releases per product.** An install is told its own product's releases and latest version. A +release can need a minimum version of a sibling (`— requires accounts 1.2.0` in its WHATS-NEW.md +heading): v2 replies carry it as `requires: [{ product, version }]`, and an update request answers +`409 REQUIREMENT_NOT_MET` (with `requirements: [{ product, version, current }]` and a message saying +what's needed) until the church's install of that product runs that version or later. + +**AI.** The monthly cap and markup are the church's, shared by all its installs: a call from any of +them counts what all of them used this month. + +**Moving an install to v2** (e.g. Cross Events 2.4.0): register again with `protocolVersion: 2`, +the product and a public key (same licence and address: same install id, new secret), then send v2 +heartbeats. Nothing on the Hub needs changing. diff --git a/package.json b/package.json index 26a4151..1dd2ef4 100644 --- a/package.json +++ b/package.json @@ -2,7 +2,7 @@ "name": "crosscode-platform", "version": "0.0.0", "private": true, - "description": "Cross Code platform monorepo: Accounts, Church Website, Church App and the shared contracts (see docs/ROADMAP-v3.md in hope-events)", + "description": "Cross Code platform monorepo: Accounts, Church Website, Church App and the shared contracts (see docs/ROADMAP-v3.md)", "workspaces": [ "packages/*", "apps/*" diff --git a/packages/contracts/src/hub.ts b/packages/contracts/src/hub.ts index fe8e3da..dac298e 100644 --- a/packages/contracts/src/hub.ts +++ b/packages/contracts/src/hub.ts @@ -4,7 +4,7 @@ import { TWO_FACTOR_METHODS } from "./identity"; /** * Hub protocol v2 — between every Cross Code install and Cross Code Hub (ROADMAP-v3 §5). - * Protocol v1 is the one in `hope-events/docs/hub-protocol.md` (Cross Events 2.1, Hub 1.7). + * Protocol v1 is the one in `docs/hub-protocol.md` (Cross Events 2.1, Hub 1.7). * * What v2 changes: * - `product` on register and heartbeat; the heartbeat's `stats` depend on the product.