joshua/hope-events
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Roadmap v3: Hub protocol v2 (today's is v1), event-feed schema, enum rule

Browse Source 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
joshua
2026-11-04 09:47:42 +02:00
co-authored by Claude Opus 5.5
parent 78bf6df40c
commit f85842d4b3
2 changed files with 11 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/HANDOVER.md
+2 -2
View File
@@ -93,12 +93,12 @@ encrypted settings unreadable or break existing installs.
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 v3, in the new `joshua/crosscode-platform` monorepo (`packages/contracts`).
Hub protocol v2 (today's is v1), in the new `joshua/crosscode-platform` monorepo (`packages/contracts`).
- **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
and WhatsApp (`TwoFactorMethod` enum in `prisma/schema.prisma`).
- **2 — Cross Events 2.3.0:** protocol v3, Linked products, the event feed (publish and show).
- **2 — Cross Events 2.3.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
docs/ROADMAP-v3.md
+9 -9
View File
@@ -76,15 +76,15 @@ same in every product's JSON.
| Contract | Used for |
|----------|----------|
| `crosscode.event/1` | The event feed every product publishes and reads (§4) |
| `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 v3 | Register, heartbeat, licence token, AI calls, for every product (§5) |
| Hub protocol v2 | Register, heartbeat, licence token, AI calls, for every product (§5). Today's protocol (Cross Events 2.1, Hub 1.7) is v1, in `docs/hub-protocol.md` |
**Versioning**
- Adding an **optional** field keeps the version (`/1`). Consumers ignore fields they don't know.
- Removing or renaming a field, or changing its meaning, needs a new version (`/2`). The old
- 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
@@ -192,7 +192,7 @@ everything; or nothing.
### Transport
- `GET /api/feed/v1/events?updatedSince=<ISO>` → `{ schema, generatedAt, events: [...], deleted: [...] }`.
- `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).
@@ -268,8 +268,8 @@ product's customers, licences, stats, AI usage and billing.
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 v3:** adds `product` to register and heartbeat, and per-product stats (aggregate
counts only, as today: no personal information). The Hub keeps accepting protocol v2, so Events
- **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
@@ -399,10 +399,10 @@ Playwright, Jest), so code and habits carry over.
| Phase | Version | What | Why this order |
|-------|---------|------|----------------|
| 0 | contracts 1.0.0 | `crosscode.event/1`, `crosscode.church/1`, `crosscode.identity/1`, Hub protocol v3: 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 v3 (v2 still accepted), sibling discovery, AI usage per product | Must exist before a second product is sold |
| 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 v3), **Linked products**, the event feed (publish + show events from siblings) | Small; ready for when the Website exists |
| 2 | **Cross Events 2.3.0** | Reports `product: "events"` (protocol v2), **Linked products**, the event feed (publish + show events from siblings) | 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, admin, simple events + feed, Hope Family Church as the first church, then a second test church 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 |