Compare commits
8
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
c398e8071d | ||
|
|
934f7a9eed | ||
|
|
4e58c5c07e | ||
|
|
8032a5d9e2 | ||
|
|
633d65eec9 | ||
|
|
d62a652be2 | ||
|
|
11e28502ea | ||
|
|
66b0c9789b |
@@ -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
|
||||||
|
|||||||
@@ -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)
|
||||||
|
|
||||||
|
|||||||
@@ -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.
|
||||||
@@ -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.)
|
||||||
@@ -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.
|
||||||
@@ -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.
|
||||||
@@ -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
@@ -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,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": [
|
||||||
|
|||||||
@@ -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({
|
||||||
|
|||||||
Reference in New Issue
Block a user