diff --git a/docs/HANDOVER.md b/docs/HANDOVER.md index 8d46bb3..1e73b93 100644 --- a/docs/HANDOVER.md +++ b/docs/HANDOVER.md @@ -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 diff --git a/docs/ROADMAP-v3.md b/docs/ROADMAP-v3.md index 435adcf..a42571d 100644 --- a/docs/ROADMAP-v3.md +++ b/docs/ROADMAP-v3.md @@ -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=` → `{ schema, generatedAt, events: [...], deleted: [...] }`. +- `GET /api/feed/v1/events?updatedSince=` → `{ 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 |