Merge branch 'docs/roadmap-monorepo-deploy'

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-04 14:48:36 +02:00
co-authored by Claude Opus 5.5
2 changed files with 155 additions and 26 deletions
+19 -7
View File
@@ -1,6 +1,7 @@
# Handover — where things stand and how to carry on
Last updated: 2026-11-03, after **2.1.1** (deployed) and Hub **1.7.0**. **The plan from here is
Last updated: 2026-11-04, after **2.1.1** (deployed), Hub **1.7.0** and **contracts 1.0.0**;
ROADMAP-v3 updated for the monorepo move and the `crosscode` deploy script (decisions 21–24). **The plan from here is
[ROADMAP-v3.md](./ROADMAP-v3.md)** (Accounts, Church Website, Church App, Cross Code Hub; decisions
table near the end). How Cross Events got to 2.x is in [ROADMAP-v2.md](./ROADMAP-v2.md); the round
before that in [FEATURES-ROUND-1.md](./FEATURES-ROUND-1.md).
@@ -92,13 +93,23 @@ encrypted settings unreadable or break existing installs.
1. **Roadmap v3** ([ROADMAP-v3.md](./ROADMAP-v3.md), decided 2026-11-03). Everything in
ROADMAP-v2 is done: 2.1.1 is deployed, and the marketing site (`../crosscode-site`,
crosscode.co.za, with prices) is live. Build order (§9):
- **0 — contracts 1.0.0:** `crosscode.event/1`, `crosscode.church/1`, `crosscode.identity/1`,
Hub protocol v2 (today's is v1), in the new `joshua/crosscode-platform` monorepo (`packages/contracts`).
- **0 — contracts 1.0.0: released 2026-11-04** (`../crosscode-platform`, tag `contracts@1.0.0`):
`crosscode.event/1`, `crosscode.church/1`, `crosscode.identity/1`, Hub protocol v2, generated
JSON Schema in `packages/contracts/schemas/`. Not published to Gitea's package registry, and
won't be (decision 22).
- **1 — Hub 2.0.0** (`../events-hub`): Cross Code Hub — products, one licence per product,
**one install of each product per customer**, domain per customer, bundles, sibling discovery.
- **1b — Cross Events 2.2.0:** **authenticator app 2FA** (TOTP + recovery codes) next to email
**one install of each product per customer**, domain per customer, bundles, sibling discovery,
**releases per product** (Events from `crosscode-platform` `events@…` tags, keeping the
`hope-events` `v…` releases) **with requirements** (`— requires accounts 1.2.0`, Request update
disabled until met). Contracts as `vendor/crosscode-contracts-1.0.0.tgz` (ROADMAP-v3 §2, §5).
- **1b — Cross Events 2.2.0: moves into the monorepo** as `apps/events` with its history, and the
**`crosscode` script** (`deploy <church> [events] [website] [app]` — Accounts always —,
`status`, `install`, `adopt`) replaces `scripts/deploy.sh` / `install.sh`. Run
`crosscode adopt` once per existing install; then archive this repo (ROADMAP-v3 §8,
"Releases and updates"). From here on this file and the roadmap live in the monorepo.
- **1c — Cross Events 2.3.0:** **authenticator app 2FA** (TOTP + recovery codes) next to email
and WhatsApp (`TwoFactorMethod` enum in `prisma/schema.prisma`).
- **2 — Cross Events 2.3.0:** protocol v2, Linked products, the event feed (publish and show).
- **2 — Cross Events 2.4.0:** protocol v2, Linked products, the event feed (publish and show).
- **3 — Accounts 1.0.0**, **4 — Church Website 1.0.0**, **5 — Cross Events 3.0.0** (sign-in
moves to Accounts), **6 — Church App 1.0.0** (House of Prayer).
- **Before selling the Website or App:** put the prices decided in ROADMAP-v3 §10 in
@@ -109,7 +120,8 @@ encrypted settings unreadable or break existing installs.
- Testing AI locally: run the Hub (`../events-hub`, port 5200), set Settings → AI there, give a
test licence an AI cap, and start Cross Events with `HUB_URL=http://localhost:5200`.
- **Deploying:** `bash scripts/deploy.sh --check`, then `bash scripts/deploy.sh v<version>` on
each server (installs ask through Request update as usual).
each server (installs ask through Request update as usual). From Events 2.2.0 on:
`crosscode deploy <church> events` (ROADMAP-v3 §8).
2. **AI rules** (decided 2026-10-29, roadmap §15): the AI buttons show only when the licence's
monthly cap is above R0, and are disabled (not hidden) once it's reached. The Hub charges the
real cost plus a markup % (a default and a per-licence override) and counts the cap in charged
+136 -19
View File
@@ -10,6 +10,12 @@ See [ROADMAP-v2.md](./ROADMAP-v2.md) for how Cross Events got to 2.x.
Website). People sign in to all of them with **one account**, and events flow between them in
whatever direction the church chooses.
**Updated 2026-11-04:** Cross Events moves into the `crosscode-platform` monorepo (§8), every
product is released and deployed the same way with one `crosscode` script (§8, "Releases and
updates"), the Hub tracks releases per product (§5), and the contracts reach the Hub as a file
committed to its repo instead of through a package registry (§2). Cross Events versions in §9
moved up by one (the move is 2.2.0). See decisions 21–24.
---
## Contents
@@ -88,8 +94,14 @@ same in every product's JSON.
- 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) and is published to Gitea's package registry so
the Events and Hub repos can install it.
- 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.
---
@@ -141,7 +153,7 @@ touching anyone's account.
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.2.0), and the migration carries it over (below).
(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
@@ -278,6 +290,29 @@ product's customers, licences, stats, AI usage and billing.
the Accounts client (§3). The list is cached, so a Hub outage changes nothing.
- **AI:** the existing proxy, cap and markup serve every product. Usage is recorded per product,
and the cap stays per customer.
- **Releases per product.** Each product has a release source: repo, tag pattern and notes
file. Releases carry a `product`, so "update available", **Request update** and "versions
behind" work per install.
| Product | Repo | Tags | Notes |
|---------|------|------|-------|
| Events | `crosscode-platform` | `events@2.2.0` on | `apps/events/WHATS-NEW.md` |
| Events (before the move) | `hope-events` (archived) | `v1.0.0` … `v2.1.x` | its `WHATS-NEW.md` |
| Accounts | `crosscode-platform` | `accounts@1.2.3` | `apps/accounts/WHATS-NEW.md` |
| Website | `crosscode-platform` | `website@1.2.3` | `apps/website/WHATS-NEW.md` |
| App | `crosscode-platform` | `app@1.2.3` | `apps/app/WHATS-NEW.md` |
`contracts@` tags are ignored (nobody installs them). The Events releases before the move stay
(today's sync removes releases without a tag; with two sources it only removes a release
missing from its own source).
- **Requirements between products.** A release can say what it needs, in its `WHATS-NEW.md`
heading: `## 3.0.0 — requires accounts 1.2.0` (several: `requires accounts 1.2.0, website
1.1.0`; it can be combined with `— urgent`). The Hub shows it on the install, and **Request
update stays disabled** ("Accounts must be updated to 1.2.0 first") until the church's install
of that product reports that version or later. The `crosscode` script checks the same thing
before it deploys (§8). By default products never need to update together: the contract rules
(§2) and protocol v1 + v2 make that possible, so requirements are only for real breaking moves
such as Events 3.0.
- **Request update** works for every product. The Hub still never runs anything on an install.
- **Domain:** `hub.crosscode.co.za`. `events-hub.crosscode.co.za` stays as an alias so existing
installs keep working.
@@ -410,10 +445,9 @@ browsed without an account. Personal actions need sign-in through Accounts.
- **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, …).
- **Install and update scripts** for each product, built from the Cross Events ones: fresh
install, then a tagged update with a database backup, migrations, build, restart and roll back
on failure. An `add-church` script runs them for the products a church has bought and prints
the nginx config and DNS records.
- **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).
@@ -425,24 +459,95 @@ browsed without an account. Personal actions need sign-in through Accounts.
| Repo | What |
|------|------|
| `joshua/hope-events` | Cross Events (unchanged home) |
| `joshua/events-hub` | Cross Code Hub (renamed in the UI; repo name can stay) |
| `joshua/crosscode-platform` (new) | Monorepo: `apps/accounts`, `apps/website`, `apps/app`, `packages/contracts`, `packages/ui`, `packages/seo` (§11) |
| `joshua/crosscode-platform` | **Every product a church installs**, and what they share: `apps/events` (Cross Events, moved here in 2.2.0), `apps/accounts`, `apps/website`, `apps/app`, `packages/contracts`, `packages/ui`, `packages/seo` (§11), and the `crosscode` script (`scripts/`) |
| `joshua/hope-events` | Cross Events up to 2.1.x. **Archived** after the move (read-only, README points to the monorepo), and kept so installs that haven't moved yet can still deploy or roll back a `v2.1.x` tag |
| `joshua/events-hub` | Cross Code Hub (renamed in the UI; repo name can stay). Stays on its own: it runs on its own server, is never installed for a church, and is deployed with its own `scripts/deploy.sh`. Gets the contracts as a committed file (§2) |
| `joshua/crosscode-site` | The marketing site (crosscode.co.za). Updated at the end of every phase that changes what's on sale or what a product does (see §9, "Updating crosscode-site") |
**Stack:** the same as Cross Events (Next.js, Express, TypeScript, Prisma, PostgreSQL, pg-boss,
Playwright, Jest), so code and habits carry over.
### Releases and updates
**What doesn't change:** git is how code reaches a server, the Hub only records releases and
passes on update requests (it never deploys, §1 rule 2), and Joshua runs the deploys.
**Releasing.** Each product is tagged on its own in the monorepo: `events@2.2.0`,
`accounts@1.0.0`, `website@1.0.0`, `app@1.0.0` (and `contracts@1.0.0`, which nobody installs).
Each app keeps its own `CHANGELOG.md` and church-facing `WHATS-NEW.md` in its folder. The release
routine is as today (branch → merge → tag → push), with the product's name in the tag. The Hub
picks the tags up per product (§5).
**On a server.** Each church gets a folder with a config file and one checkout of the monorepo
per product, each at that product's own tag:
```
/opt/crosscode/
tools/ the crosscode script (a checkout of main, updated before every run)
churches/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
```
A product's folder can live elsewhere (`church.env` says where), so existing installs such as
`/opt/hope-events` don't have to move, and their PM2 names, nginx names and database names stay
as they are. 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 /opt/hope-events` | Once per existing Cross Events install: moves it onto the monorepo (below) |
Before Accounts exists (until phase 3), "always Accounts" is skipped for churches that don't have
it yet.
**How a deploy runs**
1. **Checks first, for every product named; if one fails nothing is touched:** files changed by
hand in a checkout (as `deploy.sh --check` today), the Node version, and the requirements of
the target releases (§5: `events@3.0.0` needs `accounts@1.2.0`, and Accounts is either already
there or part of this deploy).
2. **In a fixed order: Accounts, then Events, Website, App.** Each product: database backup →
check out its tag → install and build its app → migrations → PM2 reload → `/health` answers
with the new version. If any step fails, **that product rolls back** to its previous tag (as
`deploy.sh` does today) and the deploy stops there.
3. Products already updated in this run stay updated (no product needs its siblings to update
with it, §5), and the summary says which ones were updated, which rolled back and which weren't
reached.
**Moving existing Cross Events installs (Events 2.2.0, `crosscode adopt`).** Once per server
install, run by Joshua. It writes `church.env` (pointing at the existing folder), changes the
checkout's remote to `crosscode-platform`, moves the install's own files to the new paths
(`backend/.env` → `apps/events/backend/.env`, likewise the frontend `.env`,
`backend/public/uploads/`, `backend/backups/`, `backend/data/*.json`, and `ecosystem.config.js`
with its `cwd` paths updated), checks out `events@2.2.0`, builds and reloads. The folder, PM2
names, nginx config (it only proxies to ports), database and its name stay the same. If anything
fails it moves the files back and returns to the `hope-events` remote and the version it was on.
Installs that haven't moved yet keep working with `deploy.sh` on the archived repo.
---
## 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, docs, sample payloads, the monorepo set up | 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 | Must exist before a second product is sold |
| 1b | **Cross Events 2.2.0** | **Authenticator app 2FA** (TOTP) next to email and WhatsApp, with recovery codes; admins can see which method each staff account uses | Independent and useful now; the Accounts migration later carries it over |
| 2 | **Cross Events 2.3.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 |
| 0 | contracts 1.0.0 | `crosscode.event/1`, `crosscode.church/1`, `crosscode.identity/1`, Hub protocol v2: schemas, generated JSON Schema, docs, sample payloads, the monorepo set up. **Released 2026-11-04** | Everything else depends on them |
| 1 | **Hub 2.0.0** | Cross Code Hub: products, licence per product, per-customer billing with bundles, protocol v2 (v1 still accepted), sibling discovery, AI usage per product, **releases per product with requirements** (§5), contracts as a committed file (§2) | Must exist before a second product is sold, and before Events releases come from the monorepo |
| 1b | **Cross Events 2.2.0** | **Moves into the monorepo** as `apps/events`, with its git history (merged in, not copied); its packages become workspaces; the **`crosscode` script** (`deploy`, `status`, `install`, `adopt`; §8) replaces `scripts/deploy.sh` and `scripts/install.sh`; every install moved with `crosscode adopt`; `hope-events` archived. No feature changes, so a problem is clearly the move | Before more products, so every product is released and deployed the same way from the start |
| 1c | **Cross Events 2.3.0** | **Authenticator app 2FA** (TOTP) next to email and WhatsApp, with recovery codes; admins can see which method each staff account uses | Independent and useful now; the Accounts migration later carries it over |
| 2 | **Cross Events 2.4.0** | Reports `product: "events"` (protocol v2), **Linked products**, the event feed (publish + show events from siblings), `packages/seo` (§11) with canonical links for imported events | Small; ready for when the Website exists |
| 3 | **Accounts 1.0.0** | OIDC provider, sign-in, 2FA (email, WhatsApp, authenticator app), password reset, consent and notice, export / delete fan-out, admin, install script | The Website is built on it from day one |
| 4 | **Church Website 1.0.0** | Public site with the **four templates** (§6), admin, simple events + feed, SEO (§11), Hope Family Church as the first church, then a second test church on a different template to prove it repeats | More churches need a website than an app; it also covers the "website only" case |
| 5 | **Cross Events 3.0.0** | Sign-in moves to Accounts; user migration keeping password hashes; migration guide | Breaking change, so a major version, after Accounts is proven on the Website |
@@ -462,8 +567,9 @@ At the end of each phase, update it in the same sitting and deploy it (its `DEPL
|-------|--------------------------------|
| 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 | Authenticator app 2FA in the Cross Events feature list (`src/data/cross-events.mjs`) and the security / POPIA wording |
| 2 Events 2.3.0 | "Works with the Church Website and App" (event feed, Linked products) on the Cross Events page, as "coming" until those ship |
| 1b Events 2.2.0 | Nothing (the move doesn't change what Cross Events does) |
| 1c Events 2.3.0 | Authenticator app 2FA in the Cross Events feature list (`src/data/cross-events.mjs`) and the security / POPIA wording |
| 2 Events 2.4.0 | "Works with the Church Website and App" (event feed, Linked products) on the Cross Events page, as "coming" until those ship |
| 3 Accounts 1.0.0 | "One sign-in for all your church's products" on the Products page. Accounts isn't sold, so no page or price of its own |
| 4 Website 1.0.0 | **Church Website goes on sale:** `status: "available"` and its own page in `src/data/products.mjs` / `src/pages/products/`, R99 + storage add-on in `pricing.mjs`, **a showcase of the four templates** (a page per template with screenshots of the same demo church in each), screenshots from a demo church (fictional people only), FAQ, home page, contact form product list, `SoftwareApplication` JSON-LD (§11) |
| 5 Events 3.0.0 | Cross Events page: sign-in through the church's shared account. Update screenshots that show the login |
@@ -475,7 +581,9 @@ 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 separate databases, secrets and uploads.
- 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.
@@ -579,7 +687,7 @@ me", its name, or an event it's running.
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.3.0.
`eventSchema.ts` onto it in 2.4.0.
### Per product
@@ -627,13 +735,22 @@ ranking.
| 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.2.0 first, then in Accounts |
| 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: `crosscode deploy <church> [events] [website] [app]` always updates Accounts and then the products named, in a fixed order, each rolled back on its own if it fails. Still git checkouts of tags, still run by Joshua; the Hub never deploys (§8) |
| 24 | Product requirements | A release can require a minimum version of a sibling (`— requires accounts 1.2.0` in `WHATS-NEW.md`). The Hub **disables Request update** until it's met, and the script refuses to deploy without it (§5, §8) |
## Still open
Nothing. crosscode-site is updated at the end of each phase (§9, "Updating crosscode-site"); the