Compare commits
9
Commits
docs/hub-2.10.0
...
main
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
4cc30c1445 | ||
|
|
d91d956e78 | ||
|
|
9f07ecf0dd | ||
|
|
74df4aa7b5 | ||
|
|
72a6283024 | ||
|
|
86711699cf | ||
|
|
d28029e96e | ||
|
|
e65e26202a | ||
|
|
ca55142f6f |
@@ -2,6 +2,13 @@
|
||||
|
||||
Each package and app has its own section and its own tags (`contracts@1.0.0`, `accounts@1.0.0`, …).
|
||||
|
||||
## crosscode script - 2026-11-20 (no tag: servers run `main`)
|
||||
|
||||
- **Fix:** the database dump made before each Accounts deploy (`apps/accounts/backend/backups/`)
|
||||
counted as a file added by hand on Accounts below 1.3.0 (no `.gitignore` for it yet), so the
|
||||
next deploy stopped with "changed or added by hand". Untracked files in that folder no longer
|
||||
count (`CROSSCODE_OWN_DIRS` in `lib/common.sh`).
|
||||
|
||||
## events@3.6.1 - 2026-11-20
|
||||
|
||||
- **Events 3.6.1 (fix):** uploading a logo or favicon failed with "uploaded, but the site can't
|
||||
|
||||
@@ -1,3 +1,3 @@
|
||||
# Church Website
|
||||
|
||||
Placeholder: the church's public website and its admin. Built in phase 4 of ROADMAP-v3 (see §6 there).
|
||||
Placeholder: the church's public website and its admin. Built in phase 5 of ROADMAP-v3 (see §6 there).
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
"name": "@crosscode/website",
|
||||
"version": "0.0.0",
|
||||
"private": true,
|
||||
"description": "Placeholder: Church Website, built in phase 4 (ROADMAP-v3 §6)"
|
||||
"description": "Placeholder: Church Website, built in phase 5 (ROADMAP-v3 §6)"
|
||||
}
|
||||
|
||||
@@ -354,6 +354,7 @@ Confirmed by Joshua on 2026-11-18 (1, 4, 5 and 6 asked directly; the rest as pro
|
||||
## Still open
|
||||
|
||||
- Whether the Website's admin edits the church profile through Accounts' API (as proposed in §7)
|
||||
or Accounts' own screen is the only place. Decide with the Website plan (phase 5).
|
||||
or Accounts' own screen is the only place. Decide with the Website plan (phase 5). **Decided 2026-11-21 (WEBSITE-1.0-PLAN decision 10):**
|
||||
through Accounts' API, live at once.
|
||||
- Session lengths (30 days with "Keep me signed in") are a starting point; check them with Joshua
|
||||
before release.
|
||||
|
||||
+21
-32
@@ -1,6 +1,6 @@
|
||||
# Handover — Cross Code, all products
|
||||
|
||||
Last updated: 2026-11-20. **The plan is [ROADMAP-v3.md](./ROADMAP-v3.md)** (decided 2026-11-03,
|
||||
Last updated: 2026-11-21. **The plan is [ROADMAP-v3.md](./ROADMAP-v3.md)** (decided 2026-11-03,
|
||||
decisions table near the end). This file says where each phase stands and what comes next.
|
||||
Product-specific notes (where the code lives, known gaps) stay with each product: Cross Events'
|
||||
are in [`apps/events/docs/HANDOVER.md`](../apps/events/docs/HANDOVER.md), and the Hub's are in
|
||||
@@ -25,20 +25,21 @@ every release).
|
||||
|
||||
| Phase | What | State |
|
||||
|-------|------|-------|
|
||||
| 0 | contracts 1.0.0 / 1.1.0 | **Released** 2026-11-04. Not published to a registry (decision 22): the Hub gets a packed release committed to its repo (`backend/vendor/`) |
|
||||
| 1 | Hub 2.0.x | **Released** (`v2.0.0` 2026-11-05, `v2.0.1` AI tokens and `v2.0.2` refunds / voiding refunded invoices, 2026-11-17). **Not deployed yet:** `events-hub/deployment.md` → "Upgrading to 2.0" (run `check-hub2` first). Deploy straight to the latest 2.1.x (below) |
|
||||
| 1b | Cross Events 2.2.0: moved here as `apps/events`, the `crosscode` script | **Released** 2026-11-17 (`events@2.2.0`, with AI use in tokens and the backend under `/api`). **VM tested 2026-11-17** (EVENTS-2.2-PLAN §6, all passing after fixes). **Not rolled out:** servers still run `hope-events` `v2.1.1` until each install is adopted |
|
||||
| 1c | Cross Events 2.3.x: authenticator app 2FA (TOTP + recovery codes) | **Released** 2026-11-17 (`events@2.3.0`). **`events@2.3.1`** 2026-11-18: Next.js 16.4.6 (security advisories for 16.2.0–16.4.4), so roll out 2.3.1, not 2.3.0. crosscode-site `v1.3.0` lists it (merged and tagged, **not deployed**) |
|
||||
| 1d | Agent 1.0.x + Hub 2.1.x (+ contracts 1.3.0) | **Released** 2026-11-17 (`agent@1.0.0`, `contracts@1.3.0`, Hub `v2.1.0`). **VM tested** end to end (AGENT-1.0-PLAN §13: joins, installs behind frp, scheduled / batch / missed updates, uninstall with export and purge, forged and replayed jobs). 2026-11-18: **`agent@1.0.1`** (the agent answers status on the central server itself) and Hub **`v2.1.1`** (adopt passes the church's address; Link takes the short name as a name). **Not rolled out**: use agent 1.0.1 and Hub 2.1.1 |
|
||||
| 2 | Cross Events 2.4.0: protocol v2, Linked products, event feed, `packages/seo` (+ contracts 1.4.0, Hub 2.2.0) | **Released** 2026-11-18 (`events@2.4.0`, `contracts@1.4.0`, Hub `v2.2.0`, crosscode-site `v1.4.0`; [EVENTS-2.4-PLAN.md](./EVENTS-2.4-PLAN.md)). **Before any church gets it:** the Events e2e run on Postgres and the VM test (EVENTS-2.4-PLAN §8) |
|
||||
| 3 | Accounts 1.0.0 (+ contracts 1.5.0, agent 1.1.0, Hub 2.3.0) | **Released** 2026-11-18 (`accounts@1.0.0`, `contracts@1.5.0`, `agent@1.1.0`, Hub `v2.3.0`, crosscode-site `v1.5.0`; [ACCOUNTS-1.0-PLAN.md](./ACCOUNTS-1.0-PLAN.md)). 37 backend and 8 Playwright tests pass without Postgres. **Before installing it for a church:** the VM test and a run on real Postgres; a Hub release source for `accounts@` tags |
|
||||
| 4 | Cross Events 3.0.0: sign-in through Accounts, users migrated with their password hashes and 2FA | **Released** 2026-11-19 (`events@3.0.0`, `accounts@1.1.0`, `contracts@1.8.0`, Hub `v2.5.0`, crosscode-site `v1.6.0`; [EVENTS-3.0-PLAN.md](./EVENTS-3.0-PLAN.md)). Tested on Postgres 18: both migrations, `test:accounts` on real databases (14/14), the Events e2e suite (111, incl. `sign-in-accounts.spec.ts`). **Not VM tested yet.** Roll out: Hub 2.5.0 deployed first, then per church Accounts 1.1.0 → Events 3.0 → Move (MIGRATING-TO-3.md); crosscode-site 1.6.0 once the first church has moved |
|
||||
| 4+ | Running it: jobs from the dashboard, styled Accounts emails, .env from the Hub, sign-in health, the nightly people check | **Released** 2026-11-20 (see below). Unit, bats and full `npm run check` passing; **not VM tested, not deployed** |
|
||||
| 5–7 | Website 1.0.0 → App 1.0.0 → App 1.x | Not started |
|
||||
| 0 | contracts 1.0.0 → 1.14.0 | **Released and in use.** Not published to a registry (decision 22): the Hub gets a packed release committed to its repo (`backend/vendor/`) |
|
||||
| 1 | Hub 2.0 → 2.10.0 | **Released, deployed and tested** (Hub `v2.10.0`) |
|
||||
| 1b | Cross Events 2.2.0: moved here as `apps/events`, the `crosscode` script | **Released, rolled out and tested.** Every install adopted onto the monorepo |
|
||||
| 1c | Cross Events 2.3.x: authenticator app 2FA | **Released and rolled out** (carried into Accounts in phase 4) |
|
||||
| 1d | Agent 1.x + Hub 2.1+ | **Released, rolled out and tested** (agent `1.3.1` on every server; the central server's agent is read-only) |
|
||||
| 2 | Cross Events 2.4.0: protocol v2, Linked products, event feed, `packages/seo` | **Released, rolled out and tested** ([EVENTS-2.4-PLAN.md](./EVENTS-2.4-PLAN.md)) |
|
||||
| 3 | Accounts 1.0.0 | **Released, rolled out and tested** (now `accounts@1.6.0`; [ACCOUNTS-1.0-PLAN.md](./ACCOUNTS-1.0-PLAN.md)) |
|
||||
| 4 | Cross Events 3.0.0: sign-in through Accounts | **Released, rolled out and tested** (now `events@3.6.1`; [EVENTS-3.0-PLAN.md](./EVENTS-3.0-PLAN.md)). Churches sign in through their Accounts; crosscode-site `v1.6.0` deployed |
|
||||
| 4+ | Running it: jobs from the dashboard, styled emails, .env from the Hub, sign-in health, the nightly people check | **Released, deployed and tested** 2026-11-20 (below) |
|
||||
| 5 | Church Website 1.0.0 | **Planned** 2026-11-21: [WEBSITE-1.0-PLAN.md](./WEBSITE-1.0-PLAN.md) (all decisions confirmed). Not started |
|
||||
| 6–7 | App 1.0.0 → App 1.x | Not started |
|
||||
|
||||
## Released 2026-11-20
|
||||
|
||||
All tagged and pushed; nothing deployed yet. Details in [CHANGELOG.md](../CHANGELOG.md), the apps' CHANGELOGs
|
||||
All tagged, pushed, deployed and tested (confirmed by Joshua 2026-11-21). Details in [CHANGELOG.md](../CHANGELOG.md), the apps' CHANGELOGs
|
||||
and What's New, and [VERSIONS.md](./VERSIONS.md).
|
||||
|
||||
| Release | What |
|
||||
@@ -50,9 +51,6 @@ and What's New, and [VERSIONS.md](./VERSIONS.md).
|
||||
| `events@3.6.1` | **Fix:** logo/favicon uploads failed on events-demo ("uploaded, but the site can't show it yet"). FastPanel's static-file rule sent every `/api/…` path with a file extension (`.png`, `.pdf`, …) to the frontend. The site now passes `/api/*` and `/uploads/*` on to the backend (`BACKEND_INTERNAL_URL`); the installers' nginx uses `location ^~`. Change each FastPanel site too (below) |
|
||||
| `events@3.6.0`, `accounts@1.5.0`, `contracts@1.14.0` | The nightly people check (`accounts-people-check`, 04:30): `people.check` 500 subs at a time; fixes out-of-date copies, handles deleted accounts as `user.deleted`, stops (changing nothing) when most people are unknown. Skipped with an Accounts before 1.5.0 |
|
||||
|
||||
**To fix events-demo before it's updated:** its Settings → Linked products → Connect the church's
|
||||
Accounts (or update it to Events 3.5.0+, which reconnects within ~15 minutes).
|
||||
|
||||
## FastPanel sites (central server)
|
||||
|
||||
FastPanel's nginx on the central server is the only router for sites behind frp: the church
|
||||
@@ -82,24 +80,15 @@ before that need the change by hand, and so does the Hub's own site (`events-hub
|
||||
|
||||
## Next up
|
||||
|
||||
Nothing from phase 1 onwards is rolled out yet (VERSIONS.md, "Deployed / rolled out"), so roll out
|
||||
straight to the latest releases rather than each one in turn.
|
||||
Everything up to and including the 2026-11-20 releases is deployed, rolled out and tested
|
||||
(VERSIONS.md, "Deployed / rolled out").
|
||||
|
||||
1. **VM test the latest releases** before any church gets them (the 2026-11-17 VM test covered
|
||||
Events 2.2 and agent 1.0; Events 2.4+, Accounts and Events 3.x haven't been on it): Events 3.x
|
||||
with Accounts and the move (MIGRATING-TO-3.md), the event feed and Linked products
|
||||
(EVENTS-2.4-PLAN §8), and today's: the Hub's .env panel (read; a backend URL with restart; a
|
||||
frontend value with rebuild; a value that stops the site, so it's put back), the job switches,
|
||||
a demo load (the Accounts link stays) and the people check. Also the Events e2e suite on Postgres.
|
||||
2. **Roll out**, in the order in [ROLLOUT-1.0.md](./ROLLOUT-1.0.md), with the latest releases:
|
||||
**Hub 2.10.0** (make and back up the job-signing key first; 2.4.0 onwards have migrations) → the
|
||||
central server's agent (check `proxy_bind_addr = 127.0.0.1`) → each church server's agent
|
||||
(**1.3.1**, never 1.3.0) → **adopt** the demo site, then each church (Link existing → Move onto the
|
||||
monorepo) → per church **Accounts 1.5.0 before Events 3.6.0**, then the move to Accounts
|
||||
(MIGRATING-TO-3.md) → a throwaway New install to prove FASTPANEL, DNS and Let's Encrypt.
|
||||
3. **Deploy crosscode-site.** `v1.3.0`–`v1.5.0` are tagged but not recorded as deployed;
|
||||
`v1.6.0` (one sign-in through Accounts) once the first church has moved.
|
||||
4. **Archive `hope-events`** once every install reports 2.2.0 or later (EVENTS-2.2-PLAN §7).
|
||||
1. **Phase 5, Church Website 1.0.0** (ROADMAP §6, §9). Planned in
|
||||
[WEBSITE-1.0-PLAN.md](./WEBSITE-1.0-PLAN.md): decisions all confirmed 2026-11-21. Order:
|
||||
contracts 1.15.0 → Accounts 1.7.0 → Events 3.7.0 (shared fonts and footer) → Hub 2.11.0 →
|
||||
`website@1.0.0` → Hope Family Church → a second church → crosscode-site 1.7.0.
|
||||
2. **Archive `hope-events`** if it isn't yet (every install now reports 2.2.0 or later;
|
||||
EVENTS-2.2-PLAN §7).
|
||||
|
||||
## The VM test (2026-11-17)
|
||||
|
||||
|
||||
+40
-8
@@ -29,6 +29,12 @@ change decisions 10 and 23.
|
||||
**Updated 2026-11-19:** phases 4 and 5 swapped: **Cross Events 3.0.0** (sign-in through Accounts)
|
||||
comes before the **Church Website** (§9, decision 38).
|
||||
|
||||
**Updated 2026-11-21:** the Church Website (phase 5) is planned in
|
||||
[WEBSITE-1.0-PLAN.md](./WEBSITE-1.0-PLAN.md): more room to customise each template, one Publish for
|
||||
the whole site after a clickable preview, Coming soon until then, a brand style and footer shared
|
||||
with Cross Events (3.7), and no address moves or redirects in 1.0 (§6, §9, §10, §11; decisions
|
||||
40–48).
|
||||
|
||||
---
|
||||
|
||||
## Contents
|
||||
@@ -398,6 +404,11 @@ picks one; its **logo and colours come from the church profile** (`crosscode.chu
|
||||
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.
|
||||
- **Room to make it their own** (decision 40): every section type comes in two or three
|
||||
**variants** (e.g. the hero as photo, video, collage, split or text only), **style settings**
|
||||
(font pairing, corners, section colour, spacing, buttons, image treatment, header) and **custom
|
||||
pages** built from blocks. No free layout or custom CSS. The font pairing and corners are part of
|
||||
the church's shared brand style (decision 47). Details in WEBSITE-1.0-PLAN §3.
|
||||
|
||||
### Admin (`www.church.co.za/admin`, signed in through Accounts)
|
||||
|
||||
@@ -407,13 +418,18 @@ picks one; its **logo and colours come from the church profile** (`crosscode.chu
|
||||
- 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.
|
||||
- **Draft → preview → publish** (decision 41): every change is a draft; the preview is the whole
|
||||
site, fully clickable, at phone / tablet / desktop width, and can be shared by link; **one
|
||||
Publish** puts every change live; every published version is kept and can be restored. Until the
|
||||
first publish the site shows **Coming soon** (decision 42). 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.
|
||||
Prayer requests and other forms with personal information (they belong in the App; the Contact
|
||||
page is contact details only, decision 43), a member directory, online giving processing, moving
|
||||
to the church's own domain with redirects (decision 45).
|
||||
|
||||
---
|
||||
|
||||
@@ -625,7 +641,7 @@ Planned in [AGENT-1.0-PLAN.md](./AGENT-1.0-PLAN.md). In short:
|
||||
| 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. **Planned and built 2026-11-18:** [EVENTS-2.4-PLAN.md](./EVENTS-2.4-PLAN.md) (also needs contracts 1.4.0 and Hub 2.2.0, for a public key in the v2 heartbeat); not tagged yet | 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. [ACCOUNTS-1.0-PLAN.md](./ACCOUNTS-1.0-PLAN.md) (with contracts 1.5.0, `packages/auth-client`, Hub 2.3.0). **Released 2026-11-18** (`accounts@1.0.0`, 1.0.1 on 2026-11-19); the VM test and a run on real Postgres are still to do before a church gets it | Every later product signs in through it |
|
||||
| 4 | **Cross Events 3.0.0** | Sign-in moves to Accounts; user migration keeping password hashes; migration guide. **Planned 2026-11-19:** [EVENTS-3.0-PLAN.md](./EVENTS-3.0-PLAN.md) (with contracts 1.8.0, Accounts 1.1.0, Hub 2.5.0; decisions confirmed 2026-11-19) | Breaking change, so a major version. **Moved before the Website on 2026-11-19** (decision 38): Events is the product churches use today, so Accounts is proven on real users first, and the Website then starts with a church whose people already have accounts |
|
||||
| 5 | **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. Built on Accounts from day one |
|
||||
| 5 | **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. **Planned 2026-11-21:** [WEBSITE-1.0-PLAN.md](./WEBSITE-1.0-PLAN.md) (with contracts 1.15.0, Accounts 1.7.0, Events 3.7.0 for the shared fonts and footer, Hub 2.11.0) | More churches need a website than an app; it also covers the "website only" case. Built on Accounts from day one |
|
||||
| 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 |
|
||||
|
||||
@@ -695,7 +711,7 @@ 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 |
|
||||
| **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 (old addresses redirect for 12 months; not before Website 1.0, decision 45). 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
|
||||
@@ -709,7 +725,8 @@ charged **once per church**, not per product.
|
||||
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 and reported to the Hub, which bills the add-on. **When it's full, uploads stop** until more
|
||||
is bought (decision 48); what's already uploaded keeps showing.
|
||||
|
||||
### Church App: on active members
|
||||
|
||||
@@ -783,7 +800,8 @@ data from the same `crosscode.event/1` and `crosscode.church/1`. Cross Events mo
|
||||
|
||||
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.
|
||||
ranking. **Not in Website 1.0** (decision 45): moving addresses, with a Hub job for all of a
|
||||
church's products, comes in a later release.
|
||||
|
||||
### Checks (in every product's tests)
|
||||
|
||||
@@ -859,7 +877,21 @@ ranking.
|
||||
| 38 | Order after Accounts | **Cross Events 3.0.0 (sign-in through Accounts) is phase 4, the Church Website phase 5** (swapped). Events is what churches use today, so Accounts is proven on real users and their migrated passwords and 2FA first; the Website then starts with a church whose people already have accounts |
|
||||
| 39 | Emergency updates now | An emergency update (reason and 2FA, as before) can run **as soon as possible**, at the agent's next poll (within a minute), as well as at a time at least 15 minutes away. The church is told it's happening now. When the church's Events heartbeat shows an event on now (a session or a one-day event, or check-ins in the last hour), the Hub names it and needs a second "yes". Hub 2.7.0, Events 3.2.0 |
|
||||
|
||||
**Added 2026-11-21** (phase 5, [WEBSITE-1.0-PLAN.md](./WEBSITE-1.0-PLAN.md))
|
||||
|
||||
| # | Question | Decision |
|
||||
|---|----------|----------|
|
||||
| 40 | Enough customisation | Keep **four templates**, each with **section variants**, **style settings** and **custom pages from blocks**, within limits that keep every site designed, accessible and fast. No free layout, custom CSS or custom fonts. More templates can come in 1.x, but not instead of this |
|
||||
| 41 | Publishing | Every change is a draft. A **fully clickable preview** of the whole site (shareable by a 7-day link) and **one Publish for the whole site**; any pending change can be discarded; every published version is kept and can be restored |
|
||||
| 42 | Before the first publish | The public address shows a **Coming soon** page from the church profile (logo, service times, contact, links to Events), `noindex` |
|
||||
| 43 | Contact page | **Contact details only**, no form |
|
||||
| 44 | Shared vs Website-only content | The church profile (`crosscode.church/1`) gains the **brand style** (font pairing, corners). Leaders, ministries, About, giving and messages are **Website-only for now**; the App plan decides whether they move into the profile |
|
||||
| 45 | Moving to the church's own domain | **Not in Website 1.0**, and no Hub "Change address" job yet (§10, §11 "Moving addresses") |
|
||||
| 46 | Messages | **From a YouTube channel or playlist automatically** (latest video as the latest message), or **by hand** with a YouTube or Spotify link |
|
||||
| 47 | Feeling like one church | The **brand style and footer are shared**: the Website, Accounts' pages and **Cross Events 3.7**'s public pages use the church's fonts, corners and one `ChurchFooter`, with links between the products |
|
||||
| 48 | Full storage | Admins are emailed at 80% and 100%; at 100% **uploads stop** until more storage is bought (Get more storage asks the Hub; the new limit arrives with the licence) |
|
||||
|
||||
## Still open
|
||||
|
||||
Nothing. crosscode-site is updated at the end of each phase (§9, "Updating crosscode-site"); the
|
||||
Nothing for the roadmap. WEBSITE-1.0-PLAN lists its own proposals still to confirm. 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.
|
||||
|
||||
+12
-8
@@ -1,6 +1,6 @@
|
||||
# Versions — the latest release of everything
|
||||
|
||||
Last updated: 2026-11-20. Taken from the git tags, which is what a release is here (branch → merge →
|
||||
Last updated: 2026-11-21. Taken from the git tags, which is what a release is here (branch → merge →
|
||||
tag → push, see [HANDOVER.md](./HANDOVER.md) "Releasing"). **Update this file with every release.**
|
||||
|
||||
"Released" means tagged and pushed. Whether a release is **deployed** or rolled out is recorded
|
||||
@@ -16,7 +16,7 @@ separately below; the two often differ.
|
||||
| Contracts | `crosscode-platform` (`packages/contracts`) | **1.14.0** | `contracts@1.14.0` | 2026-11-20 |
|
||||
| Cross Code Hub | `events-hub` | **2.10.0** | `v2.10.0` | 2026-11-20 |
|
||||
| crosscode.co.za | `crosscode-site` | **1.6.0** | `v1.6.0` | 2026-11-19 |
|
||||
| `crosscode` script | `crosscode-platform` (`scripts/`) | `main` | none | 2026-11-20 (last change: nginx `location ^~ /api/`) |
|
||||
| `crosscode` script | `crosscode-platform` (`scripts/`) | `main` | none | 2026-11-20 (last change: Accounts' pre-deploy dumps don't stop a deploy) |
|
||||
|
||||
The `crosscode` script has no version: every server's copy (`/opt/crosscode/tools`) pulls `main`
|
||||
on each run, so merging to `main` and pushing releases it. Its changes are listed in
|
||||
@@ -29,7 +29,7 @@ on each run, so merging to `main` and pushing releases it. Its changes are liste
|
||||
| `@crosscode/auth-client` | `packages/auth-client` | 1.1.0 (released with Events 3.0.0 and Accounts 1.1.0) |
|
||||
| `@crosscode/seo` | `packages/seo` | 1.0.0 (released with Events 2.4.0) |
|
||||
| `@crosscode/ui` | `packages/ui` | 0.1.0 |
|
||||
| Website | `apps/website` | 0.0.0 (not started, phase 5) |
|
||||
| Website | `apps/website` | 0.0.0 (phase 5, being planned) |
|
||||
| App | `apps/app` | 0.0.0 (not started, phase 6) |
|
||||
|
||||
These shared packages ship inside the apps that use them, from the same checkout, so they don't
|
||||
@@ -37,6 +37,9 @@ need their own tags until something outside this repo depends on them.
|
||||
|
||||
## What each latest release was for
|
||||
|
||||
- **`crosscode` script (2026-11-20, later):** the database dump made before each Accounts deploy
|
||||
(`backend/backups/`) no longer stops the next deploy as "added by hand" on Accounts below 1.3.0.
|
||||
Released by pushing `main`; the next Hub job pulls it.
|
||||
- **Hub 2.10.0:** every Hub email (job reports, alerts, emails to church admins, notices) laid out
|
||||
as Events' and Accounts' are. The FastPanel email gives `location ^~ /api/` to paste, and Proxy
|
||||
done refuses a site whose `/api` files reach the frontend. No migration.
|
||||
@@ -136,8 +139,9 @@ you deploy one.
|
||||
|
||||
| What | Running | Since | Notes |
|
||||
|------|---------|-------|-------|
|
||||
| Hub | 2.x (exact version not recorded) | | It runs agent jobs (installs on church-server1, 2026-11-18), so it's past 2.1. **2.4.0 not deployed yet** (it has a migration) |
|
||||
| Agent on church-server1 | not recorded | | |
|
||||
| Agent on the central server | not recorded | | |
|
||||
| Cross Events (churches) | not recorded | | `hope-events` and `cross-events-demo` heartbeat as 2.1.1 and 2.3.1 |
|
||||
| crosscode.co.za | not recorded | | Handover: `v1.3.0` was merged and tagged but not deployed |
|
||||
| Hub | 2.10.0 | 2026-11-20 | |
|
||||
| Agent on church-server1 | 1.3.1 | 2026-11-20 | |
|
||||
| Agent on the central server | 1.3.1 | 2026-11-20 | Read-only (decision 35) |
|
||||
| Cross Events (churches) | 3.6.1 | 2026-11-20 | Every install adopted onto the monorepo and signing in through Accounts |
|
||||
| Accounts (churches) | 1.6.0 | 2026-11-20 | |
|
||||
| crosscode.co.za | 1.6.0 | 2026-11-20 | |
|
||||
|
||||
@@ -0,0 +1,399 @@
|
||||
# Church Website 1.0.0 — the church's own public site
|
||||
|
||||
Phase **5** of [ROADMAP-v3.md](./ROADMAP-v3.md) (§6, §9, §10, §11; decisions 19, 20, 40–47).
|
||||
Written 2026-11-21. **All decisions confirmed by Joshua on 2026-11-21** (12 changed: a full
|
||||
storage stops uploads). Not started.
|
||||
|
||||
**What the Website is:** the church's public site at `www.<church's address>` (or
|
||||
`<church>.crosscode.co.za` on the Cross Code address), plus its admin at `/admin`. Admins sign in
|
||||
through the church's Accounts. The church picks one of **four templates** and makes it its own with
|
||||
section layouts, style settings and its own pages. Changes are drafts until an admin **previews**
|
||||
the whole site and presses **Publish**. Until the first publish, visitors see a **Coming soon**
|
||||
page. The Website, Cross Events and (later) the App share the church's **brand style** (colours,
|
||||
logo, fonts, corners) and **footer**, so the three feel like one church.
|
||||
|
||||
**Who uses 1.0:** Hope Family Church first, then a second test church on a different template, to
|
||||
prove it repeats. Then it goes on sale (crosscode-site, ROADMAP §9).
|
||||
|
||||
**Done when:**
|
||||
|
||||
- `website@1.0.0`, `contracts@1.15.0`, `accounts@1.7.0`, `events@3.7.0` and Hub `v2.11.0` are
|
||||
tagged; the Hub installs the Website from New install (after Accounts) and lists its releases.
|
||||
- All four templates pass the same checks (§13) at phone, tablet and desktop sizes: layout, axe, the
|
||||
§11 SEO checks, and Lighthouse (SEO 100, accessibility 95+, performance 90+).
|
||||
- An editor can change anything, preview the whole site as a visitor would, share the preview, and
|
||||
publish it all at once. An earlier version can be restored.
|
||||
- Switching template keeps all content, and the preview shows the switch before it goes live.
|
||||
- Cross Events' public pages use the church's fonts and the shared footer.
|
||||
- Hope Family Church and a second church are live on different templates.
|
||||
- crosscode-site sells it (ROADMAP §9, "Updating crosscode-site").
|
||||
|
||||
## Contents
|
||||
|
||||
1. [The shape](#1-the-shape)
|
||||
2. [Content: shared and Website-only](#2-content-shared-and-website-only)
|
||||
3. [Templates and customisation](#3-templates-and-customisation)
|
||||
4. [Drafts, preview and publish](#4-drafts-preview-and-publish)
|
||||
5. [Coming soon](#5-coming-soon)
|
||||
6. [Pages](#6-pages)
|
||||
7. [Messages](#7-messages)
|
||||
8. [Events](#8-events)
|
||||
9. [Connected with Events and the App](#9-connected-with-events-and-the-app)
|
||||
10. [Admin, roles and storage](#10-admin-roles-and-storage)
|
||||
11. [Hub, licence and servers](#11-hub-licence-and-servers)
|
||||
12. [What changes in each repo](#12-what-changes-in-each-repo)
|
||||
13. [Testing](#13-testing)
|
||||
14. [Releasing and rolling it out](#14-releasing-and-rolling-it-out)
|
||||
15. [Decisions](#decisions)
|
||||
16. [Still open](#still-open)
|
||||
|
||||
## 1. The shape
|
||||
|
||||
`apps/website`, the same stack as Events and Accounts (decision 8 in the roadmap): an **Express +
|
||||
Prisma + pg-boss backend** (TypeScript) and a **Next.js frontend**, one PostgreSQL database, served
|
||||
on one address with `/api` to the backend (`location ^~ /api/` in FastPanel, HANDOVER "FastPanel
|
||||
sites").
|
||||
|
||||
```
|
||||
visitor ─► www.hopefamily.co.za ─► Next.js (server-rendered from the published version, cached)
|
||||
│ template + section variants + style → HTML
|
||||
editor ──► /admin (signed in through Accounts, @crosscode/auth-client)
|
||||
edits the working copy ─► /admin/preview: the whole site from the working copy
|
||||
Publish ─► a new SiteVersion (snapshot) ─► public pages revalidated
|
||||
|
||||
backend: content API (/api/v1/admin/…), public API (/api/v1/site/…), uploads (/api/uploads/…),
|
||||
event feed (/api/links/v1/*, as Events 2.4), Hub client (protocol v2, product "website"),
|
||||
jobs (YouTube feed, storage count, sitemap, feed sync)
|
||||
|
||||
Accounts ── crosscode.church/1 (name, logo, colours, service times, contact, social, brand style)
|
||||
Events ──── crosscode.event/1 (the event feed, both directions)
|
||||
```
|
||||
|
||||
- **Rendering:** public pages are server components rendered from the **latest published
|
||||
version** and cached; Publish revalidates them. Preview renders the same components from the
|
||||
**working copy**, uncached. Visitors and the preview run the same code, so the preview is exactly
|
||||
what will go live.
|
||||
- **Shared packages:** `@crosscode/ui` (branded shell, footer, fonts, form fields, now also the
|
||||
public site's building blocks), `@crosscode/seo` (meta, JSON-LD, sitemap), `@crosscode/auth-client`
|
||||
(sign-in), `@crosscode/contracts`.
|
||||
|
||||
## 2. Content: shared and Website-only
|
||||
|
||||
**The rule:** facts that more than one product shows live in the **church profile**
|
||||
(`crosscode.church/1`, owned by Accounts). How the Website presents them, and anything only the
|
||||
Website shows, lives in the **Website's own database**. Leaders, ministries, About, giving and
|
||||
messages stay **Website-only for now** (decision 5), and can move into the profile when the App needs
|
||||
them (phase 6–7).
|
||||
|
||||
| Shared: `crosscode.church/1` | Website-only |
|
||||
|---|---|
|
||||
| Already there: name, short name, logo, icon, colours, campuses, service times, contact, social, links | Template, section variants, style settings other than fonts and corners (§3), homepage order |
|
||||
| **New in contracts 1.15.0:** `branding.style`: `fontPairing` (an id from the shared list, §3) and `corners` (`sharp` / `soft` / `round`). Optional and additive, so a minor version | Pages, sections and blocks, navigation, custom pages |
|
||||
| | About (story, mission, vision, values, beliefs), Plan your visit, Leaders, Ministries, Give |
|
||||
| | Messages and series (§7), simple events (§8), media library, per-page SEO |
|
||||
| | Drafts, published versions, preview links |
|
||||
|
||||
- **Editing shared facts from the Website** (decision 10): the Website's admin shows the profile's
|
||||
fields where they're used (service times on the Service times screen, the logo on Branding) and
|
||||
saves them through **Accounts' API** with the admin's token, as ACCOUNTS-1.0-PLAN §7 proposed.
|
||||
Accounts → Church profile stays the other way in.
|
||||
- **Shared facts aren't drafts:** Accounts has no draft state, and Events shows the profile too.
|
||||
A change to a shared fact goes live in every product straight away, and the Website's screens
|
||||
say so ("Changes here show on all your church's sites at once"). The preview always shows the
|
||||
current profile.
|
||||
- **Legal pages:** the privacy notice is Accounts' (the version people agreed to), linked from the
|
||||
footer. The Website adds its own terms and safeguarding pages from starter text.
|
||||
- **Content is never tied to a template.** Every section stores its data (validated with a zod
|
||||
schema per section type) and its chosen variant. Switching template keeps the data, and each
|
||||
template maps every variant to its nearest look.
|
||||
|
||||
## 3. Templates and customisation
|
||||
|
||||
Four templates, decided in decision 19: **Heritage, Bold, Community, Clean** (ROADMAP §6). Rather
|
||||
than adding more templates (more looks, but churches on the same one still look the same), each
|
||||
template has room to vary in four ways, within limits that keep every site designed, accessible
|
||||
and fast (decision 1).
|
||||
|
||||
**1. Template = structure.** The header and navigation style, the page rhythm, the default homepage
|
||||
order and which variant each section starts with.
|
||||
|
||||
**2. Section variants.** Every section type comes in two or three layouts, and every template can
|
||||
render every variant in its own style.
|
||||
|
||||
| Section | Variants |
|
||||
|---|---|
|
||||
| Hero | Photo · Video (muted, with a still for phones and reduced motion) · Collage · Split (image and text) · Text only |
|
||||
| Service times and location | Panel · Inline strip · With map |
|
||||
| Welcome / introduction | Text · Image and text · With pastor's photo and quote |
|
||||
| Ministries | Cards · List · Alternating bands |
|
||||
| Team / leaders | Faces grid · List · Featured (one large, rest small) |
|
||||
| Upcoming events | Cards · List · Calendar strip |
|
||||
| Latest message | Large video · Card · Compact |
|
||||
| Invitation (call to action) | Banner · Centred · Image background |
|
||||
|
||||
**3. Style settings**, on one screen with a live preview:
|
||||
|
||||
| Setting | Options | Shared? |
|
||||
|---|---|---|
|
||||
| Font pairing | 8 pairings in a shared list (self-hosted, no Google Fonts requests); each template marks 3 as recommended, all 8 work everywhere | **Shared** (Events, Accounts, App) |
|
||||
| Corners | Sharp · Soft · Round | **Shared** |
|
||||
| Colours | From the profile (primary, accent); tints and shades built and contrast-checked (WCAG AA, darkened or lightened automatically, with a note why) | **Shared** (already) |
|
||||
| Section colour | Light · Tinted (the church colour as a soft background) · Mixed with dark bands | Website |
|
||||
| Spacing | Airy · Compact | Website |
|
||||
| Buttons | Solid · Outline · Pill | Website |
|
||||
| Image treatment | Natural · Black and white · Duotone in the church colour | Website |
|
||||
| Header | Each template's options (e.g. Bold: transparent over the hero, or solid) | Website |
|
||||
|
||||
**4. Pages from blocks.** Besides the fixed pages (§6), churches add **custom pages** (Youth camp,
|
||||
Our history, Kids…) from blocks: text, image and text, gallery, quote, video, FAQ, map, people
|
||||
cards, call to action, divider. Blocks come in the same variants and follow the style settings.
|
||||
|
||||
**Not in 1.0:** free drag-and-drop layout, custom CSS, custom fonts. Each would break phone
|
||||
layouts, accessibility or speed for some churches, and create support work. More templates can come
|
||||
in 1.x (they're part of the product, ROADMAP §1 rule 3).
|
||||
|
||||
**Photos:** the setup checklist explains what photos work (people, not buildings; landscape for
|
||||
heroes). The duotone treatment makes uneven photos look consistent. Every image needs alt text.
|
||||
Uploads are resized into responsive sizes (WebP and JPEG).
|
||||
|
||||
## 4. Drafts, preview and publish
|
||||
|
||||
Decision 2: **one Publish for the whole site.**
|
||||
|
||||
- **The working copy** is the content tables the admin edits. **A published version** is an
|
||||
immutable snapshot of all of them (`SiteVersion`: JSON, who, when, an optional note). Visitors
|
||||
always see the latest published version.
|
||||
- **Pending changes:** the admin header shows "N changes not published". The Publish screen lists
|
||||
each change (page, section, setting; who made it, when), and any one can be **discarded** (back
|
||||
to its published value).
|
||||
- **Preview** (`/admin/preview`, or the Preview button anywhere): the whole site from the working
|
||||
copy, **fully clickable** (navigation, events, messages, video), with a bar on top: phone /
|
||||
tablet / desktop width, "Back to editing", the change count and **Publish**. The bar is outside
|
||||
the page, so the page is laid out exactly as it will be.
|
||||
- **Share a preview:** a link (`/preview/<token>`) for someone without an account, e.g. the pastor.
|
||||
It expires after 7 days (or when revoked), shows the working copy as it is when opened, sends
|
||||
`noindex`, and can't edit or publish.
|
||||
- **Version history:** every publish is kept. **Restore** copies a version back into the working
|
||||
copy, so it's previewed and published like any other change; nothing is lost.
|
||||
- **Two editors at once:** one shared working copy, saved per field. A field changed by someone else
|
||||
since it was opened warns before it's overwritten. Publish publishes everyone's changes, and the
|
||||
list shows whose they are.
|
||||
- **What doesn't wait for Publish** (decision 9): simple events and messages are things that happen
|
||||
rather than the site's design, so each has its own Publish (and messages found automatically on
|
||||
YouTube appear on their own, §7). Changes to shared profile facts go live straight away (§2).
|
||||
- **Template switch:** the new template is a pending change like any other, so the whole site can be
|
||||
previewed in it before publishing.
|
||||
- Every publish, discard and restore is in the audit log.
|
||||
|
||||
## 5. Coming soon
|
||||
|
||||
Decision 3: until the site's **first publish**, the public address shows a **Coming soon** page, not
|
||||
an empty site.
|
||||
|
||||
- From the church profile: logo, name, colours and fonts, service times and address, contact
|
||||
details, social links, and buttons to the church's Events (and App) when they're linked. A short
|
||||
"Our new website is on its way" line the admin can change.
|
||||
- `noindex`, an empty sitemap, `robots.txt` as usual. Real HTTP 200, so the church's details are
|
||||
still useful to someone who finds the address.
|
||||
- Signed-in admins see a banner on it: "Your site isn't published yet. Preview it or publish it."
|
||||
- After the first publish there is no going back to Coming soon in 1.0 (unpublishing isn't needed).
|
||||
|
||||
## 6. Pages
|
||||
|
||||
As ROADMAP §6, with these changes:
|
||||
|
||||
- **Contact:** **contact details only** (decision 4): address with a map, phone, email, WhatsApp,
|
||||
service times, social links. No contact form (personal information belongs in the App, §6 "Not in
|
||||
the first release").
|
||||
- **Give:** information and the church's provider links (SnapScan, Zapper, PayFast page, bank
|
||||
details as text). No giving processed.
|
||||
- **Events:** list, detail, calendar, past (§8).
|
||||
- **Messages:** list, series, detail (§7).
|
||||
- **Home:** the sections in the template's order; the church can reorder, hide and show them.
|
||||
- Every page: unique title and description, canonical, Open Graph image (generated from the logo and
|
||||
colours when the page has none), JSON-LD (`Church` on home and contact, `Event`, `VideoObject`,
|
||||
`BreadcrumbList`), exactly one `<h1>`, `lang="en-ZA"`. Slug changes get a 301 to the new slug
|
||||
(within the site; moving domains is decision 6).
|
||||
|
||||
## 7. Messages
|
||||
|
||||
Decision 7: two ways in, chosen in **Messages → Settings**:
|
||||
|
||||
- **From YouTube, automatically.** The admin gives the church's **channel** or a **playlist** (a
|
||||
playlist is better when the channel has other uploads). A job reads YouTube's public feed
|
||||
(`youtube.com/feeds/videos.xml?channel_id=…` / `?playlist_id=…`, no API key) every hour, and each
|
||||
new video becomes a message (title, date, thumbnail, video). Admins can add the speaker, series,
|
||||
Bible passage and notes afterwards, or hide one. The newest is the home page's **Latest message**.
|
||||
- **By hand.** Add a message with a **YouTube or Spotify link** (episode or show) and the same
|
||||
details.
|
||||
|
||||
Both can be used together. Embeds load only when clicked (a thumbnail first), use
|
||||
`youtube-nocookie.com`, and set `VideoObject` (or `PodcastEpisode` for Spotify) JSON-LD. Audio and
|
||||
video are never uploaded (ROADMAP §10), so they don't count towards storage.
|
||||
|
||||
## 8. Events
|
||||
|
||||
- **Simple events** made in the Website (title, date and time, place, description, image, an
|
||||
optional link). Only Cross Events takes registrations and payments (roadmap decision 4).
|
||||
- **The event feed** as Events 2.4: Settings → Linked products, "Publish my events" and "Show events
|
||||
from". Events from Cross Events show in the template's event cards and link through to Cross
|
||||
Events for registering.
|
||||
- **Imported events** carry `<link rel="canonical">` to the origin's page and aren't in the
|
||||
Website's sitemap (ROADMAP §11). A source that's down keeps its last events showing.
|
||||
|
||||
## 9. Connected with Events and the App
|
||||
|
||||
Decision 8. The three products look like one church without looking like each other:
|
||||
|
||||
- **Brand style is shared** (§2, §3): the same colours, logo, font pairing and corners in the
|
||||
Website, in Cross Events' public pages and Accounts' sign-in pages, and later in the App.
|
||||
- **One footer.** `@crosscode/ui` gets a `ChurchFooter` built from the profile (logo, service times,
|
||||
address, contact, social, links to the church's Website, Events and App, the privacy notice). The
|
||||
Website uses it in every template (styled by the template), Events 3.7 and Accounts 1.7 use it on
|
||||
their public pages.
|
||||
- **Links between products:** each product's header has a link to the others that exist (from the
|
||||
profile's `links`): "Events", "Website", later "App".
|
||||
- **One sign-in and account menu** (already, through Accounts).
|
||||
- **Events 3.7.0:** public pages (event list and detail, registration, the church's home) use the
|
||||
shared fonts, corners and footer. Admin and staff screens stay as they are. Nothing else changes.
|
||||
|
||||
## 10. Admin, roles and storage
|
||||
|
||||
**Admin** (`/admin`, as ROADMAP §6): dashboard with the setup checklist ("Choose your template"
|
||||
first, previewed with the church's own logo, colours and content, or sample content), pending
|
||||
changes and recent edits; Template and style; Pages; About; Leaders; Ministries; Messages; Events;
|
||||
Media library; Contact and service times; Navigation; Settings (SEO, search engine verification,
|
||||
linked products, email); Version history; Audit log. Each field shows the Google-style snippet
|
||||
preview and SEO warnings where they apply (ROADMAP §11).
|
||||
|
||||
**Roles** (per product, held in the Website; proposed in decision 11):
|
||||
|
||||
| Role | Can |
|
||||
|---|---|
|
||||
| Owner | Everything, including roles and the licence |
|
||||
| Admin | Everything but the licence and Owners |
|
||||
| Editor | Edit everything, preview, share previews, **publish** |
|
||||
| Ministry leader | Edit their own ministry's page and events; their changes wait for an Editor or above to publish |
|
||||
| Viewer | See the admin and the preview, change nothing |
|
||||
|
||||
Admin roles can require 2FA through Accounts (`acr_values=mfa`, ACCOUNTS-1.0-PLAN decision 8): on by
|
||||
default for Owner and Admin.
|
||||
|
||||
**Storage** (ROADMAP §10): 5 GB of uploads included. Settings shows what's used; admins get an email
|
||||
at 80% and at 100%. **When it's full, uploads stop** (decision 12) until more storage is bought:
|
||||
the media library and every upload field say so, with **Get more storage** (Settings → Storage).
|
||||
That asks the Hub, as Request update does, and the Hub emails Joshua. Once he adds a 5 GB step to the
|
||||
licence, the new limit reaches the site with the next heartbeat answer (within a minute or so) and
|
||||
uploads work again. Everything already uploaded keeps showing; only new uploads are refused. The
|
||||
limit is the licence's (5 GB plus the steps bought), never the site's own setting. An upload is
|
||||
only freed when neither the working copy nor the last 10 published versions use it.
|
||||
|
||||
## 11. Hub, licence and servers
|
||||
|
||||
- **Hub protocol v2, product `website`.** The heartbeat's `websiteStatsSchema` is already in the
|
||||
contracts (pages, messages, events, editors, storage). A Website licence needs the church's
|
||||
Accounts, installed first (as Events 3.x).
|
||||
- **Hub 2.11.0:** New install offers the Website; release sync for `website@` tags and
|
||||
`apps/website/WHATS-NEW.md`; its env template; the Website's price (R99) and the storage add-on
|
||||
(R20 per extra 5 GB, sent to the site with the licence as its storage limit, and the "Get more storage"
|
||||
request with its email to Joshua) in `frontend/src/lib/tiers.ts` and `backend/src/utils/billing/tiers.js`, in
|
||||
step with crosscode-site; the FastPanel email for `www.` (and the bare domain sent to `www.` with a
|
||||
301, for an own domain) or `<church>.crosscode.co.za`.
|
||||
- **`crosscode`:** `scripts/products/website.sh` with the same hooks as Events and Accounts (`website`
|
||||
is already in `PRODUCT_ORDER`), `website.env.template.json`, `crosscode add <church> website`. The
|
||||
env template in three places, plus any value rules (HANDOVER, "A new .env variable").
|
||||
- **Agent:** none expected. The job schemas already take `website` (`releaseTagSchema`, `PRODUCTS`).
|
||||
The frp port list gets the Website's two ports.
|
||||
- **Accounts 1.7.0:** `branding.style` on the church profile (and Accounts → Church profile), the
|
||||
Website as a client through Connect (as Events), the profile API allowing the Website's admins to
|
||||
save, the shared fonts and footer on its pages.
|
||||
- **Uninstall:** the church export (`crosscode.church-export/1`) gets a `website` section (content,
|
||||
versions' notes, messages, events) and the uploaded media, as Events' export does its uploads.
|
||||
- **Demo church:** `npm run demo` loads a fictional church (fictional people and photos only) into
|
||||
each template, for the crosscode-site screenshots and the Hub's demo sites.
|
||||
|
||||
## 12. What changes in each repo
|
||||
|
||||
| Repo | Change | Version |
|
||||
|------|--------|---------|
|
||||
| `crosscode-platform` `apps/website` | New (§1–§11), with `CHANGELOG.md`, `WHATS-NEW.md`, `env.template.json`, e2e, demo data | `website@1.0.0` |
|
||||
| `crosscode-platform` `packages/contracts` | `branding.style` (`fontPairing`, `corners`) on `crosscode.church/1`, the font pairing ids, a `website` part of the church export | `contracts@1.15.0` |
|
||||
| `crosscode-platform` `packages/ui` | Fonts (self-hosted), the theme from the profile (colours, fonts, corners as CSS variables), `ChurchFooter`, links between products, the public site's building blocks | workspace |
|
||||
| `crosscode-platform` `packages/seo` | `Church`, `VideoObject`, `PodcastEpisode`, `BreadcrumbList` builders, the generated share image | workspace |
|
||||
| `crosscode-platform` `apps/accounts` | `branding.style` in the church profile, the shared fonts and footer, the Website's admins saving the profile | `accounts@1.7.0` |
|
||||
| `crosscode-platform` `apps/events` | Public pages with the shared fonts, corners and footer | `events@3.7.0` |
|
||||
| `crosscode-platform` `scripts/` | `products/website.sh`, `website.env.template.json`, bats tests | — |
|
||||
| `events-hub` | Website in New install, its releases, env template, prices and storage add-on, FastPanel email | Hub `v2.11.0` |
|
||||
| `crosscode-site` | Church Website on sale (ROADMAP §9): its page, prices, a page per template, screenshots of the demo church, FAQ, `SoftwareApplication` JSON-LD | `v1.7.0` |
|
||||
|
||||
## 13. Testing
|
||||
|
||||
- **Unit (Jest):** section schemas and variants, the palette builder and contrast fixes, publish /
|
||||
discard / restore, pending change lists, preview tokens (expiry, revoke, no edit rights), roles
|
||||
(a Ministry leader can't publish or edit another ministry), the YouTube feed parser (channel,
|
||||
playlist, duplicates, a removed video), storage counting, uploads refused when full (and allowed again when the licence's limit goes
|
||||
up), uploads kept by older versions.
|
||||
- **Playwright, every template at phone / tablet / desktop:** the demo church's pages look right
|
||||
(screenshots compared), axe has no violations, the §11 checks (title, description, canonical,
|
||||
`og:image`, one `<h1>`, JSON-LD parses, sitemap, `robots.txt`, `noindex` where it should be).
|
||||
- **Playwright, the flows:** Coming soon before the first publish; edit → preview (click through
|
||||
the site) → publish → the public site changes; discard one change; a shared preview link works
|
||||
signed out and stops after revoking; restore an older version; switch template in preview and
|
||||
back without losing anything; sign in from a deep admin page and land back on it (through 2FA).
|
||||
- **Lighthouse (mobile):** home, an event and a message in each template: SEO 100,
|
||||
accessibility 95+, performance 90+.
|
||||
- **Events 3.7:** the e2e suite still passes, and its public pages show the church's fonts and the
|
||||
shared footer.
|
||||
- **The release checks** (ROADMAP §9) for the Website, and the **VM test**: install the Website
|
||||
next to Accounts and Events through the agent, update it, uninstall it with its export.
|
||||
|
||||
## 14. Releasing and rolling it out
|
||||
|
||||
1. `contracts@1.15.0`, then `accounts@1.7.0` (the profile's brand style), then `events@3.7.0`.
|
||||
2. Hub `v2.11.0` (vendored contracts 1.15.0) deployed.
|
||||
3. `website@1.0.0` tagged after the e2e, Lighthouse and VM runs.
|
||||
4. **Hope Family Church:** Accounts 1.7.0 and Events 3.7.0 first, then New install → Website. The
|
||||
site shows Coming soon while the church builds it, and goes live with its first publish.
|
||||
5. **A second test church** on a different template.
|
||||
6. crosscode-site `v1.7.0`: the Website on sale.
|
||||
|
||||
## Decisions
|
||||
|
||||
Made by Joshua on 2026-11-21:
|
||||
|
||||
1. **Customisation within limits:** four templates, each with section variants, style settings and
|
||||
custom pages from blocks (§3). No free layout, custom CSS or custom fonts. More templates later,
|
||||
not instead.
|
||||
2. **One Publish for the whole site,** after a fully clickable preview (§4), with a shareable preview
|
||||
link and version history.
|
||||
3. **Coming soon** until the first publish (§5).
|
||||
4. **Contact page: details only,** no form (§6).
|
||||
5. **Leaders, ministries, About, giving and messages are Website-only** for now (§2). Only the brand
|
||||
style (font pairing, corners) is added to the shared profile.
|
||||
6. **No address move or redirects in 1.0,** and no Hub "Change address" job yet. Moving to the
|
||||
church's own domain (ROADMAP §10, §11 "Moving addresses") comes later.
|
||||
7. **Messages from a YouTube channel or playlist automatically, or by hand with a YouTube or
|
||||
Spotify link** (§7).
|
||||
8. **The three products feel connected:** shared brand style and footer, and **Events 3.7** uses the
|
||||
shared fonts and footer on its public pages (§9).
|
||||
|
||||
Proposed and confirmed on 2026-11-21 (12 changed):
|
||||
|
||||
9. **Simple events and messages publish on their own,** not with the site's Publish; YouTube messages
|
||||
appear automatically (§4, §7).
|
||||
10. **The Website's admin edits shared profile facts through Accounts' API,** and they go live
|
||||
straight away (§2). Answers ACCOUNTS-1.0-PLAN's "Still open".
|
||||
11. **Editors can publish; Ministry leaders' changes wait** for an Editor or above (§10).
|
||||
12. **A full storage stops uploads** until more is bought (admins emailed at 80% and 100%; "Get more
|
||||
storage" asks the Hub; §10). Changed from the proposal, which let uploads carry on and billed
|
||||
afterwards.
|
||||
13. **Fonts are self-hosted** (no Google Fonts requests, for POPIA and speed), from a shared list of 8
|
||||
pairings (§3).
|
||||
14. **Coming soon is a real page (HTTP 200) with `noindex`,** not a 503 (§5).
|
||||
|
||||
## Still open
|
||||
|
||||
- The 8 font pairings and the exact variants per template: settled with the template designs, early
|
||||
in the build.
|
||||
- Whether the App (phase 6) moves leaders, ministries and giving into `crosscode.church/1` or reads
|
||||
them from the Website. Decide with the App plan.
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
Shared UI for the products a church's members see: the branded shell, cards, buttons, form fields
|
||||
and notices. First used by Accounts' sign-in and account pages (phase 3); the Church Website and
|
||||
App build on it (phases 4 and 6).
|
||||
App build on it (phases 5 and 6).
|
||||
|
||||
- Plain React + Tailwind, no runtime dependencies. Apps compile the source
|
||||
(`transpilePackages: ["@crosscode/ui"]` in `next.config.ts`) and add
|
||||
|
||||
+18
-4
@@ -355,10 +355,24 @@ node_major() { node -p 'process.versions.node.split(".")[0]' 2>/dev/null || echo
|
||||
# Files changed or added by hand in a checkout (ignored files such as .env, uploads, backups and
|
||||
# the install's ecosystem.config.js never count). The PM2 configs this script makes for each
|
||||
# install never count either, also in checkouts of releases that don't ignore them yet (Accounts
|
||||
# 1.0–1.1 has no .gitignore for its ecosystem.config.cjs).
|
||||
# 1.0–1.1 has no .gitignore for its ecosystem.config.cjs). Nor do the files in the folders this
|
||||
# script writes into (Accounts below 1.3.0 doesn't ignore the database dumps made before each
|
||||
# deploy, so the dump would stop the very deploy that brings the .gitignore).
|
||||
CROSSCODE_OWN_FILES=(apps/events/ecosystem.config.js apps/accounts/ecosystem.config.cjs)
|
||||
CROSSCODE_OWN_DIRS=(apps/accounts/backend/backups/)
|
||||
local_changes() {
|
||||
git_in "$1" status --porcelain --untracked-files=all | awk -v own="${CROSSCODE_OWN_FILES[*]}" '
|
||||
BEGIN { n = split(own, f, " "); for (i = 1; i <= n; i++) skip[f[i]] = 1 }
|
||||
!(substr($0, 1, 2) == "??" && substr($0, 4) in skip)'
|
||||
git_in "$1" status --porcelain --untracked-files=all |
|
||||
awk -v own="${CROSSCODE_OWN_FILES[*]}" -v dirs="${CROSSCODE_OWN_DIRS[*]}" '
|
||||
BEGIN {
|
||||
n = split(own, f, " "); for (i = 1; i <= n; i++) skip[f[i]] = 1
|
||||
m = split(dirs, d, " ")
|
||||
}
|
||||
{
|
||||
if (substr($0, 1, 2) == "??") {
|
||||
path = substr($0, 4)
|
||||
if (path in skip) next
|
||||
for (i = 1; i <= m; i++) if (index(path, d[i]) == 1) next
|
||||
}
|
||||
print
|
||||
}'
|
||||
}
|
||||
|
||||
@@ -159,6 +159,20 @@ cc() { bash "$CROSSCODE_HOME/crosscode" "$@"; }
|
||||
[[ "$output" == *"apps/accounts/notes.txt"* ]]
|
||||
}
|
||||
|
||||
@test "the database dumps crosscode makes don't count as changes by hand" {
|
||||
# Accounts below 1.3.0 has no .gitignore for backend/backups/.
|
||||
mkdir -p "$CROSSCODE_SITES/hope/events/apps/accounts/backend/backups"
|
||||
echo "dump" > "$CROSSCODE_SITES/hope/events/apps/accounts/backend/backups/accounts-20261119-221205.sql.gz"
|
||||
run cc deploy hope events --version events@2.2.1 --check
|
||||
[ "$status" -eq 0 ]
|
||||
# A file merely named like the folder still counts.
|
||||
echo "notes" > "$CROSSCODE_SITES/hope/events/apps/accounts/backend/backups.txt"
|
||||
run cc deploy hope events --version events@2.2.1 --check
|
||||
[ "$status" -eq 1 ]
|
||||
[[ "$output" == *"apps/accounts/backend/backups.txt"* ]]
|
||||
[[ "$output" != *"accounts-20261119-221205.sql.gz"* ]]
|
||||
}
|
||||
|
||||
@test "--allow-local-changes deploys with a file added by hand" {
|
||||
echo "notes" > "$CROSSCODE_SITES/hope/events/apps/events/notes.txt"
|
||||
run cc deploy hope events --version events@2.2.1
|
||||
|
||||
Reference in New Issue
Block a user