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

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 16:26:51 +02:00

59 KiB
Raw Permalink Blame History

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). 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.

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.

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). 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
  2. Contracts (shared JSON formats)
  3. Accounts (shared users)
  4. Event sync in any direction
  5. Cross Code Hub (all products)
  6. Church Website
  7. Church App
  8. Servers and deployment
  9. Build order
  10. Pricing
  11. SEO (every public site)
  12. Decisions
  13. 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

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

{
  "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).

  • 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 §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 cwds 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. 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 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)

# 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.