Compare commits
8
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
  joshuaandClaude Opus 5.5
|
d6ff08f5d9 | ||
|
joshuaandClaude Opus 5.5
|
b1a5c5abc3 | ||
|
joshuaandClaude Opus 5.5
|
1adf1d4870 | ||
|
joshuaandClaude Opus 5.5
|
e42e244edc | ||
|
joshuaandClaude Opus 5.5
|
f85842d4b3 | ||
|
joshuaandClaude Opus 5.5
|
78bf6df40c | ||
|
joshuaandClaude Opus 5.5
|
47725a689d | ||
|
joshuaandClaude Opus 5.5
|
a9584cdde5 |
+33
-17
@@ -1,8 +1,10 @@
|
||||
# Handover — where things stand and how to carry on
|
||||
|
||||
Last updated: 2026-11-03, after **2.1.1** and Hub **1.7.0**. The plan itself is in
|
||||
[ROADMAP-v2.md](./ROADMAP-v2.md) (decisions table at the end); the previous round of
|
||||
features is in [FEATURES-ROUND-1.md](./FEATURES-ROUND-1.md).
|
||||
Last updated: 2026-11-04, after **2.1.1** (deployed), Hub **1.7.0** and **contracts 1.0.0**;
|
||||
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).
|
||||
|
||||
The product is called **Cross Events** (renamed from Hope Events in 1.41.3); the Hub is the
|
||||
**Cross Events Hub**. Technical names keep `hope-events` on purpose — the repo, browser storage
|
||||
@@ -88,24 +90,38 @@ encrypted settings unreadable or break existing installs.
|
||||
|
||||
## Next up
|
||||
|
||||
1. **After 2.0.x** (order decided 2026-11-02, roadmap §18: 2.0.1 → the marketing site → 2.1.0):
|
||||
- **Deploy:** `bash scripts/deploy.sh --check`, then `bash scripts/deploy.sh v2.0.1` on each server
|
||||
(installs on 1.52.x ask through Request update as usual). Before updating an install that has
|
||||
its own integration, look in the nginx access log for `/api/` calls that aren't `/api/v2/`,
|
||||
the webhooks or the old links — those get 410 after the update (MIGRATING-TO-2.md).
|
||||
1. **Roadmap v3** ([ROADMAP-v3.md](./ROADMAP-v3.md), decided 2026-11-03). Everything in
|
||||
ROADMAP-v2 is done: 2.1.1 is deployed, and the marketing site (`../crosscode-site`,
|
||||
crosscode.co.za, with prices) is live. Build order (§9):
|
||||
- **0 — contracts 1.0.0: 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/`. Not published to Gitea's package registry, and
|
||||
won't be (decision 22).
|
||||
- **1 — Hub 2.0.0** (`../events-hub`): Cross Code Hub — products, one licence per product,
|
||||
**one install of each product per customer**, domain per customer, bundles, sibling discovery,
|
||||
**releases per product** (Events from `crosscode-platform` `events@…` tags, keeping the
|
||||
`hope-events` `v…` releases) **with requirements** (`— requires accounts 1.2.0`, Request update
|
||||
disabled until met). Contracts as `vendor/crosscode-contracts-1.0.0.tgz` (ROADMAP-v3 §2, §5).
|
||||
- **1b — Cross Events 2.2.0: moves into the monorepo** as `apps/events` with its history, and the
|
||||
**`crosscode` script** (`deploy <church> [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.
|
||||
- **AI for a church:** set the licence's monthly AI cap above R0 on the Hub (Hub 1.6.0+); with
|
||||
no cap the buttons don't show.
|
||||
- **Marketing site — next, and before 2.1.0** (roadmap §17, all decided 2026-11-02): **crosscode.co.za**, Cross Code's
|
||||
main site with a Cross Events page; church website and church app as "coming later"; repo
|
||||
**`joshua/crosscode-site`** (create it on Gitea first); Joshua's own server (nginx); no prices;
|
||||
a **contact form to info@crosscode.co.za** (needs a small send endpoint on the server — see
|
||||
§17's building notes); a privacy notice and terms of use; no cookies or analytics. Logo,
|
||||
colours, wording and screenshots come from Joshua later — start with placeholders.
|
||||
- **2.1.0** (roadmap §18): the **Feedback page** — results per event, each response, who
|
||||
hasn't answered and a "remind" action. AI helpers on the privacy pages were dropped
|
||||
(2026-11-03).
|
||||
- Testing AI locally: run the Hub (`../events-hub`, port 5200), set Settings → AI there, give a
|
||||
test licence an AI cap, and start Cross Events with `HUB_URL=http://localhost:5200`.
|
||||
- **Deploying:** `bash scripts/deploy.sh --check`, then `bash scripts/deploy.sh v<version>` on
|
||||
each server (installs ask through Request update as usual). From Events 2.2.0 on:
|
||||
`crosscode deploy <church> 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
|
||||
|
||||
+2
-2
@@ -1200,5 +1200,5 @@ feature.
|
||||
|
||||
## Still open
|
||||
|
||||
- **Marketing site (§17):** built; waiting on Joshua's real logo, wording and photos where
|
||||
placeholders remain.
|
||||
Nothing. The marketing site (§17) is done (2026-11-03). The plan from here is
|
||||
[ROADMAP-v3.md](./ROADMAP-v3.md).
|
||||
|
||||
@@ -0,0 +1,775 @@
|
||||
# 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](./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-<version>.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=<ISO>` → `{ 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
|
||||
`<church>.crosscode.co.za` for the Cross Code address (a wildcard DNS record and certificate
|
||||
for `*.crosscode.co.za` subdomains, so no DNS work per church). Certificates through certbot. Only configured domains are served (no trusting arbitrary Host headers).
|
||||
- Every product has `/health` (version, DB, jobs, last backup), reported to the Hub.
|
||||
- Several churches can share a server at first. Any church can move to its own server later
|
||||
without code changes. The Hub stays on a separate server from church installs.
|
||||
|
||||
### 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/<church>/`** (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 <church> [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 <church> --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 [<church>]` | Each product's version, latest release, health (from `/health`) and last backup |
|
||||
| `crosscode install <church> --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 <church> app` | Adds a product to an existing church |
|
||||
| `crosscode adopt <church> --events-dir /var/www/<old folder>` | Once per existing Cross Events install: moves it onto the monorepo and into `/var/www/sites/<church>/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/<old folder>` to `/var/www/sites/<church>/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/<church>/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) | 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 `<title>` 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.
|
||||
Reference in New Issue
Block a user