Author SHA1 Message Date
joshuaandClaude Opus 5.5 c398e8071d Docs: server agent and Hub 2.1.0 plan (phase 1d, decisions 27-37)
Agent on every server runs installs, scheduled/emergency updates and
uninstalls on signed jobs from the Hub, polls only (no listening port),
appends to frpc.ini in marked blocks, builds .env files from per-server
config in the Hub. FastPanel and DNS stay manual (emailed instructions).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 16:26:51 +02:00
joshua 934f7a9eed Merge branch 'docs/adopt-decisions' 2026-11-05 13:51:09 +02:00
joshuaandClaude Opus 5.5 4e58c5c07e Docs: adopt builds next to the install and switches over; adopt --undo (decisions 25-26)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-05 13:51:08 +02:00
joshua 8032a5d9e2 Merge branch 'docs/roadmap-and-events-move' 2026-11-05 09:48:28 +02:00
joshuaandClaude Opus 5.5 633d65eec9 Docs: roadmap and Hub protocol move here; handover and Events 2.2.0 plan
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-05 09:48:27 +02:00
joshuaandClaude Opus 5.5 d62a652be2 Merge branch 'feat/contracts-release-requires' (contracts@1.1.0)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 15:45:40 +02:00
joshuaandClaude Opus 5.5 11e28502ea Contracts 1.1.0: optional requires on Hub releases
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 15:45:40 +02:00
13 changed files with 2071 additions and 7 deletions
+14
View File
@@ -4,6 +4,20 @@ Each package and app has its own section and its own tags (`contracts@1.0.0`, `a
## Unreleased ## Unreleased
### Docs
- The roadmap (`docs/ROADMAP-v3.md`) and the Hub protocol (`docs/hub-protocol.md`) move here from
`hope-events/docs/`, since they cover every product. New: `docs/HANDOVER.md` (where each phase
stands) and `docs/EVENTS-2.2-PLAN.md` (phase 1b, Cross Events into the monorepo).
## contracts@1.1.0 - 2026-11-04
### Contracts
- Hub protocol v2: optional `requires` on a release (`[{ product, version }]`), the sibling
versions it needs. The Hub refuses an update request with `409 REQUIREMENT_NOT_MET` until
they're met (Hub 2.0, ROADMAP-v3 §5). Optional, so the schema stays `/1`-compatible.
## contracts@1.0.0 - 2026-11-04 ## contracts@1.0.0 - 2026-11-04
### Monorepo ### Monorepo
+14 -3
View File
@@ -1,7 +1,8 @@
# Cross Code platform # Cross Code platform
The monorepo for the Cross Code products that come after Cross Events, and the formats they share. The monorepo for the Cross Code products that come after Cross Events, and the formats they share.
The plan is in `hope-events/docs/ROADMAP-v3.md` (decided 2026-11-03). The plan for every product is in [`docs/ROADMAP-v3.md`](./docs/ROADMAP-v3.md) (decided 2026-11-03); where
things stand is in [`docs/HANDOVER.md`](./docs/HANDOVER.md).
| Folder | What | Status | | Folder | What | Status |
|--------|------|--------| |--------|------|--------|
@@ -11,8 +12,18 @@ The plan is in `hope-events/docs/ROADMAP-v3.md` (decided 2026-11-03).
| `apps/website` | Church Website | Placeholder (phase 4) | | `apps/website` | Church Website | Placeholder (phase 4) |
| `apps/app` | Church App (PWA) | Placeholder (phase 6) | | `apps/app` | Church App (PWA) | Placeholder (phase 6) |
Cross Events (`joshua/hope-events`) and Cross Code Hub (`joshua/events-hub`) stay in their own Cross Events (`joshua/hope-events`) moves in as `apps/events` in Events 2.2.0
repos and install `@crosscode/contracts` from Gitea's package registry. ([`docs/EVENTS-2.2-PLAN.md`](./docs/EVENTS-2.2-PLAN.md)). Cross Code Hub (`joshua/events-hub`) stays in
its own repo and gets `@crosscode/contracts` as a packed release committed there (decision 22).
## Docs
| File | What |
|------|------|
| [`docs/ROADMAP-v3.md`](./docs/ROADMAP-v3.md) | The plan: products, contracts, Accounts, sync, Hub, servers, build order, pricing, decisions |
| [`docs/HANDOVER.md`](./docs/HANDOVER.md) | Where each phase stands and what's next |
| [`docs/hub-protocol.md`](./docs/hub-protocol.md) | Install ↔ Hub protocol, versions 1 and 2 (a copy lives in `events-hub`) |
| [`docs/EVENTS-2.2-PLAN.md`](./docs/EVENTS-2.2-PLAN.md) | Phase 1b: Cross Events into the monorepo, the `crosscode` script |
## Rules (ROADMAP-v3 §1) ## Rules (ROADMAP-v3 §1)
+477
View File
@@ -0,0 +1,477 @@
# Server agent 1.0.0 + Hub 2.1.0 — installs, updates and uninstalls from the Hub
Planned 2026-11-12 (ROADMAP-v3 phase **1d**, decisions 27–37). Goal: when a new church signs up,
Joshua picks a server in the Hub and the rest happens by itself, with a report by email. Updates
are scheduled from the Hub with notice to the church, and every server's health is visible there.
This replaces the old rule "the Hub never deploys" (decisions 10 and 23). The part that matters
stays: **no site depends on the Hub to keep running**, and everything still goes through the
`crosscode` script (EVENTS-2.2-PLAN §4), which keeps working by hand over SSH.
## Contents
1. [The shape](#1-the-shape)
2. [Rules](#2-rules)
3. [The agent](#3-the-agent)
4. [Jobs and their security](#4-jobs-and-their-security)
5. [Configuration: server, defaults, per install](#5-configuration-server-defaults-per-install)
6. [frp and the central server](#6-frp-and-the-central-server)
7. [New install](#7-new-install)
8. [Updates: scheduled, emergency, batch](#8-updates-scheduled-emergency-batch)
9. [Uninstall](#9-uninstall)
10. [Servers page and alerts](#10-servers-page-and-alerts)
11. [Reports and emails](#11-reports-and-emails)
12. [What changes in each repo](#12-what-changes-in-each-repo)
13. [Testing](#13-testing)
14. [Rolling it out](#14-rolling-it-out)
15. [Decisions](#decisions)
---
## 1. The shape
```
Cross Code Hub (hub.crosscode.co.za)
servers · jobs · schedules · port list · server config · reports
▲ agents poll: "any jobs?" + stats + job results (outbound HTTPS only)
│
┌────────┴─────────────┐ ┌──────────────────────┐ ┌─────────────────────────────┐
│ Church server A │ │ Church server B │ │ Central server (FastPanel) │
│ crosscode-agent │ │ crosscode-agent │ │ crosscode-agent --central │
│ └ runs `crosscode` │ │ └ runs `crosscode` │ │ read-only: frps ports, │
│ PM2 sites, Postgres │ │ … │ │ allow_ports, bind address │
│ frpc ═══tunnel═══════╪═══╪══════════════════════╪══▶│ frps ◀─ nginx (FastPanel, │
└──────────────────────┘ └──────────────────────┘ │ set up by Joshua) │
└─────────────────────────────┘
```
## 2. Rules
1. **The agent listens on nothing.** No HTTP server, no open port, no URL, not even on
`127.0.0.1`. It only makes outgoing HTTPS requests to the Hub (poll, stats, results). A test
checks that the running agent has no listening socket.
2. **The agent only runs the `crosscode` script**, with arguments built from a fixed list of job
types (§4). There is no "run this command" job.
3. **Jobs are signed by the Hub** and checked by the agent against the Hub key pinned when the
server joined. Unsigned, expired or replayed jobs are refused and reported.
4. **No site depends on the Hub or the agent.** If either is down, sites keep running and
`crosscode` still works by hand. Scheduled jobs that can't be delivered are reported as missed,
never run late without a fresh notice (§8).
5. **The agent never touches FastPanel or DNS.** FastPanel setup is an email to Joshua (§7, §11).
6. **Files the agent edits are only ever added to, never replaced**: `/etc/frp/frpc.ini` and each
install's `.env` (§5, §6). Anything written by hand is never changed.
7. **Secrets generated for an install stay on its server** (`JWT_SECRET`, the database password).
They're never sent to the Hub, never put in a report or email.
## 3. The agent
- **Where:** `apps/agent` in this monorepo, Node 24 + TypeScript, tagged `agent@1.0.0`. Installed
in `/opt/crosscode/agent` with its config in `/etc/crosscode/agent.json` (mode 600, root).
- **Run by systemd** (`crosscode-agent.service`, restarts on failure), not PM2, because it manages
PM2. Runs as root, as `crosscode install` needs (PostgreSQL, PM2 for the app user, frpc).
- **Joining:** Hub → Servers → **Add server** gives a one-time token (valid 1 hour). On the server:
`curl … | bash -s -- --hub https://hub.crosscode.co.za --token …` installs Node if needed, the
agent and `/opt/crosscode/tools`, then the agent:
1. makes an **Ed25519 key pair** (signs its requests to the Hub) and an **X25519 key pair**
(receives encrypted config, §5); the private keys never leave the server,
2. sends the token and both public keys; the Hub replies with the server id and **the Hub's
job-signing public key**, which the agent pins.
- **Polling:** every 30 s `POST /api/agent/v1/poll` (signed) with a short status; the reply holds
any jobs due. Every 60 s the stats (§10). Requests back off when the Hub doesn't answer.
- **Modes:** `church` (default) and `central` (§6). The central agent can't run any job but
`check-ports` and `status`.
- **Updating itself:** an `update-agent` job checks out the newest `agent@…` tag, builds it next
to the running copy, switches the systemd unit over and reports its new version. If the new one
doesn't poll within 2 minutes, a systemd timer starts the previous one again.
- **One job at a time per server**, in the order the Hub gives them. A job has a time limit
(install 30 min, deploy 20 min); a job past it is stopped and reported as failed.
## 4. Jobs and their security
**Job types** (and the `crosscode` command each runs):
| Job | Runs | Needs 2FA again in the Hub |
|-----|------|:-:|
| `install` | `crosscode install <church> --products … --json` | no |
| `add-product` | `crosscode add <church> <product> --json` | no |
| `deploy` | `crosscode deploy <church> [products] [--version …] --json` | emergency only |
| `adopt` / `adopt-undo` | `crosscode adopt …` | no |
| `restart` | `crosscode restart <church> [product]` (PM2 reload) | no |
| `export` | `crosscode export <church> --json` (§9) | no |
| `uninstall` | `crosscode uninstall <church> --json` | **yes**, and typing the short name |
| `purge` | `crosscode purge <church>` (deletes the 30-day keep, §9) | no (scheduled at uninstall) |
| `update-agent` | §3 | no |
| `check-ports` | central only (§6) | no |
| `status` | `crosscode status --json` | no |
**A signed job** (`crosscode.agent-job/1`, in `packages/contracts`):
```json
{
"schema": "crosscode.agent-job/1",
"id": "job_…",
"serverId": "srv_…",
"type": "deploy",
"args": { "church": "hope", "products": ["events"], "version": "events@2.4.1" },
"config": { "alg": "x25519-xsalsa20-poly1305", "ciphertext": "…" },
"notBefore": "2026-11-20T12:00:00Z",
"expiresAt": "2026-11-20T12:15:00Z",
"signature": "…"
}
```
- The agent checks: the signature (pinned Hub key), `serverId` is its own, it's within
`notBefore`–`expiresAt`, the id hasn't been seen (it keeps the ids of the last 90 days), the
type is known and every `args` value passes that type's schema (short names
`^[a-z][a-z0-9-]{1,30}$`, products from the enum, versions as `<product>@x.y.z`). Arguments are
passed to `crosscode` as an argument array, never through a shell.
- `config` holds whatever the job needs from §5, encrypted to **this server's** X25519 key, so
job rows and logs in the Hub never hold it in plain text.
- **Results** (`crosscode.agent-report/1`): the job id, status (`succeeded`, `failed`,
`rolled-back`, `refused`, `expired`), each step with its start, end and outcome, and the last
200 log lines. The script's `--json` output is that report; the agent adds the log lines and
sends it, signed with its own key. Logs are filtered for anything that looks like a secret
before they leave the server.
- **The Hub side:** job-signing private key in the Hub's `.env` (not in the database), its own
key separate from the licence-signing key. 2FA re-confirmation for uninstall and emergency
deploys. Every job is in the audit log with who made it.
## 5. Configuration: server, defaults, per install
An install's `.env` files are built from four layers. Each variable comes from exactly one layer.
| Layer | Set where | Examples | Sent how |
|-------|-----------|----------|----------|
| **Server** | Hub → Servers → *server* → Configuration, **once per server** (editable) | Database host, port and an admin role that can create databases and roles (or "local PostgreSQL, through `sudo -u postgres`"), `TRUST_PROXY`, app user, backup folder | Stored AES-GCM encrypted in the Hub (as install secrets are today); sent to the agent encrypted to its key with each job that needs it. The agent doesn't keep it on disk |
| **Defaults** | Hub → Settings → Install defaults, once | `HUB_URL`, `APP_TIMEZONE` (Africa/Johannesburg), job switches (`DAILY_SUMMARY_ENABLED=true`, `BACKUP_ENABLED=true`, …), `HUB_HEARTBEAT_ENABLED=true`, optional platform `SENTRY_DSN` | With the job, encrypted the same way |
| **Install** | The New install form (§7) | Domain → `FRONTEND_URL`, `APP_BASE_URL`, `BACKEND_URL` and the frontend's `NEXT_PUBLIC_API_URL` (all `https://<domain>`, since FastPanel sends `/api` to the backend on the same domain); timezone if not the default; the licence key; ports from the port list (§6) → `PORT` | With the job |
| **Generated** | On the server by `crosscode install` | `JWT_SECRET`, the database password (so `DATABASE_URL`), `NODE_ENV=production` | Never leaves the server (rule 7) |
**Per-product env template.** Each product has `apps/<product>/env.template.json` in the
monorepo, listing every variable with its layer, whether it's required, and a default:
```json
{ "schema": "crosscode.env-template/1", "product": "events", "files": {
"backend/.env": [
{ "name": "DATABASE_URL", "layer": "generated", "required": true },
{ "name": "FRONTEND_URL", "layer": "install", "from": "https://{domain}", "required": true },
{ "name": "TRUST_PROXY", "layer": "server", "required": true },
{ "name": "BACKUP_ENABLED", "layer": "defaults", "default": "true" }
],
"frontend/.env.production": [
{ "name": "NEXT_PUBLIC_API_URL", "layer": "install", "from": "https://{domain}", "required": true }
] } }
```
- The Hub reads the template of the release being installed (synced with the release, §5 of the
roadmap) and **refuses to create the job if a required server or defaults value is missing**,
saying which, before anything runs on the server.
- **Install:** `crosscode install` writes each `.env` from the template (mode 600, app user).
- **Updates:** before building, `crosscode deploy` compares the new release's template with the
`.env`. A new variable is **appended** with its value (and a comment with the date and
release); existing lines are never changed or removed. A new *required* variable with no value
in any layer stops the deploy at the checks, before anything is touched.
- **Changing a server value later** (e.g. a new database host) is a `reconfigure` step of a
deploy: the agent shows which lines would change in each install, and only changes them when
Joshua confirms in the Hub. This is the one exception to "only append", and it never runs by
itself.
- **URLs are checked before and after.** Before: the form checks that the domain's DNS points at
the central server and warns if not (the install still runs). After Joshua marks the proxy done:
the Hub checks `https://<domain>/` (frontend answers), `https://<domain>/health` (backend
answers with the right version) and that `/health` reports the `FRONTEND_URL` it was given.
**For Joshua to set per server before the first install:** the database settings and
`TRUST_PROXY`. Behind frp the app sees every connection from frpc on `127.0.0.1`, and the
visitor's address arrives in `X-Forwarded-For` from FastPanel's nginx, so the expected value is
`loopback` (the Hub suggests it).
## 6. frp and the central server
**Today:** `/etc/frp/frpc.ini` on each church server, `tcp` tunnels, frontend and backend each
with their own `remote_port`. FastPanel on the central server proxies a domain to
`127.0.0.1:<remote_port>` with Let's Encrypt.
**Port list in the Hub.** frps opens every `remote_port` on the one central server, so they must
be unique across every church server. The Hub hands them out from a range (default
**20000–29999**, set in Hub settings to match `allow_ports`), two per product install (web, api),
and **uses the same number for `local_port`**, so it's also free on the church server and there's
one number per tunnel to think about. Ports already in use (today's `3000`/`5000` and anything
the central agent sees listening) are recorded as taken. Ports are released 30 days after an
uninstall.
**Tunnel names** must also be unique on frps: `<church>-<product>-web` and
`<church>-<product>-api` (e.g. `hope-events-web`). Existing entries such as `[events-frontend]`
stay as they are.
**What the agent adds to frpc.ini** (one block per product install, appended at the end):
```ini
# >>> crosscode:hope:events (added by crosscode-agent 2026-11-20, do not edit by hand)
[hope-events-web]
type = tcp
local_ip = 127.0.0.1
local_port = 20010
remote_port = 20010
[hope-events-api]
type = tcp
local_ip = 127.0.0.1
local_port = 20011
remote_port = 20011
# <<< crosscode:hope:events
```
- **Only appended to, never replaced.** Before a change: a copy to
`/etc/frp/backups/frpc.ini.<timestamp>`; write to a temporary file; `frpc verify -c`; then move
it into place. If the check fails, nothing is changed. Uninstall removes only the lines between
that install's own markers; nothing outside a marked block is ever changed.
- **Reload without dropping other sites.** Once per server (agreed 2026-11-12) the agent adds to
`[common]`, if they're not there:
```ini
admin_addr = 127.0.0.1
admin_port = 7400
```
so `frpc reload -c /etc/frp/frpc.ini` picks up new tunnels without restarting frpc. This is the
only change ever made in `[common]`, and it's reported. (`admin_addr` is loopback only, so it
adds no way in from outside.)
- The `.ini` format is deprecated in newer frp versions in favour of TOML. The agent reads the
format the server has; moving to TOML is a separate job for later.
**The central agent** (`--central`, on the FastPanel server, read-only) answers `check-ports`:
- the port is inside `allow_ports` in `frps.ini`,
- frps has the tunnel open (the port is listening; frps's dashboard API is used if it's enabled
on `127.0.0.1`),
- **`proxy_bind_addr = 127.0.0.1` is set**, so tunnels are only reachable through FastPanel's
nginx, not straight from the internet on `<central IP>:<port>` (which would bypass HTTPS and
expose the backend). If it's missing, every report and the Servers page show a warning.
It changes nothing on the central server: no frps edits, no firewall changes, no FastPanel.
## 7. New install
**Hub → Customers → *customer* → New install** (or a new customer first):
1. **Form:** products (Events now; Accounts / Website / App as they ship), **short name**
(`hope`, `cross`, `bridge`; checked unique across all servers and used for folders, PM2 names,
database names and tunnel names), address (own domain or Cross Code address; per product the
domain is shown, e.g. `events.hope.co.za`), timezone, **site admin name and email**, and the
**server**: a list showing each server's free RAM, free disk, CPU load over the last day, sites
on it and agent status, with servers below the free-RAM threshold (default 1.5 GB per product
install) marked as not recommended.
2. **Checks in the Hub** before the job exists: the server agent is online, server config and
defaults are complete for the release's env template (§5), ports are free, the short name is
free, DNS (warning only).
3. The Hub **creates the licence(s)**, assigns ports, and queues the `install` job.
4. **On the server** (`crosscode install`, each step in the report):
checks (disk, RAM, Node, PostgreSQL reachable) → folder `/var/www/sites/<church>/<product>`
→ checkout of the release tag → `.env` files (§5) → database and role → install dependencies
→ migrations → build → PM2 processes on the given ports, `pm2 save` → `church.env` → frpc
block and reload (§6) → local `/health` answers with the right version → the site registers
with the Hub using its licence.
5. **On failure** anything this job created is removed again (PM2 processes, frpc block, database
and role, folder), in reverse order, and the report says what failed and what was cleaned up.
6. **Central check:** the Hub asks the central agent to `check-ports` for both ports.
7. **Emails to Joshua:** the install report and, if everything passed, the **FastPanel email**
(§11). The install shows **Waiting for proxy** in the Hub.
8. Joshua sets up FastPanel by hand and clicks **Proxy done**. The Hub checks the public URLs
(§5) and marks it **Live**, or says what didn't answer. When Live, the site admin gets the
welcome email with the setup-wizard link.
## 8. Updates: scheduled, emergency, batch
**Scheduled** (Hub → Install → Schedule update, or Updates → Schedule):
- Joshua picks the release and the time. The time must be **at least 4 hours away**; the Hub
refuses anything sooner. A warning (not a block) for Sunday 06:00–13:00 and for days with an
event of that church running (from the stats).
- Straight away: an email to the site admin(s) ("Cross Events will be updated on Thursday 20
November at 14:00; the site will be unavailable for a few minutes", plus the what's-new
summary), and a **banner** through the existing Notices, starting now and ending after the
update. A reminder email 1 hour before.
- At the time the Hub releases the `deploy` job (`notBefore` = the time, `expiresAt` = 15 min
later). If the agent doesn't pick it up in that window the update is **missed**: nothing runs,
Joshua is emailed, and a new time needs a new notice.
- Afterwards: the report to Joshua; to the site admin "Updated to 2.4.1" with what's new, or
"The update didn't go through; the site is running the previous version" if it rolled back.
- Cancelling or moving it updates the banner and emails the site admin.
**Emergency:** the same, with at least **15 minutes'** notice, a required reason (shown in the
email and banner), and 2FA again. Meant for security fixes and broken releases.
**Batch:** "every Events install to 2.4.1" (or a selection), at one time with one notice. The
Hub runs them **one at a time** (on each server, and across servers) and **stops the batch at the
first failure**, emailing Joshua; the remaining installs get a "postponed" email and their banner
is removed.
**Rules carried over:** the release's requirements (`— requires accounts 1.2.0`, decision 24)
are checked in the Hub before scheduling and again by the script; each product rolls back on its
own (§8 of the roadmap). A church's **Request update** now shows as "Requested" next to
Schedule update. Moving a 2.1.x install to 2.2.0 is an `adopt` job, scheduled the same way.
## 9. Uninstall
Hub → Install → **Uninstall** (2FA again, type the short name):
1. Joshua picks the date (at least 4 hours away, default 7 days) and the site admin is emailed
and gets a banner, as for an update.
2. **Export first** (`crosscode export`): the church's data as **JSON in a format of our own**,
`crosscode.church-export/1` (defined in `packages/contracts`): events, sessions, ticket types,
registrations and attendees, people (name, email, phone, consent), payments (amounts, dates,
references), check-ins, rosters, settings, and the uploads as files next to it. Written in
plain terms with our own field names; **no database tables, Prisma models or internal ids**.
One ZIP: `export.json`, `uploads/`, `README.txt` explaining the fields.
3. The agent **encrypts the ZIP with a random key** and uploads it to the Hub. The key is only in
the link emailed to the site admin (`…/download/<id>#<key>`; the part after `#` is never sent
to the Hub), so the Hub stores the file but can't read it, and the roadmap's "the Hub only sees
aggregate stats" still holds. The download page decrypts it in the browser. Available for
**30 days**.
4. **Uninstall:** final database backup and an archive of the uploads to
`/var/www/sites/.removed/<church>-<date>/` (root only) → PM2 processes removed, `pm2 save` →
the frpc block removed and reloaded → database and role dropped → the site folder removed →
the licence released in the Hub.
5. **Emails:** to the site admin, the download link and the date it expires; to Joshua, the report
and "remove the FastPanel site `events.hope.co.za` (ports 20010, 20011)".
6. **After 30 days:** a `purge` job deletes the kept backup and archive, and the Hub deletes the
encrypted export. Joshua is emailed **3 days before**, and can extend it once by 30 days. The
Hub keeps a record that it was deleted, and when (for POPIA).
## 10. Servers page and alerts
**Hub → Servers:** one card per server (church servers and the central one).
- **Every 60 s** the agent sends: RAM (total, used, available, swap), CPU (% and 1/5/15-minute
load), disk per mount (used, free), uptime, versions (OS, Node, PostgreSQL, frpc, agent), frpc
running, and **per PM2 process** (church, product, memory, CPU, restarts, uptime).
- **Kept:** per minute for 7 days, per hour (average and peak) for 90 days.
- **Server page:** RAM and CPU charts for 24 h / 7 days / 90 days with **spikes marked** (peaks
above 85%), disk bars, the sites on it with each process's memory, recent jobs, the frpc blocks
it manages and the ports they use.
- **Alerts** (email to Joshua, through the existing alerts, once per incident and again when it
clears): agent not heard from for 5 minutes; disk over 85%; RAM over 90% for 5 minutes; a PM2
process restarting more than 5 times in 10 minutes; frpc not running; on the central server,
`proxy_bind_addr` missing or a managed tunnel not listening.
## 11. Reports and emails
All in the Hub (Jobs page, with the full report) and by email:
| Email | To | When |
|-------|----|------|
| Install report | Joshua | Every install, success or failure: each step with its time, ports, the central check, the log tail on failure, what was cleaned up |
| **FastPanel setup** | Joshua | After a successful install. What *he* does in FastPanel; the agent does none of it (below) |
| Welcome | Site admin | When the install is Live |
| Update planned / reminder / done / didn't go through | Site admin | §8 |
| Update report | Joshua | Every update (and batch summary) |
| Missed job | Joshua | A scheduled job wasn't picked up in time |
| Uninstall planned / export ready | Site admin | §9 |
| Uninstall report, purge in 3 days | Joshua | §9 |
| Alerts | Joshua | §10 |
**The FastPanel email** (an instruction to Joshua, nothing is set up automatically):
```
Set up in FastPanel: events.hope.co.za (Hope Family Church, Cross Events)
1. Add the site events.hope.co.za.
2. Proxy:
/api, /uploads, /health, /docs → http://127.0.0.1:20011 (backend)
everything else → http://127.0.0.1:20010 (frontend)
Pass the Host header and X-Forwarded-For / X-Forwarded-Proto: https.
Allow uploads up to 25 MB.
3. Turn on Let's Encrypt for the site.
4. DNS: events.hope.co.za → <central server IP> (checked: ✅ points there / ⚠ not yet)
5. Then click "Proxy done" in the Hub: <link>
Central check: both ports are open in frps and only on 127.0.0.1.
```
## 12. What changes in each repo
**`crosscode-platform`**
- `apps/agent` (new, `agent@1.0.0`) with its install script and systemd unit.
- `scripts/` (the `crosscode` script): `--json` reports on every command, `uninstall`, `export`,
`purge`, `restart`, the frpc block handling (lib/frpc.sh), the env template handling
(lib/env.sh), ports given on the command line instead of picked.
- `apps/events`: `env.template.json`, and the export (`crosscode export` calls a backend script
that writes `crosscode.church-export/1`).
- `packages/contracts` **1.2.0**: `crosscode.agent-job/1`, `crosscode.agent-report/1`,
`crosscode.agent-stats/1`, `crosscode.env-template/1`, `crosscode.church-export/1`.
**`events-hub` (Hub 2.1.0)**
- Models: `Server` (name, mode, public keys, encrypted config, last seen, versions), `ServerStat`
(minute and hourly), `Job` (type, args, status, schedule, who, report), `ScheduledUpdate` /
batch, `Port` (number, server, install, released at), `Export` (encrypted blob, expires).
`Install` gets `serverId`, `shortName`, `status` (installing, waiting-for-proxy, live,
uninstalling, removed).
- Agent API `/api/agent/v1/*` (join, poll, stats, report, export upload), signed by the agent.
- Pages: Servers, Server, New install, Jobs, Updates (schedule, batch), Install defaults, the
public export download page.
- Emails in §11; alerts in §10; the job-signing key in `.env`.
**`crosscode-site`:** nothing (this changes how Joshua works, not what churches buy).
## 13. Testing
- **Agent:** unit tests for job checking (bad signature, wrong server, expired, replayed,
unknown type, an argument with shell characters), and **a test that the running agent has no
listening socket** (`ss -ltnp` shows nothing for its process).
- **Script:** bats tests for the frpc blocks (append to a file with hand-written entries and
comments, remove one block, the other blocks and the hand-written lines unchanged byte for byte;
a failed `frpc verify` leaves the file untouched; `[common]` admin lines added only once), the
env template (new variable appended, existing lines untouched, required one missing → refused),
and the export (a demo church's export validates against `crosscode.church-export/1` and has no
internal ids).
- **On VMs** (multipass): a "central" VM with frps (with `proxy_bind_addr = 127.0.0.1`) and nginx
in place of FastPanel, two church VMs with frpc and a hand-written tunnel, the Hub running
locally:
1. Join all three. Stats show up.
2. New install on church VM 1 → report, FastPanel email, ports open on the central VM, the
hand-written tunnel still works. Add the nginx site by hand, Proxy done → Live.
3. A second church on VM 2 → different ports, unique tunnel names.
4. Schedule an update 4 h ahead (time moved forward in the test) → emails, banner, update,
report. Try 3 h → refused. Emergency with 15 min → needs 2FA.
5. A broken release → rolled back, "didn't go through" email, batch stopped.
6. Hub stopped during a scheduled update → missed, nothing runs, sites keep running.
7. Uninstall → export downloads and decrypts in the browser, everything removed, the other
church's tunnel and the hand-written one untouched. Purge after 30 days (clock moved).
8. A forged job (wrong key) and a replayed job → refused and reported.
## 14. Rolling it out
1. Contracts 1.2.0 → the `crosscode` script changes (with Events 2.2.0 out first) → agent 1.0.0
→ Hub 2.1.0, each released as usual (branch → merge → tag → push).
2. On the central server: add `proxy_bind_addr = 127.0.0.1` to `frps.ini` if it's missing (check
that each FastPanel site still answers), then join the central agent.
3. Join each church server; set its server config in the Hub. Existing installs are linked to
their server and their current ports recorded in the port list (read from `church.env` and
`frpc.ini`; nothing is changed).
4. First real use: the next new church. Existing churches get their next update through a
scheduled update.
5. Docs: CHANGELOGs, HANDOVER.md (1d done), `events-hub/deployment.md` (the job-signing key),
a server how-to in `apps/agent/README.md`.
## Decisions
Agreed with Joshua on 2026-11-12 (ROADMAP-v3 decisions 27–37):
1. The Hub can install, update and uninstall through an agent on each server, with **signed jobs
of fixed types**; the agent only runs the `crosscode` script; uninstall and emergency updates
need 2FA again.
2. **The agent has no URL or listening port**; it only polls the Hub.
3. **Scheduled updates at least 4 hours ahead, emergency updates at least 15 minutes**, with an
email and banner to the site admin; Joshua picks the time.
4. **Uninstall:** the church gets a **JSON export in our own format** (no internal data
structures), encrypted so the Hub can't read it, downloadable for 30 days; backups kept 30
days, then deleted.
5. All church servers are behind frp to **one central FastPanel server**. The Hub keeps the port
list; **frpc.ini is only appended to**; the `[common]` admin lines are added once.
6. **FastPanel and DNS are never automated**; Joshua gets an email with what to set up.
7. **Database and other server settings are set once per server in the Hub** and sent encrypted
with each job; `.env` files are built from a per-product template and only appended to on
updates; generated secrets stay on the server.
8. A read-only agent on the central server checks ports and `proxy_bind_addr`.
## Still open
Nothing.
+255
View File
@@ -0,0 +1,255 @@
# Cross Events 2.2.0 — moving into the monorepo
Phase **1b** of [ROADMAP-v3.md](./ROADMAP-v3.md) (§8 "Releases and updates", §9; decisions 21, 23,
24). Written 2026-11-05.
**What 2.2.0 is:** Cross Events moves from `joshua/hope-events` into this repo as `apps/events`,
with its git history, and the **`crosscode` script** replaces `scripts/deploy.sh` and
`scripts/install.sh`. **It changes no features.** If something breaks, the cause is the move.
Churches see one line in What's new ("Nothing changes for you").
**Done when:**
- `events@2.2.0` is tagged here, and the Hub lists it under Cross Events.
- Every existing install has been moved with `crosscode adopt` and reports 2.2.0.
- `hope-events` is archived.
- The test results match 2.1.1's.
## Before starting
- **Hub 2.0.0 is deployed.** Its release sync already reads `events@…` tags from this repo, with
notes in `apps/events/WHATS-NEW.md` (`events-hub/backend/src/utils/releaseSync.js`). It also
keeps the `hope-events` `v…` source for older releases. Hub 1.7 can't see `events@` tags.
- `hope-events` `main` is at 2.1.1 with nothing in flight, and **frozen** from step 1 on. A fix
needed during the move goes in on the `hope-events` side as 2.1.2 and is merged in again
(step 1 can be re-run).
- **Baseline:** the result counts of 2.1.1's backend Jest run, frontend build and Playwright e2e
run, so step 6 has something to compare against.
- `git-filter-repo` installed on the dev machine (`pip install git-filter-repo`).
## 1. History: merge it in, with paths rewritten
On a fresh clone, so the working repo is never rewritten:
```bash
git clone https://c-git.crosscode.co.za/joshua/hope-events.git events-move
cd events-move
git tag -l | xargs git tag -d # v… tags stay in the archived repo
git filter-repo --to-subdirectory-filter apps/events
cd ../crosscode-platform
git checkout -b move/events
git remote add events-move ../events-move && git fetch events-move main
git merge --allow-unrelated-histories events-move/main \
-m "Cross Events moves into the monorepo (apps/events), from hope-events <last commit hash>"
git remote remove events-move
```
- **Why `filter-repo` rather than `git subtree add`:** every old commit then already has its
`apps/events/…` path, so `git log` and `git blame` on a file show its whole history without
`--follow`. Commit hashes change. The archived repo keeps the originals, and the merge message
names the last one.
- **Old tags aren't brought over.** Bare `v2.1.1` tags would be ambiguous in a monorepo, and the
Hub reads them from the archived repo. Product tags start at `events@2.2.0`.
## 2. Workspaces and the lockfile
- Root `package.json` → `"workspaces": ["packages/*", "apps/*", "apps/events/backend",
"apps/events/frontend"]`. `apps/events` itself is covered by `apps/*` (its root scripts and
Playwright).
- Rename the packages so workspace names are unique: `@crosscode/events` (was `hope-events`),
`@crosscode/events-backend`, `@crosscode/events-frontend`. Nothing reads the names. The Hub
reads the backend's `version` (`backend/src/hub/report.js`), and that stays. All three go to
`2.2.0`.
- **One lockfile at the root.** Delete `backend/package-lock.json` and
`frontend/package-lock.json`, then run `npm install` at the root. **Versions must not drift:**
compare `npm ls --all` before and after (next, react, prisma, @prisma/client, express,
typescript, jest, ts-jest, @sentry/nextjs, pg-boss, and anything else resolved differently).
Pin anything that moved with `overrides`. Keep the existing `shell-quote` override at the root.
- **Hoisting traps to check:**
- Prisma's `prisma-client-js` generates into the hoisted `node_modules/.prisma/client`. That's
fine while Events is the only Prisma app. **Accounts (phase 3) must use its own generator
`output`**, otherwise the two overwrite each other locally. On servers each checkout builds
only one app, so the problem doesn't arise there. Events keeps the default, so no imports
change in 2.2.0.
- Next.js 16 finds the workspace root from the lockfile. Once the nested lockfiles are gone,
there's no "multiple lockfiles" warning, and `next build` traces files from the repo root.
Check that `.next` still builds to `apps/events/frontend/.next`, and that `NEXT_DIST_DIR`
(e2e) still works.
- `@types/node` 20, TypeScript 5, Jest 30 and ESLint 10 are the same majors on both sides.
- **Lint:** the root `eslint .` ignores `apps/events/**` (add it to `globalIgnores`). Events
keeps its own configs: `frontend/eslint.config.mjs`, plus `tsc` for the backend. Moving Events
onto the root lint is a later cleanup, not part of 2.2.0.
- **Root `npm run check`** runs Events' scripts through `--workspaces --if-present`: backend
`test` and `typecheck`, frontend `build`. Make sure the backend tests run with no database, as
they do today. If any need one, give them their own script so the root `check` stays
self-contained.
## 3. Inside `apps/events`
Paths mostly carry over, because everything in Events is relative to its own folder:
- **`.gitignore`** moves to `apps/events/.gitignore`. Git reads a nested `.gitignore` relative to
its own folder, so `/ecosystem.config.js`, `backend/public/uploads/`, `backend/backups/` and
`backend/data/*.json` keep working unchanged. Check with `git status --ignored` on a copy of a
real install.
- **`ecosystem.config.js`** uses `__dirname + '/backend'`. Placed in `apps/events/`, it needs no
change. `adopt` rewrites only installs whose copy has absolute `cwd` paths.
- **Playwright** (`apps/events/playwright.config.ts`) keeps its `cwd: "backend"` / `"frontend"`.
Run it from `apps/events`.
- **Docs:** `ROADMAP-v3.md` and `hub-protocol.md` already live in the root `docs/`. Remove their
pointer stubs from `apps/events/docs/` in the merge. Code comments that cite
`docs/hub-protocol.md` then point at the root copy. `apps/events/docs/HANDOVER.md` keeps the
Events-only parts (where the code lives, known gaps), and the cross-product status lives in the
root [HANDOVER.md](./HANDOVER.md).
- **`CHANGELOG.md` and `WHATS-NEW.md`** stay in `apps/events/` (the Hub reads
`apps/events/WHATS-NEW.md`). The 2.2.0 entry in `WHATS-NEW.md` has no `— requires`.
- **`README.md` and `DEPLOYMENT.md`:** rewrite the deploy and install sections for `crosscode`.
The nginx and PM2 background stays.
- `scripts/deploy.sh` and `scripts/install.sh` are **removed** from `apps/events`. The archived
repo keeps them for installs that haven't moved yet.
## 4. The `crosscode` script
It lives in this repo's root `scripts/`. It's bash, like today's scripts, and is checked with
`shellcheck`. On a server it's a checkout of `main` in `/opt/crosscode/tools`, updated with
`git pull --ff-only` at the start of every run, then re-run from a copy (as `deploy.sh` does
today, so a checkout never changes the running script).
```
scripts/
crosscode entry: self-update, re-run from a copy, dispatch, `help`
lib/common.sh logging, root/app-user checks, church.env read/write, tag lookup
lib/deploy.sh checks → per product in order → summary
lib/install.sh new church (from today's install.sh)
lib/adopt.sh existing Events install → monorepo
lib/status.sh
products/events.sh the product's hooks (below); accounts.sh, website.sh, app.sh follow
tests/ bats tests for the parts that don't need a server
```
**Product hooks.** Each `products/<name>.sh` defines `backup`, `install_deps` (`npm ci
--include=dev -w apps/events/backend -w apps/events/frontend`), `migrate`, `build`, `pm2_names`,
`health_url` and `rollback_build`. With hooks, adding Accounts in phase 3 means adding a file,
not rewriting the deploy. For Events they come from today's `deploy.sh`: the backup through
`backupUtils.runBackup()`, `prisma migrate deploy`, the backend `tsc` build and `next build`.
**`church.env`** (`/var/www/sites/<church>/church.env`, mode 600, owned by root):
```
CHURCH=hopefamily
PRODUCTS="events" # accounts website app as they're added
ADDRESS=hopefamily.co.za # or hopefamily.crosscode.co.za
EVENTS_DIR=/var/www/sites/hopefamily/events
EVENTS_DOMAIN=events.hopefamily.co.za
EVENTS_PM2="hope-events-backend hope-events-frontend"
EVENTS_PORTS="5000 3000" # api web
EVENTS_DB=hope_events
EVENTS_USER=hopeevents
```
Secrets stay in each product's own `.env`, never in `church.env`.
**Commands in 2.2.0:**
| Command | In 2.2.0 |
|---------|----------|
| `deploy <church> [events]` | Yes. Accounts is skipped while a church has none (§8). Tags are `events@x.y.z`, newest by version (`git tag -l 'events@*' --sort=-v:refname`) |
| `deploy … --version events@x.y.z`, `--main`, `--check` | Yes |
| `deploy --every-church …` | Yes (it's a loop over `/var/www/sites/*/church.env`) |
| `status [<church>]` | Yes: version from `/health`, latest tag, DB, jobs, last backup |
| `install <church> --products events --domain …` | Yes, for Events only (from today's `install.sh`: Node 24, PostgreSQL, PM2, nginx, certbot); it writes `church.env` |
| `adopt <church> --events-dir …` | Yes (section 5) |
| `adopt <church> --undo` | Yes (decision 26): goes back to the old folder and the 2.1.x it ran, within the days the old folder is kept |
| `add <church> <product>` | **Later** (phase 3), when there's a second product to add |
**Requirement check** (decision 24): before anything is touched, read the target version's
heading in `apps/<product>/WHATS-NEW.md`. Refuse the deploy if a `— requires <product> <version>`
isn't met by the installed sibling or by this same run. Nothing in 2.2.0 requires anything, but
the check is built and tested now.
**A deploy, per product** (as `deploy.sh` today): refuse if files were changed by hand →
database backup → `git fetch --tags` and check out the tag (detached) → install and build that
app only → migrations → `pm2 reload` → poll `/health` until it reports the new version (60 s).
On failure that product goes back to its previous tag and rebuilds, and the run stops. The
summary lists each product as updated, rolled back or not reached.
## 5. `crosscode adopt` (once per existing install)
**Decided 2026-11-05 (ROADMAP decision 25):** build the new checkout **next to** the running
install, then switch over, instead of moving the running folder. Moving the folder underneath running PM2
processes breaks anything they read from disk later (Next.js pages, uploads), so the site would
be down for the whole build. Building next to it keeps the old install untouched, which makes
rolling back simply "start the old one again".
1. **Checks:** the old folder is a `hope-events` checkout at a `v2.1.x` tag with no files changed
by hand, and `/var/www/sites/<church>/events` doesn't exist (or is already an adopted
checkout, in which case stop: nothing to do).
2. **Read what the install already has:** the PM2 names and ports from `ecosystem.config.js`, and
the database name from `backend/.env` `DATABASE_URL`. Write `church.env`.
3. **New checkout** of this repo at `events@2.2.0` in `/var/www/sites/<church>/events`, owned by
the app user.
4. **Copy the install's own files** into `apps/events/`: `backend/.env`, `frontend/.env*`,
`ecosystem.config.js` (with absolute `cwd`s rewritten), `backend/data/*.json`, and
`backend/backups/`. Then `rsync -a backend/public/uploads/`, which may be large; the old site
is still serving meanwhile.
5. **Build** (`npm ci -w …`, backend build, `next build`). The old install keeps running.
6. **Switch over** (the only downtime, a few seconds): database backup → a final
`rsync -a --delete` of the uploads and `data/*.json` → `prisma migrate status` must show
nothing pending (2.2.0 adds no migrations; refuse if it does) → `pm2 delete` the two names →
`pm2 start ecosystem.config.js` from the new folder → `pm2 save` → `/health` reports 2.2.0.
7. **On failure at step 6:** `pm2 delete` → `pm2 start` from the old folder → `pm2 save`. Nothing
in the old folder was changed, so it comes back exactly as it was.
8. **Keep the old folder**, renamed `<old>.pre-2.2.0`, for 14 days. `adopt --undo` uses it.
After that, `crosscode status` reminds you to remove it.
The nginx config doesn't change (it only proxies to ports), and neither do the PM2 names, the
database or its name.
## 6. Testing
- **Events, unchanged behaviour:** backend Jest, `tsc --noEmit`, frontend build and the
Playwright e2e run, all from the monorepo. They should give the same counts as the 2.1.1
baseline.
- **Script:** `shellcheck`, plus bats tests for tag lookup, the `— requires` parsing,
`church.env` reading and writing, and the rewriting of `ecosystem.config.js`.
- **On a throwaway Ubuntu 24.04 VM** (e.g. multipass), in this order:
1. `install.sh` from the archived repo at `v2.1.1`. Add demo data and a few uploads.
2. `crosscode adopt` → 2.2.0 works, the uploads are there, and the database is unchanged.
3. `adopt --undo` → back on 2.1.1. Then `adopt` again.
4. `crosscode deploy <church> events --version events@2.2.0-test` with a broken migration on a
test tag → it rolls back to 2.2.0 and the site stays up.
5. A file changed by hand → `deploy --check` refuses it.
6. A second church with `crosscode install` on the same VM → separate databases, `.env` files,
uploads and PM2 names. `deploy --every-church` updates both.
7. `crosscode status` for both.
8. The Hub (local, port 5200) sees the install's heartbeat as 2.2.0, and `events@2.2.0` under
Releases.
## 7. Rolling it out
1. **`hope-events`, last commit on `main`:** README "Moved to `crosscode-platform/apps/events`;
this repo only keeps 2.1.x for installs that haven't moved". No tag.
2. **Here:** merge `move/events` → `npm run check` → tag `events@2.2.0` → push with tags. Remove
any test tags first.
3. **Hub:** run release sync. Check that Cross Events shows 2.2.0 and the older `v…` releases
are still listed.
4. **Servers:** set up `/opt/crosscode/tools`. Adopt a staging copy first, then each real
install one at a time, checking `crosscode status` after each. Installs on 2.1.1 see 2.2.0 on
the Hub. Their "Request update" is answered with `adopt`, not `deploy`.
5. **When every install reports 2.2.0:** archive `hope-events` on Gitea (read-only; cloning and
fetching still work, so `adopt --undo` and old installs keep working).
6. **crosscode-site:** nothing changes (ROADMAP §9).
7. **Docs:** a 2.2.0 entry in `apps/events/CHANGELOG.md` and the root `CHANGELOG.md`, and the
root [HANDOVER.md](./HANDOVER.md) updated with 1b done and 1c (2.3.0, authenticator app 2FA)
next.
## Decisions
1. `adopt` builds next to the old install and switches over (section 5); ROADMAP §8 updated to
match (decision 25).
2. `adopt --undo` is built (decision 26).
## Still open
- Do any Events backend tests need a database, which would affect the root `npm run check`?
(Answered while doing section 2.)
+60
View File
@@ -0,0 +1,60 @@
# Handover — Cross Code, all products
Last updated: 2026-11-12. **The plan is [ROADMAP-v3.md](./ROADMAP-v3.md)** (decided 2026-11-03,
decisions table near the end). This file says where each phase stands and what comes next.
Product-specific notes (where the code lives, known gaps) stay with each product: Cross Events'
are in `hope-events/docs/HANDOVER.md` (`apps/events/docs/HANDOVER.md` from Events 2.2.0), and
the Hub's are in `events-hub/docs/`.
The docs for every product are here in `docs/`: the roadmap, the Hub protocol
([hub-protocol.md](./hub-protocol.md), with a copy in `events-hub`), this handover and the plans
for each phase. They moved here from `hope-events/docs/` on 2026-11-05.
## Repos
| Repo | What |
|------|------|
| `joshua/crosscode-platform` (this one) | Contracts, the apps (Accounts, Website, App, and Events from 2.2.0), shared packages, the `crosscode` script (from Events 2.2.0), the server agent (`apps/agent`, phase 1d), and these docs |
| `joshua/hope-events` | Cross Events up to 2.1.x. Archived after the 2.2.0 move |
| `joshua/events-hub` | Cross Code Hub. Its own server, its own `scripts/deploy.sh` |
| `joshua/crosscode-site` | crosscode.co.za. Updated at the end of every phase that changes what it says (ROADMAP §9) |
## Where each phase stands (ROADMAP §9)
| Phase | What | State |
|-------|------|-------|
| 0 | contracts 1.0.0 / 1.1.0 | **Released** 2026-11-04 (`contracts@1.0.0`, `contracts@1.1.0`). Not published to a registry (decision 22): the Hub gets a packed release committed to its repo |
| 1 | Hub 2.0.0 | **Released** 2026-11-05 (`events-hub` `v2.0.0`; `docs/HUB-2.0-PLAN.md` there). **Not deployed yet:** `events-hub/deployment.md` → "Upgrading to 2.0" (run `check-hub2` first). crosscode-site's address prices are merged, **not deployed yet** |
| 1b | Cross Events 2.2.0: moves here as `apps/events`, `crosscode` script | **Next.** Planned and decided in [EVENTS-2.2-PLAN.md](./EVENTS-2.2-PLAN.md) |
| 1c | Cross Events 2.3.0: authenticator app 2FA (TOTP + recovery codes) | Not started (`TwoFactorMethod` enum in Events' `prisma/schema.prisma`) |
| 1d | Agent 1.0.0 + Hub 2.1.0 (+ contracts 1.2.0): server agent, installs / scheduled updates / uninstalls from the Hub, server stats | **Planned** 2026-11-12 in [AGENT-1.0-PLAN.md](./AGENT-1.0-PLAN.md) (ROADMAP decisions 27–37). Starts after 1b; can run alongside 1c |
| 2 | Cross Events 2.4.0: protocol v2, Linked products, event feed, `packages/seo` | Not started. Events keeps speaking protocol 1 until then |
| 3–7 | Accounts 1.0.0 → Website 1.0.0 → Events 3.0.0 → App 1.0.0 → App 1.x | Not started |
## Next up
1. **Deploy Hub 2.0.0** and **crosscode-site** (the address prices). This finishes phase 1 and is
needed before 2.2.0, because Hub 1.7 can't see `events@…` tags.
2. **Cross Events 2.2.0**: [EVENTS-2.2-PLAN.md](./EVENTS-2.2-PLAN.md). Decided 2026-11-05:
`adopt` builds next to the running install and switches over, and `adopt --undo` is built
(ROADMAP decisions 25–26).
3. **Agent 1.0.0 + Hub 2.1.0** (phase 1d): [AGENT-1.0-PLAN.md](./AGENT-1.0-PLAN.md). Before the
first install through it: check `proxy_bind_addr = 127.0.0.1` in `frps.ini` on the central
server (worth doing now: without it, tunnel ports such as `:5000` may be reachable straight from
the internet), and set each server's database settings and `TRUST_PROXY` in the Hub.
4. **Cross Events 2.3.0** (authenticator app 2FA), then 2.4.0, as in ROADMAP §9.
## Things to remember across phases
- **Before selling the Website or App:** put the ROADMAP §10 prices in
`crosscode-site/src/data/pricing.mjs` *and* the Hub's `frontend/src/lib/tiers.ts` (plus
`backend/src/utils/billing/tiers.js`) in the same phase, so the site and the Hub never disagree.
- **A phase isn't done until crosscode-site matches it** (ROADMAP §9, "Updating crosscode-site").
- Servers stay **PM2 + nginx** (no Docker), with one database per product per church, under
`/var/www/sites/<church>/<product>`.
- **Prisma in the monorepo:** each app other than Events sets its own generator `output`, so
hoisted clients don't overwrite each other (EVENTS-2.2-PLAN §2).
- **AI for a church:** set the licence's monthly AI cap above R0 on the Hub; with no cap the
buttons don't show (rules in Events' handover, "AI rules").
- **Releasing:** branch → merge → tag (`<product>@<version>`) → push, with a CHANGELOG entry, and
`npm run check` first. Pushes to c-git often fail authentication the first time; retry once.
+852
View File
@@ -0,0 +1,852 @@
# Cross Code — Road to three products
Planned work to go from one product (Cross Events 2.1.x) to three that can be sold separately or
together: **Cross Events**, a **Church Website** and a **Church App**, all managed from one
**Cross Code Hub**. Based on the two concept specs (church website platform, church app v1.1,
3 November 2026), with the changes decided on 2026-11-03 (see [Decisions](#decisions-2026-11-03)).
See ROADMAP-v2.md (Cross Events: `hope-events/docs/`, `apps/events/docs/` from Events 2.2.0) for how
Cross Events got to 2.x. Where things stand now: [HANDOVER.md](./HANDOVER.md).
**Moved 2026-11-05** from `hope-events/docs/` to the monorepo's `docs/`, since it covers every
product. The Events 2.2.0 move is planned in [EVENTS-2.2-PLAN.md](./EVENTS-2.2-PLAN.md).
**Theme:** a church can have any mix of products (Events, Website, App, all, or just the
Website). People sign in to all of them with **one account**, and events flow between them in
whatever direction the church chooses.
**Updated 2026-11-04:** Cross Events moves into the `crosscode-platform` monorepo (§8), every
product is released and deployed the same way with one `crosscode` script (§8, "Releases and
updates"), the Hub tracks releases per product (§5), and the contracts reach the Hub as a file
committed to its repo instead of through a package registry (§2). Cross Events versions in §9
moved up by one (the move is 2.2.0). See decisions 21–24.
**Updated 2026-11-12:** a **server agent** on each server installs, updates and uninstalls
church sites on signed jobs from the Hub (phase 1d, [AGENT-1.0-PLAN.md](./AGENT-1.0-PLAN.md)).
The Hub can now trigger changes, but no site depends on it to keep running and the agent only
polls (it has no URL or open port). Rule 2 (§1), §5, §8 and §9 are updated; decisions 27–37
change decisions 10 and 23.
---
## 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.** Installs push to it, it never connects to them, and
a Hub outage switches nobody off. **Changes to a site are made by the server agent** on its
server (from phase 1d): it polls the Hub for **signed jobs of fixed types**, only ever runs the
`crosscode` script, and has no URL or listening port of its own (§8, decisions 27–37).
3. **One maintained codebase per product.** Each church runs a tagged release of it. Nothing is
built specially for one church.
4. **The origin of a record owns it.** Copies elsewhere are read-only and link back to the origin.
**Products and what each one owns**
| Product | Owns | Doesn't do |
|---------|------|------------|
| **Accounts** | People's accounts: name, email, phone, password, 2FA, privacy notice acceptance, news consent | Anything product-specific |
| **Cross Events** | Events with registrations, tickets, payments, check-in, kids, rosters, POPIA toolkit | Website content |
| **Church Website** | Public pages, leaders, ministries, messages (sermons), service times, simple events | Registrations or payments |
| **Church App** | House of Prayer, announcements, devotionals, reading plans, groups, care, simple events | Registrations or payments |
---
## 2. Contracts (shared JSON formats)
Everything that crosses between products is defined **once**, in a shared package
`@crosscode/contracts` (zod schemas + generated JSON Schema + TypeScript types + sample payloads).
Every product, including Cross Events and the Hub, uses it. This is what keeps the key fields the
same in every product's JSON.
| Contract | Used for |
|----------|----------|
| `crosscode.event/1`, `crosscode.event-feed/1` | One event, and the feed every product publishes and reads (with the `event.changed` webhook) (§4) |
| `crosscode.church/1` | The church profile: name, logo, colours, campuses, service times, contact details. Set once and shared |
| `crosscode.identity/1` | The claims Accounts puts in a sign-in token, and the back-channel calls (`user.updated`, `user.deleted`, `user.export`) |
| Hub protocol v2 | Register, heartbeat, licence token, AI calls, for every product (§5). Today's protocol (Cross Events 2.1, Hub 1.7) is v1, in [hub-protocol.md](./hub-protocol.md) |
**Versioning**
- Adding an **optional** field keeps the version (`/1`). Consumers ignore fields they don't know.
- Removing or renaming a field, adding a value to an enum (older consumers would refuse it), or changing a meaning needs a new version (`/2`). The old
version is served alongside it until every install has updated, as with `/api/v2`.
- Every payload carries its `schema` name, so a consumer always knows what it's reading.
- The package lives in the platform monorepo (§8). Every product there (Events, Accounts, Website,
App) uses it as a workspace, so no registry is involved.
- **The Hub** (its own repo, §8) uses a packed release committed to its repo
(`vendor/crosscode-contracts-<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. From Hub 2.1.0 Joshua answers it with a
**scheduled update** (at least 4 hours' notice to the site admin, emergency at least 15
minutes), carried out by the server agent (§8).
- **Servers (Hub 2.1.0):** every server's agent, its stats (RAM, CPU, disk, spikes, PM2
processes per church), alerts, the frp port list, server configuration (database and other
per-server `.env` values, stored encrypted), new installs with a choice of server, jobs with
emailed reports, and uninstalls with a 30-day encrypted export for the church
([AGENT-1.0-PLAN.md](./AGENT-1.0-PLAN.md)).
- **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), the `crosscode` script (`scripts/`) and the server agent (`apps/agent`, phase 1d) |
| `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, and every install, update and
uninstall goes through the `crosscode` script. Until phase 1d Joshua runs it by hand; from
phase 1d the **server agent** runs it on signed jobs from the Hub (below), and it still works by
hand over SSH.
**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) |
| `crosscode adopt <church> --undo` | Goes back to the old folder and the 2.1.x it ran, while the old folder is kept (14 days) |
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. **The new checkout is built next to the running install, then PM2 switches
over** (decided 2026-11-05, decision 25). The running folder is never moved, because moving it
underneath PM2 would break everything the running processes read from disk later, so the site
would be down for the whole build. The steps are in
[EVENTS-2.2-PLAN.md](./EVENTS-2.2-PLAN.md) §5. In short:
1. Checks: the old folder is a `hope-events` checkout at a `v2.1.x` tag with no files changed by
hand. Reads the PM2 names, ports and database name the install already has, and writes
`church.env`.
2. A fresh checkout of `crosscode-platform` at `events@2.2.0` in
`/var/www/sites/<church>/events`. The install's own files are copied into `apps/events/`:
`backend/.env` and the frontend `.env`, `backend/data/*.json`, `backend/backups/`,
`ecosystem.config.js` (absolute `cwd`s rewritten), and the uploads (`rsync`). Then it builds.
The old install keeps serving throughout.
3. Switch over (a few seconds of downtime): database backup → a final `rsync` of the uploads and
data files → no pending migrations → `pm2 delete` + `pm2 start` from the new folder +
`pm2 save` (PM2 remembers the folder a process was started from, so a reload isn't enough) →
`/health` reports 2.2.0. If that fails, PM2 starts from the old folder again, which was never
changed.
4. The old folder is kept as `<old>.pre-2.2.0` for 14 days. **`crosscode adopt <church> --undo`**
(decision 26) goes back to it within that time, copying back uploads added since.
`crosscode status` reminds you to remove it afterwards.
The PM2 names, nginx config (it only proxies to ports), database and its name stay the same.
Installs that haven't moved yet keep working with `deploy.sh` on the archived repo.
### Server agent (phase 1d)
Planned in [AGENT-1.0-PLAN.md](./AGENT-1.0-PLAN.md). In short:
- **`crosscode-agent`** (`apps/agent`, systemd) on every church server. It **only polls** the Hub
(outgoing HTTPS; no URL, no listening port), sends server stats every minute, and runs
**signed jobs of fixed types** (install, add product, deploy, adopt, restart, export,
uninstall), each by calling the `crosscode` script. Uninstall and emergency updates need 2FA
again in the Hub.
- **Servers are behind frp** to one central FastPanel server. The Hub hands out the tunnel ports
(unique across all servers). The agent **only appends** marked blocks to `/etc/frp/frpc.ini` and
removes only its own blocks. A read-only agent on the central server checks the ports are open
and only bound to `127.0.0.1`. **FastPanel and DNS are never automated:** Joshua gets an email
with what to set up.
- **`.env` files** are built from a per-product template: database and other server values set
**once per server in the Hub** (sent encrypted), platform defaults, the install's domain and
ports, and secrets generated on the server (never sent anywhere). Updates only append new
variables.
- **Updates** are scheduled at least 4 hours ahead (emergency 15 minutes) with an email and banner
to the site admin, and run one install at a time. **Uninstall** gives the church a JSON export
in our own format (encrypted, 30 days) and keeps backups for 30 days.
- New `crosscode` commands for it: `uninstall`, `export`, `purge`, `restart`, and `--json`
reports on every command.
---
## 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 |
| 1d | **Agent 1.0.0 + Hub 2.1.0** (contracts 1.2.0) | **Server agent** on every server (polls only, signed jobs, runs the `crosscode` script); Hub: Servers page with stats and alerts, server configuration, frp port list, New install with a choice of server, scheduled / emergency / batch updates with notice to the church, uninstall with an encrypted JSON export, emailed reports. [AGENT-1.0-PLAN.md](./AGENT-1.0-PLAN.md) | Right after 1b (it runs the `crosscode` script), so every new church from then on is installed from the Hub. Can run alongside 1c |
| 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 |
| 1d Agent 1.0.0 + Hub 2.1.0 | Nothing (it changes how installs are run, not what churches buy) |
| 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.
- (From phase 1d) The product installs, updates and uninstalls through the server agent from the
Hub, with its `.env` template complete and its uninstall export in `crosscode.church-export/1`.
---
## 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). **Changed 2026-11-12** by decisions 27–37: the server agent runs the script on signed jobs from the Hub |
| 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). **Changed 2026-11-12** by decision 27: from phase 1d the server agent runs it on jobs from the Hub |
| 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) |
**Added 2026-11-05**
| # | Question | Decision |
|---|----------|----------|
| 25 | Moving existing Events installs | `crosscode adopt` **builds the new checkout next to the running install and switches PM2 over** (seconds of downtime) instead of moving the running folder; the old folder is untouched, so a failure just starts it again (§8) |
| 26 | Undoing a move | **`crosscode adopt <church> --undo`** goes back to the old folder and its 2.1.x while it's kept (14 days) (§8) |
**Added 2026-11-12** (phase 1d, [AGENT-1.0-PLAN.md](./AGENT-1.0-PLAN.md))
| # | Question | Decision |
|---|----------|----------|
| 27 | Deploying from the Hub | A **server agent** on every server runs installs, updates and uninstalls on **signed jobs of fixed types** from the Hub, always through the `crosscode` script (which still works by hand). Changes decisions 10 and 23; rule 2 (§1) reworded |
| 28 | The agent's exposure | **It has no URL or listening port.** It only polls the Hub over outgoing HTTPS |
| 29 | Confirming risky jobs | Uninstall and emergency updates need **2FA again** in the Hub; uninstall also needs the short name typed |
| 30 | Notice before updates | **Scheduled: at least 4 hours**; **emergency: at least 15 minutes**, with a reason. The site admin gets an email and a banner straight away. Joshua picks the time. A job the agent misses doesn't run late |
| 31 | Uninstall | The church gets a **JSON export in our own format** (`crosscode.church-export/1`, no internal tables or ids), encrypted so the Hub can't read it, downloadable for **30 days**. The final backup is kept 30 days, then deleted (Joshua emailed 3 days before) |
| 32 | frp | Every church server is behind frp to **one central FastPanel server**. The Hub keeps the **port list** (unique across servers, same number local and remote), tunnels are named `<church>-<product>-web/-api` |
| 33 | frpc.ini | **Only appended to**, in marked blocks, checked with `frpc verify`, with a backup first; uninstall removes only its own block. `admin_addr = 127.0.0.1` / `admin_port = 7400` added once to `[common]` so frpc reloads without dropping other sites |
| 34 | FastPanel and DNS | **Never automated.** Joshua gets an email with the proxy rules, Let's Encrypt and DNS to set up, then clicks *Proxy done*; the Hub checks the public URLs |
| 35 | Central server | A **read-only** agent on the central server checks the ports are allowed and open and that frps binds tunnels to `127.0.0.1` (`proxy_bind_addr`). It changes nothing there |
| 36 | `.env` configuration | **Database and other server values are set once per server in the Hub**, stored encrypted and sent encrypted to that server's agent with each job. `.env` files come from a per-product template; updates only append new variables; secrets are generated on the server and never leave it |
| 37 | Server stats | Every agent reports RAM, CPU, disk and PM2 processes every minute; the Hub keeps minutes for 7 days and hours for 90 days, shows spikes, and emails alerts |
## 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.
+328
View File
@@ -0,0 +1,328 @@
# Hub protocol (versions 1 and 2)
The contract between an **install** (one of a church's products: Cross Events, Accounts, Church
Website, Church App) and **Cross Code Hub** (`hub.crosscode.co.za`; `events-hub.crosscode.co.za`
keeps working as an alias). Sections 1–5 describe **version 1**, which Cross Events 2.1 speaks;
**[version 2](#6-protocol-version-2-hub-20)** (every product, Hub 2.0) is section 6. A copy of this
file lives in both repositories (`joshua/crosscode-platform` → `docs/hub-protocol.md`, for every
product; `joshua/events-hub` → `docs/hub-protocol.md`); change both together. (Until 2026-11-05
the install's copy was in `hope-events/docs/`.) From Hub 2.0 the formats are
defined once, in `@crosscode/contracts` (`crosscode-platform/packages/contracts`, `src/hub.ts`,
with JSON Schema and samples).
Principles:
- **Install → Hub only.** The install always starts the conversation; the Hub never calls
into an install. Works behind firewalls, and the Hub has no access to church data.
- **No personal information** is ever sent — counts, versions and health only. Income is
sent as a range, never an amount.
- **A Hub outage never switches a church off.** Licences are signed tokens the install
verifies offline with the Hub's public key.
- Every request carries `protocolVersion`. The Hub accepts the current and the previous
version, so installs waiting to update keep working.
All bodies are JSON (`Content-Type: application/json`). Times are ISO 8601 UTC strings.
Errors are `{ "message": "...", "code": "..." }` with a 4xx/5xx status.
---
## 1. Public key
```
GET /api/public-key
→ 200 { "protocolVersions": [1], "keyId": "k1", "algorithm": "Ed25519", "publicKey": "-----BEGIN PUBLIC KEY-----\n…" }
```
Installs ship with the Hub's public key built in (and may refresh it from here). The private
key exists only on the Hub server.
## 2. Register an install
Sent once, at the end of `/setup` (licence step) or from Site settings → "Connect to Hub".
```
POST /api/installs/register
{
"protocolVersion": 1,
"licenceKey": "CEH-7K2M-9QXA-P4RT-WD8C",
"install": {
"name": "Hope Family Church",
"url": "https://events.hopefamily.co.za",
"adminContact": { "name": "Jane Admin", "email": "jane@hopefamily.co.za" },
"version": "1.41.0",
"timezone": "Africa/Johannesburg",
"server": { "node": "20.18.0", "postgres": "16.4", "os": "linux 6.8" },
"features": { "whatsapp": true, "paymentProviders": ["yoco", "payfast"], "campuses": false }
}
}
→ 201 {
"installId": "inst_…",
"installSecret": "…", // shown once; the install stores it encrypted
"licence": "<licence token>",
"heartbeatIntervalMinutes": 15,
"latestVersion": "1.41.0",
"releases": [ … ], // as in the heartbeat reply (§3); Hub 1.4.0+
"notices": [ … ]
}
```
- `404 LICENCE_NOT_FOUND` — unknown key. `403 LICENCE_REVOKED` — revoked licences can't register.
- One licence = one install. Registering again **from the same URL** re-registers (new
secret, same `installId`). From a different URL → `409 LICENCE_IN_USE` until Joshua releases
the licence in the Hub (e.g. after a move to a new domain).
- The `adminContact` is the one piece of personal information: a work contact for the
church's admin, so Joshua can reach them. It is not used for anything else.
- Rate-limited per IP.
## 3. Heartbeat
Every `heartbeatIntervalMinutes` (15) from the install's job queue.
```
POST /api/installs/heartbeat
X-Hub-Install: inst_…
X-Hub-Timestamp: 2026-10-24T08:15:00.000Z
X-Hub-Signature: <hex HMAC-SHA256(installSecret, timestamp + "." + rawBody)>
{
"protocolVersion": 1,
"version": "1.41.0",
"health": {
"uptimeSeconds": 86400,
"db": true,
"jobs": { "mode": "queue", "failedLast24h": 0 },
"lastBackupAt": "2026-10-24T00:00:12.000Z", // null if none
"disk": { "freeBytes": 21474836480, "totalBytes": 53687091200 }, // null if unknown
"errorsLast24h": 0, // null if not tracked
"pendingMigrations": 0
},
"stats": {
"users": 412,
"events": { "active": 3, "upcoming": 5, "total": 61 },
"registrations": { "last30d": 88, "total": 2310 },
"tickets": { "last30d": 140, "total": 3901 },
"checkIns": { "last30d": 96 },
"messages": { "email30d": 610, "whatsapp30d": 233 },
"paymentProviders": ["yoco", "payfast"],
"campuses": false, // Site settings → Campuses on/off
"campusCount": 0, // active campuses (0 while off; Cross Events 1.43.0+)
"income": { "last30d": "R5 001–R20 000", "allTime": "R150 001–R250 000",
"eventIncome12m": "R100 001–R150 000" } // eventIncome12m: Cross Events 2.0.2+
}
}
→ 200 {
"licence": "<fresh licence token>",
"latestVersion": "1.42.0",
"releases": [ // Hub 1.4.0+: newer than the version sent, newest first, at most 20
{ "version": "1.42.0", "releasedAt": "2026-10-27T10:00:00.000Z", "urgent": false, "notes": "- Event series\n- Fixed: …" }
],
"notices": [ // Hub 1.4.0+: the provider's banners for this install
{ "id": "…", "level": "maintenance", "title": "Planned maintenance", "message": "…",
"startsAt": "2026-11-01T16:00:00.000Z", "endsAt": "2026-11-01T16:30:00.000Z", "updatedAt": "…" }
],
"serverTime": "…"
}
```
- **`releases`** — what's new in each version, so the church can decide whether to ask for the
update. The Hub takes the versions from the Cross Events repository's `v*` tags and the notes from
its `WHATS-NEW.md`. `notes` is plain text; lines starting with `- ` are
a list. `urgent` marks security or serious bug fixes: the install shows those in red and doesn't let
admins put them off. The highest release is `latestVersion`.
- **`notices`** — banners Joshua posts on the Hub's Notices page (`level`: `info`, `maintenance` or
`warning`). Sent until `endsAt`, including ones that haven't started, so the install shows each one
from `startsAt` without waiting for a heartbeat. The install shows them to site admins and
supervisors. Notices can also be emailed; that happens on the Hub, not through the install.
- A Hub older than 1.4.0 sends neither field; the install then shows no notes and no notices.
- The signature covers the exact bytes sent. Requests more than **5 minutes** off the Hub's
clock are refused (`401 STALE_REQUEST`); a bad signature is `401 BAD_SIGNATURE`; an unknown or
released install is `404 INSTALL_NOT_FOUND` (the install should show "Reconnect to Hub").
- **Income bands** (worked out on the install; the amount never leaves it): `R0–R1 000`,
`R1 001–R5 000`, `R5 001–R20 000`, `R20 001–R50 000`, `R50 001–R100 000`,
`R100 001–R150 000`, `R150 001–R250 000`, `R250 001–R400 000`, `R400 001–R700 000`,
`R700 001–R1 000 000`, `R1 000 001–R2 500 000`, `R2 500 001–R5 000 000`,
`R5 000 001–R10 000 000`, `over R10 000 000`. Before Cross Events 2.0.2 the bands stopped at
`over R100 000`, and donations applied to a registration were counted twice.
- **`eventIncome12m`** (Cross Events 2.0.2+) is the band of the last 365 days' event income:
payments less refunds, without donations or sponsorships. Cross Code's licence tiers are billed
on it, so every tier edge is a band edge. Older installs don't send it.
- The Hub keeps every heartbeat for 30 days, then one per install per day.
## 3a. Update request
Sent when a site admin presses **Request update** (Site settings → Licence). Installs never update
themselves and never show the deploy command; the request tells Joshua, who updates the server.
Signed exactly like the heartbeat.
```
POST /api/installs/update-request
X-Hub-Install / X-Hub-Timestamp / X-Hub-Signature (as in §3)
{ "protocolVersion": 1, "version": "1.41.2" }
→ 201 { "requestedAt": "2026-10-27T09:00:00.000Z", "version": "1.42.0", "alreadyRequested": false, "changed": false }
→ 200 { …, "alreadyRequested": true, "changed": false } // a request for the latest is already open: not emailed again
→ 200 { …, "alreadyRequested": true, "changed": true, "previousVersion": "1.42.0" }
// the open request was for an older version: it now asks for the latest
```
- The Hub opens an `update_requested` alert on the install (shown under Alerts) and emails the
alert address once. It is resolved when a heartbeat reports a newer version than before.
- **Changing a request (Hub 1.5.0):** when a request is open for a version that has since been
overtaken, asking again moves it on to the latest version — the alert says "latest is 1.47.3
(changed from 1.47.0)" and the alert address is emailed once about the change. `version` is
always the version now asked for. A Hub before 1.5.0 doesn't send `changed`; installs then
withdraw the request and ask again (two emails, same result).
- `409 UP_TO_DATE` — the install already runs the Hub's latest version (or none is set).
- Errors as in §3 (`INSTALL_NOT_FOUND`, `STALE_REQUEST`, `BAD_SIGNATURE`). Rate-limited (10 an
hour per IP). A Hub older than this section answers `404 NOT_FOUND`.
- No personal information: not who pressed the button (the Hub already has the admin contact).
### Withdrawing it
Sent when a site admin presses **Withdraw request**. Signed like the heartbeat.
```
POST /api/installs/update-request/cancel
X-Hub-Install / X-Hub-Timestamp / X-Hub-Signature (as in §3)
{ "protocolVersion": 1 }
→ 200 { "cancelled": true } // the open request was resolved, and Joshua is emailed
→ 200 { "cancelled": false } // there was no open request
```
- The Hub resolves the `update_requested` alert and records `update_request_withdrawn` in the install's
history. Rate-limited with update requests. A Hub older than 1.4.0 answers `404 NOT_FOUND`.
- **"Not now"** (no reminders until the next version) stays on the install; the Hub isn't told.
## 3b. AI (Cross Events 2.0, Hub 1.6.0)
Installs never hold the Claude API key. Each AI helper call goes through the Hub, which adds the
key, checks the licence's monthly cap, calls Claude and meters the call. Both requests are signed
exactly like the heartbeat. The install keeps its prompts; the Hub stores **no prompt or response
text** — only the install, helper name, tokens, cost and time.
### Status
```
POST /api/installs/ai/status
X-Hub-Install / X-Hub-Timestamp / X-Hub-Signature (as in §3)
{ "protocolVersion": 1 }
→ 200 { "enabled": true, "capReached": false, "capCents": 5000, "usedCents": 812.4,
"usedPercent": 16, "renewsOn": "2026-12-01" }
```
- **`enabled: false`** — hide the AI buttons everywhere: the licence's cap is R0, the licence isn't
active (suspended, revoked, or past its grace days), or the Hub's AI isn't set up.
- **`capReached: true`** — show the buttons **disabled** ("This month's AI allowance is used up — it
renews on 1 December"). Reached means there isn't room left for even a small call.
- Amounts are cents (rand) as **charged** to the church, with fractions (a call costs a fraction of a
cent). The month is South African time; `renewsOn` is the 1st of the next month.
### A helper call
```
POST /api/installs/ai/complete
X-Hub-Install / X-Hub-Timestamp / X-Hub-Signature (as in §3)
{
"protocolVersion": 1,
"helper": "draft_event", // lower-case name, for usage reports
"system": "…", // the helper's fixed instructions (cached by Claude)
"input": "…", // this request's text
"schema": { … }, // optional JSON schema: the reply is JSON in that shape
"maxTokens": 2000, // 1–8000
"effort": "low" // optional: low (default) | medium | high
}
→ 200 { "output": "…" | { … }, // text, or the parsed JSON when a schema was given
"usage": { "inputTokens": 1840, "outputTokens": 420 },
"chargedCents": 0.31,
"status": { …as above… } }
```
- **Errors** are `{ code, message, status }` — `status` is the new AI status, so buttons can disable
straight after the call that used up the allowance:
- `402 AI_CAP_REACHED` — this call could pass the cap (checked before calling Claude).
- `403 AI_OFF` (cap R0) · `403 LICENCE_INACTIVE` · `503 AI_NOT_CONFIGURED` (Hub not set up).
- `422 AI_REFUSED` — Claude declined. `502 AI_INCOMPLETE` — the answer hit `maxTokens`.
`502 AI_FAILED` — not usable (e.g. JSON in the wrong shape). These still cost what was used.
- `503 AI_BUSY` / `503 AI_UNAVAILABLE` — Claude unreachable or rate-limited; nothing is charged.
- `400 BAD_REQUEST`, `413 AI_INPUT_TOO_LARGE` (about 90 000 tokens), and the §3 errors.
- **Metering:** real cost = tokens × the model's price × the exchange rate set in the Hub; charged =
real × (1 + markup). The cap counts charged rand. Before calling Claude the Hub holds the worst
case (an over-estimate of the prompt, plus `maxTokens`) against the cap in one transaction per
install, so calls at the same moment can't pass it; afterwards the hold becomes the real amount.
- Rate-limited to 60 a minute per IP (against runaway loops; money is limited by the cap).
- A Hub older than 1.6.0 answers `404 NOT_FOUND`: the install treats that as "AI off".
## 4. Licence token
`hel1.<payload>.<signature>` — `payload` is base64url JSON, `signature` is the base64url
Ed25519 signature of the ASCII string `hel1.<payload>`.
```json
{
"v": 1,
"licenceId": "lic_…",
"installId": "inst_…",
"customer": "Hope Family Church",
"plan": "standard",
"status": "active", // active | suspended | revoked
"licenceExpiresAt": "2027-10-31T21:59:59.000Z", // null = no end date
"graceDays": 14,
"issuedAt": "2026-10-24T08:15:00.000Z",
"validUntil": "2026-11-23T08:15:00.000Z", // issuedAt + 30 days
"limits": { "aiMonthlyCapCents": 0 } // the AI cap (§3b); 0 = AI off
}
```
### What the install does with it
The install keeps the newest valid token (signature checks out, `installId` matches) and works
out its state:
| State | When | What happens |
|-------|------|--------------|
| **active** | `status` is active and now is before `min(licenceExpiresAt, validUntil)` | Everything works |
| **grace** | after that date, for up to `graceDays` | Everything works; **only site admins** see a banner "Licence needs renewing — X days left" |
| **suspended** | `status` is suspended, or grace has run out | Read-only: events can't be created or edited; no new registrations or payments. Tickets still scan; admins can view and export all data; privacy requests still work |
| **revoked** | `status` is revoked | Same as suspended, with a permanent banner |
| **unlicensed** | never connected, or the Hub answered `INSTALL_NOT_FOUND` (the install drops its token) | Same as suspended (events can't be created or edited either); admins see "Connect to Hub" |
`validUntil` is refreshed by every heartbeat, so a Hub outage only matters after 30 days (then
grace starts). Blocking the Hub can't keep a suspended licence active for more than 30 days.
## 5. Versioning
- `protocolVersion` goes up only for changes an older install can't handle. Adding optional
fields to a heartbeat or a token doesn't need a new version — both sides ignore fields they
don't know.
- The Hub accepts protocol `N` and `N-1`; anything else is `400 UNSUPPORTED_PROTOCOL`.
## 6. Protocol version 2 (Hub 2.0)
The formats are in `@crosscode/contracts` (`hub.registerRequestSchema`, `hub.heartbeatRequestSchema`,
… with JSON Schema in `schemas/hub-*.json` and samples in `samples/hub-*.json`). The Hub accepts
versions 1 and 2 (`/api/public-key` lists `[1, 2]`); a v1 request is treated as Cross Events and
answered exactly as in sections 1–5. Signing, offline licence checks, update requests and AI calls
are as in version 1.
What version 2 changes:
| | Version 1 | Version 2 |
|---|---|---|
| Who | Cross Events | Every product: `product` is `events`, `accounts`, `website` or `app` |
| Licence keys | `CEH-…` | `CEH-` Events, `CCA-` Accounts, `CCW-` Website, `CCP-` App |
| Register | as §2 | adds `product` (must match the licence: `409 WRONG_PRODUCT`) and `install.publicKey` (the install's Ed25519 public key, PEM) |
| Heartbeat | as §3 | adds `product` (must match the install: `409 WRONG_PRODUCT`); `stats` per product (Events as v1; Website: pages, messages, events, editors, `storage`; App: `activeMembers90d` band, modules, prayer coverage; Accounts: accounts, 2FA methods) |
| Replies | as §2, §3 | add `linkedProducts`: the church's other installs in use that have a public key, as `{ product, installId, url, publicKey }`, nothing else. Releases carry `requires` (below) |
| Bodies | checked by hand | checked against the contract schemas: `400 INVALID_REQUEST` with the field that's wrong; unknown fields are dropped |
| Licence token | as §4 | also `customerId` and `product` (still `v: 1`; a v1 install ignores them). `limits.aiMonthlyCapCents` is the church's cap |
**Releases per product.** An install is told its own product's releases and latest version. A
release can need a minimum version of a sibling (`— requires accounts 1.2.0` in its WHATS-NEW.md
heading): v2 replies carry it as `requires: [{ product, version }]`, and an update request answers
`409 REQUIREMENT_NOT_MET` (with `requirements: [{ product, version, current }]` and a message saying
what's needed) until the church's install of that product runs that version or later.
**AI.** The monthly cap and markup are the church's, shared by all its installs: a call from any of
them counts what all of them used this month.
**Moving an install to v2** (e.g. Cross Events 2.4.0): register again with `protocolVersion: 2`,
the product and a public key (same licence and address: same install id, new secret), then send v2
heartbeats. Nothing on the Hub needs changing.
+1 -1
View File
@@ -2,7 +2,7 @@
"name": "crosscode-platform", "name": "crosscode-platform",
"version": "0.0.0", "version": "0.0.0",
"private": true, "private": true,
"description": "Cross Code platform monorepo: Accounts, Church Website, Church App and the shared contracts (see docs/ROADMAP-v3.md in hope-events)", "description": "Cross Code platform monorepo: Accounts, Church Website, Church App and the shared contracts (see docs/ROADMAP-v3.md)",
"workspaces": [ "workspaces": [
"packages/*", "packages/*",
"apps/*" "apps/*"
+1 -1
View File
@@ -1,6 +1,6 @@
{ {
"name": "@crosscode/contracts", "name": "@crosscode/contracts",
"version": "1.0.0", "version": "1.1.0",
"description": "The shared JSON formats used by every Cross Code product: zod schemas, JSON Schema, TypeScript types and sample payloads", "description": "The shared JSON formats used by every Cross Code product: zod schemas, JSON Schema, TypeScript types and sample payloads",
"license": "UNLICENSED", "license": "UNLICENSED",
"type": "commonjs", "type": "commonjs",
@@ -1,7 +1,14 @@
{ {
"licence": "hel1.eyJ2IjoxfQ.c2lnbmF0dXJl", "licence": "hel1.eyJ2IjoxfQ.c2lnbmF0dXJl",
"latestVersion": "2.3.1", "latestVersion": "3.0.0",
"releases": [ "releases": [
{
"version": "3.0.0",
"releasedAt": "2026-12-01T10:00:00.000Z",
"urgent": false,
"notes": "- Sign in with your church account",
"requires": [{ "product": "accounts", "version": "1.2.0" }]
},
{ "version": "2.3.1", "releasedAt": "2026-11-10T10:00:00.000Z", "urgent": false, "notes": "- Fixed: feed sync after a campus is renamed" } { "version": "2.3.1", "releasedAt": "2026-11-10T10:00:00.000Z", "urgent": false, "notes": "- Fixed: feed sync after a campus is renamed" }
], ],
"notices": [ "notices": [
@@ -36,6 +36,31 @@
}, },
"notes": { "notes": {
"type": "string" "type": "string"
},
"requires": {
"type": "array",
"items": {
"type": "object",
"properties": {
"product": {
"type": "string",
"enum": [
"events",
"website",
"app",
"accounts"
]
},
"version": {
"type": "string",
"pattern": "^\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z.-]+)?$"
}
},
"required": [
"product",
"version"
]
}
} }
}, },
"required": [ "required": [
@@ -50,6 +50,31 @@
}, },
"notes": { "notes": {
"type": "string" "type": "string"
},
"requires": {
"type": "array",
"items": {
"type": "object",
"properties": {
"product": {
"type": "string",
"enum": [
"events",
"website",
"app",
"accounts"
]
},
"version": {
"type": "string",
"pattern": "^\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z.-]+)?$"
}
},
"required": [
"product",
"version"
]
}
} }
}, },
"required": [ "required": [
+11 -1
View File
@@ -4,7 +4,7 @@ import { TWO_FACTOR_METHODS } from "./identity";
/** /**
* Hub protocol v2 — between every Cross Code install and Cross Code Hub (ROADMAP-v3 §5). * Hub protocol v2 — between every Cross Code install and Cross Code Hub (ROADMAP-v3 §5).
* Protocol v1 is the one in `hope-events/docs/hub-protocol.md` (Cross Events 2.1, Hub 1.7). * Protocol v1 is the one in `docs/hub-protocol.md` (Cross Events 2.1, Hub 1.7).
* *
* What v2 changes: * What v2 changes:
* - `product` on register and heartbeat; the heartbeat's `stats` depend on the product. * - `product` on register and heartbeat; the heartbeat's `stats` depend on the product.
@@ -71,11 +71,21 @@ export function activeMemberBand(count: number): (typeof ACTIVE_MEMBER_BANDS)[nu
const count = z.int().nonnegative(); const count = z.int().nonnegative();
/** A minimum version of a sibling product that a release needs (`— requires accounts 1.2.0`). */
export const releaseRequirementSchema = z.object({ product: productSchema, version: semverSchema });
export type ReleaseRequirement = z.infer<typeof releaseRequirementSchema>;
export const releaseSchema = z.object({ export const releaseSchema = z.object({
version: semverSchema, version: semverSchema,
releasedAt: dateTimeSchema, releasedAt: dateTimeSchema,
urgent: z.boolean(), urgent: z.boolean(),
notes: z.string(), notes: z.string(),
/**
* contracts 1.1.0 (Hub 2.0): the sibling versions this release needs. The Hub refuses an update
* request (`409 REQUIREMENT_NOT_MET`) until the church's install of each product runs at least
* that version. Optional: absent from Hubs before 2.0 and from protocol v1 replies.
*/
requires: z.array(releaseRequirementSchema).optional(),
}); });
export const noticeSchema = z.object({ export const noticeSchema = z.object({