From 897b27cc42bc409b961c3e8f2a8fb148f4c55d5f Mon Sep 17 00:00:00 2001 From: Joshua Oosthuizen Date: Thu, 5 Nov 2026 09:48:31 +0200 Subject: [PATCH] Docs: roadmap v3 and Hub protocol moved to crosscode-platform/docs Co-Authored-By: Claude Opus 5.5 --- apps/events/docs/HANDOVER.md | 55 +-- apps/events/docs/ROADMAP-v3.md | 777 +------------------------------ apps/events/docs/hub-protocol.md | 329 +------------ 3 files changed, 24 insertions(+), 1137 deletions(-) diff --git a/apps/events/docs/HANDOVER.md b/apps/events/docs/HANDOVER.md index 1baaba4..47fc654 100644 --- a/apps/events/docs/HANDOVER.md +++ b/apps/events/docs/HANDOVER.md @@ -1,11 +1,14 @@ # Handover — where things stand and how to carry on -Last updated: 2026-11-05, after **2.1.1** (deployed), **Hub 2.0.0** (released, not deployed yet), -**contracts 1.1.0** and the crosscode-site address prices (not deployed yet); ROADMAP-v3 updated for -the monorepo move and the `crosscode` deploy script (decisions 21–24). **The plan from here is -[ROADMAP-v3.md](./ROADMAP-v3.md)** (Accounts, Church Website, Church App, Cross Code Hub; decisions -table near the end). How Cross Events got to 2.x is in [ROADMAP-v2.md](./ROADMAP-v2.md); the round -before that in [FEATURES-ROUND-1.md](./FEATURES-ROUND-1.md). +Last updated: 2026-11-05, after **2.1.1** (deployed). **This file covers Cross Events only** +(what's been done, where the code lives, known gaps). **The plan for every product and where each +phase stands moved to the platform monorepo:** `crosscode-platform/docs/` → +[ROADMAP-v3.md](../../crosscode-platform/docs/ROADMAP-v3.md), +[HANDOVER.md](../../crosscode-platform/docs/HANDOVER.md) (all products) and +[EVENTS-2.2-PLAN.md](../../crosscode-platform/docs/EVENTS-2.2-PLAN.md) (the next Events release: +the move into the monorepo). The Hub protocol moved there too (`docs/hub-protocol.md`). How Cross +Events got to 2.x is in [ROADMAP-v2.md](./ROADMAP-v2.md); the round before that in +[FEATURES-ROUND-1.md](./FEATURES-ROUND-1.md). The product is called **Cross Events** (renamed from Hope Events in 1.41.3); the Hub is the **Cross Events Hub**. Technical names keep `hope-events` on purpose — the repo, browser storage @@ -91,40 +94,18 @@ encrypted settings unreadable or break existing installs. ## Next up -1. **Roadmap v3** ([ROADMAP-v3.md](./ROADMAP-v3.md), decided 2026-11-03). Everything in - ROADMAP-v2 is done: 2.1.1 is deployed, and the marketing site (`../crosscode-site`, - crosscode.co.za, with prices) is live. Build order (§9): - - **0 — contracts 1.0.0: released 2026-11-04** (`../crosscode-platform`, tag `contracts@1.0.0`): - `crosscode.event/1`, `crosscode.church/1`, `crosscode.identity/1`, Hub protocol v2, generated - JSON Schema in `packages/contracts/schemas/`. **1.1.0** (2026-11-04) adds `requires` on Hub - releases. Not published to Gitea's package registry, and won't be (decision 22). - - **1 — Hub 2.0.0: released 2026-11-05** (`../events-hub`, tag `v2.0.0`; plan and what each step - did in its `docs/HUB-2.0-PLAN.md` and CHANGELOG): products and one licence per product, protocol - v2 next to v1 (Linked products), releases per product with requirements, billing per church - (bundles, founding, Website storage, App tiers, prorating), the church's address, AI per church, - dashboard per product. **Deploying it:** `events-hub/deployment.md` → "Upgrading to 2.0" (run - `check-hub2` first). crosscode-site has the address prices (merged, deploy it too). Then - installs show up per product; Cross Events 2.1.x keeps speaking protocol 1 until 2.4.0. - - **1b — Cross Events 2.2.0: moves into the monorepo** as `apps/events` with its history, and the - **`crosscode` script** (`deploy [events] [website] [app]` — Accounts always —, - `status`, `install`, `adopt`) replaces `scripts/deploy.sh` / `install.sh`. Run - `crosscode adopt` once per existing install; then archive this repo (ROADMAP-v3 §8, - "Releases and updates"). From here on this file and the roadmap live in the monorepo. - - **1c — Cross Events 2.3.0:** **authenticator app 2FA** (TOTP + recovery codes) next to email - and WhatsApp (`TwoFactorMethod` enum in `prisma/schema.prisma`). - - **2 — Cross Events 2.4.0:** protocol v2, Linked products, the event feed (publish and show). - - **3 — Accounts 1.0.0**, **4 — Church Website 1.0.0**, **5 — Cross Events 3.0.0** (sign-in - moves to Accounts), **6 — Church App 1.0.0** (House of Prayer). - - **Before selling the Website or App:** put the prices decided in ROADMAP-v3 §10 in - `crosscode-site/src/data/pricing.mjs` and the Hub's `frontend/src/lib/tiers.ts`. - - Servers stay **PM2 + nginx** (no Docker); one database per product per church. +1. **Roadmap v3**, across every product: see `crosscode-platform/docs/HANDOVER.md` ("Where each + phase stands", "Next up"). For Cross Events that means **2.2.0** (the move into the monorepo as + `apps/events`, with the `crosscode` script; `crosscode-platform/docs/EVENTS-2.2-PLAN.md`), then + **2.3.0** (authenticator app 2FA, `TwoFactorMethod` in `prisma/schema.prisma`) and **2.4.0** + (protocol v2, Linked products, the event feed). + - **Deploying until 2.2.0:** `bash scripts/deploy.sh --check`, then + `bash scripts/deploy.sh v` on each server (installs ask through Request update as + usual). From 2.2.0 on: `crosscode deploy events`. - **AI for a church:** set the licence's monthly AI cap above R0 on the Hub (Hub 1.6.0+); with no cap the buttons don't show. - Testing AI locally: run the Hub (`../events-hub`, port 5200), set Settings → AI there, give a test licence an AI cap, and start Cross Events with `HUB_URL=http://localhost:5200`. - - **Deploying:** `bash scripts/deploy.sh --check`, then `bash scripts/deploy.sh v` on - each server (installs ask through Request update as usual). From Events 2.2.0 on: - `crosscode deploy events` (ROADMAP-v3 §8). 2. **AI rules** (decided 2026-10-29, roadmap §15): the AI buttons show only when the licence's monthly cap is above R0, and are disabled (not hidden) once it's reached. The Hub charges the real cost plus a markup % (a default and a per-licence override) and counts the cap in charged @@ -277,7 +258,7 @@ Languages (Afrikaans, §10) and Wallet passes (§7) are removed from scope (2026 ## Where the Hub client lives (1.41.0, update requests 1.42.0) -- Protocol: `docs/hub-protocol.md` — the same file is in the Hub repo (`joshua/events-hub`, +- Protocol: `crosscode-platform/docs/hub-protocol.md` (moved from `docs/` here on 2026-11-05) — the same file is in the Hub repo (`joshua/events-hub`, developed at `../events-hub`); change both together. - `backend/src/hub/`: `publicKey.js` (the production Hub key, built in since 1.42.1 — if the Hub's signing key is ever regenerated, update it here in a release; `HUB_PUBLIC_KEY` env overrides it diff --git a/apps/events/docs/ROADMAP-v3.md b/apps/events/docs/ROADMAP-v3.md index 4dcaf01..d361c1d 100644 --- a/apps/events/docs/ROADMAP-v3.md +++ b/apps/events/docs/ROADMAP-v3.md @@ -1,775 +1,4 @@ -# Cross Code — Road to three products +# Cross Code — Road to three products — moved -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](./ROADMAP-v2.md) for how Cross Events got to 2.x. - -**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 `docs/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. +The roadmap for every Cross Code product (Accounts, Church Website, Church App, Cross Events, Cross Code Hub) moved on 2026-11-05 to the platform monorepo, since it covers every product: +**`joshua/crosscode-platform` → [`docs/ROADMAP-v3.md`](https://c-git.crosscode.co.za/joshua/crosscode-platform/src/branch/main/docs/ROADMAP-v3.md)** (locally `../crosscode-platform/docs/ROADMAP-v3.md`). diff --git a/apps/events/docs/hub-protocol.md b/apps/events/docs/hub-protocol.md index cbf2c64..9bfbc25 100644 --- a/apps/events/docs/hub-protocol.md +++ b/apps/events/docs/hub-protocol.md @@ -1,327 +1,4 @@ -# Hub protocol (versions 1 and 2) +# Hub protocol (versions 1 and 2) — moved -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/hope-events` → `docs/hub-protocol.md`, -`joshua/events-hub` → `docs/hub-protocol.md`); change both together. 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. +The install ↔ Hub protocol, for every product (a copy is also in `joshua/events-hub`, `docs/hub-protocol.md`) moved on 2026-11-05 to the platform monorepo, since it covers every product: +**`joshua/crosscode-platform` → [`docs/hub-protocol.md`](https://c-git.crosscode.co.za/joshua/crosscode-platform/src/branch/main/docs/hub-protocol.md)** (locally `../crosscode-platform/docs/hub-protocol.md`).