From 6bb80f75d1ff97748acda5d2fab84feb9f8b3dad Mon Sep 17 00:00:00 2001 From: joshua Date: Wed, 4 Nov 2026 10:04:13 +0200 Subject: [PATCH] Roadmap v3: four Website templates; SEO for every public site Co-Authored-By: Claude Opus 5.5 --- apps/events/docs/ROADMAP-v3.md | 120 ++++++++++++++++++++++++++++++--- 1 file changed, 109 insertions(+), 11 deletions(-) diff --git a/apps/events/docs/ROADMAP-v3.md b/apps/events/docs/ROADMAP-v3.md index a42571d..e51f34b 100644 --- a/apps/events/docs/ROADMAP-v3.md +++ b/apps/events/docs/ROADMAP-v3.md @@ -24,8 +24,9 @@ whatever direction the church chooses. 8. [Servers and deployment](#8-servers-and-deployment) 9. [Build order](#9-build-order) 10. [Pricing](#10-pricing) -11. [Decisions](#decisions-2026-11-03) -12. [Still open](#still-open) +11. [SEO (every public site)](#11-seo-every-public-site) +12. [Decisions](#decisions-2026-11-03) +13. [Still open](#still-open) --- @@ -296,16 +297,55 @@ A professional public website the church manages itself. From the website spec, Messages (sermons, series), Give (information and provider links), Contact, Privacy / POPIA / safeguarding / terms. - **Homepage order:** hero with Plan Your Visit, service times and location, mission, - introduction, ministries and team, upcoming events, latest message, final invitation. -- Branding from `crosscode.church/1`: logo, colours, a choice of themes. Approved section types - that can be reordered, not free-form layout editing. -- Server-rendered for SEO, fast on a phone, accessible (WCAG 2.2 AA, axe checks in Playwright). + introduction, ministries and team, upcoming events, latest message, final invitation (each + template starts from this and arranges it its own way, below). +- Server-rendered, fast on a phone, accessible (WCAG 2.2 AA, axe checks in Playwright), with + the SEO in §11. + +### Templates: each church its own identity + +The website is the most personal of the products, so churches shouldn't all look the same. +The Website ships with **four templates**, each with its own **layout and design**. The church +picks one; its **logo and colours come from the church profile** (`crosscode.church/1`), and its +**content fills into the chosen template**. + +| Template | Character | Layout and design | +|----------|-----------|-------------------| +| **Heritage** | Traditional, dignified | Centred logo and navigation above a framed hero image; serif headings; generous margins; content in a single centred column with thin rules between sections; service times in a formal panel | +| **Bold** | Modern, energetic | Full-screen photo or video hero with large overlaid headline; sticky transparent header; strong sans-serif type; full-bleed alternating image / text bands; large "Plan your visit" call to action | +| **Community** | Warm, friendly, family | Logo left, rounded friendly type; a hero with photo collage; content in cards (ministries, events, messages as a grid); soft shapes and the church colour as tinted backgrounds; people's faces prominent | +| **Clean** | Minimal, calm | Small header, lots of white space; typographic hero (no photo needed, good for churches without good photos); narrow text column; lists rather than cards; colour used sparingly as accent | + +**How it works** + +- **One content model, four presentations.** Content is structured (pages, sections, ministries, + leaders, messages, events, service times), never tied to a template. Every template renders + every section type in its own way, so **switching template never loses content**. +- **The template sets the layout:** header and navigation style, hero type, how each section + type looks, section spacing, typography (with two or three font pairings to choose from per + template), shapes and image treatment, and the default homepage order. Within it, churches can + reorder, hide and show the approved sections, but not edit layout freely, so a site always + looks designed. +- **Colours from the church, made safe:** the template builds its palette (tints, shades, text + colours, buttons) from the church's primary and accent colours, and checks contrast (WCAG AA). + A colour that fails is darkened or lightened automatically, and the admin is told why. +- **Logo** in the template's header and footer positions; the icon (from the profile) for the + favicon and share images. +- **Choosing:** the setup checklist starts with "Choose your template", showing all four + **previewed with the church's own logo, colours and content** (sample content until they have + their own). Switching later goes through preview → publish like any other change. +- **Templates are part of the product**, not per church (§1, rule 3): they improve in each + release for every church using them. More templates can be added in later releases. +- Every template meets the same bar: tested in Playwright (layout at phone / tablet / desktop, + axe accessibility) and with the §11 SEO checks. ### Admin (`www.church.co.za/admin`, signed in through Accounts) - Dashboard with a setup checklist, recent edits and drafts. +- **Template:** choose and preview the template, font pairing, and which homepage sections show + in which order. - Pages and sections, About, Leadership, Ministries, Messages, Media library, Contact and - service times, Navigation, Settings. + service times, Navigation, Settings (including SEO and search engine verification, §11). - **Events:** simple events, plus the feed settings (§4) and sync health. - **Draft → preview → publish**, archive instead of delete, an audit log of who changed what. - **Roles:** Owner, Admin, Editor, Ministry leader (own ministry only), Viewer. @@ -387,7 +427,7 @@ browsed without an account. Personal actions need sign-in through Accounts. |------|------| | `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` | +| `joshua/crosscode-platform` (new) | Monorepo: `apps/accounts`, `apps/website`, `apps/app`, `packages/contracts`, `packages/ui`, `packages/seo` (§11) | | `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, @@ -402,9 +442,9 @@ Playwright, Jest), so code and habits carry over. | 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) | 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), `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, 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 | +| 4 | **Church Website 1.0.0** | Public site with the **four templates** (§6), admin, simple events + feed, SEO (§11), Hope Family Church as the first church, then a second test church on a different template to prove it repeats | More churches need a website than an app; it also covers the "website only" case | | 5 | **Cross Events 3.0.0** | Sign-in moves to Accounts; user migration keeping password hashes; migration guide | Breaking change, so a major version, after Accounts is proven on the Website | | 6 | **Church App 1.0.0** | Foundation (PWA, branding, Accounts), House of Prayer, announcements, devotionals, events (simple + feed) | Starts with shared users and the feed already in place | | 7 | Church App 1.x | Reading plans, sermons, groups, pastoral care, serving, giving links, directory | After House of Prayer is in use | @@ -425,7 +465,7 @@ At the end of each phase, update it in the same sitting and deploy it (its `DEPL | 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 | | 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`, screenshots from a demo church (fictional people only), FAQ, home page, contact form product list | +| 4 Website 1.0.0 | **Church Website goes on sale:** `status: "available"` and its own page in `src/data/products.mjs` / `src/pages/products/`, R99 + storage add-on in `pricing.mjs`, **a showcase of the four templates** (a page per template with screenshots of the same demo church in each), screenshots from a demo church (fictional people only), FAQ, home page, contact form product list, `SoftwareApplication` JSON-LD (§11) | | 5 Events 3.0.0 | Cross Events page: sign-in through the church's shared account. Update screenshots that show the login | | 6 App 1.0.0 | **Church App goes on sale:** own page, active-member tiers in `pricing.mjs`, House of Prayer screenshots, the bundle examples from §10 | | 7 App 1.x | New modules added to the App page's feature list as each one ships | @@ -443,6 +483,7 @@ Hub never disagree. Run the site's tests and build before deploying it. - Signing in from any page of any product returns to that same page (including through 2FA and a password reset), and a foreign return URL is refused. - crosscode-site shows the product as available, with its page, prices and screenshots. +- The §11 SEO checks pass (Playwright and Lighthouse), for the Website in all four templates. - A database backup is restored successfully. --- @@ -513,6 +554,61 @@ as a band (like event income for Cross Events). Visitors browsing without signin --- +## 11. SEO (every public site) + +Every public site gets search engine optimisation at least as good as Cross Events has today: +the **Church Website**, **Cross Events**, the public parts of the **Church App**, and the +marketing site **crosscode.co.za**. A church should be found when someone searches "church near +me", its name, or an event it's running. + +### The baseline (what Cross Events does now, for every product) + +- **Server-rendered HTML** with a unique `` and meta description on every page. +- **Canonical URL** on every page (tracking tags such as `?src=` dropped). +- **Open Graph and Twitter cards** with an image on every page. Pages without their own image + get a share image generated from the church's logo and colours. +- **`sitemap.xml`** generated from published content and refreshed hourly, and **`robots.txt`** + that points to it and keeps admin, sign-in and personal pages out. +- **schema.org JSON-LD** (e.g. `Event` on event pages, as `frontend/src/lib/eventSchema.ts` does, + checked with Google's Rich Results Test). +- Readable slugs, with **301 redirects** when a slug changes; real 404 status for missing pages; + `lang="en-ZA"`. +- **Fast and accessible:** responsive images with required alt text, good Core Web Vitals on a + phone (LCP under 2.5 s, CLS under 0.1), WCAG 2.2 AA. + +The JSON-LD builders and meta helpers live in a shared `packages/seo` in the platform monorepo, +built on `@crosscode/contracts`, so Events, the Website and the App produce the same schema.org +data from the same `crosscode.event/1` and `crosscode.church/1`. Cross Events moves its +`eventSchema.ts` onto it in 2.3.0. + +### Per product + +| Product | SEO | +|---------|-----| +| **Church Website** | JSON-LD `Church` (name, logo, address, geo, phone, service times, social links) on the home and contact pages, so the church shows up in local search and maps; `Event` for its events; `VideoObject` / `PodcastEpisode` for messages; `BreadcrumbList`. Admin: per-page title and description (with a Google-style snippet preview), warnings for a missing description, alt text or a too-long title, and a field for Google Search Console / Bing verification. Setup checklist links to setting up a Google Business Profile. All four templates produce the same markup and pass the same checks | +| **Imported events** | A copy of another product's event (§4) has `<link rel="canonical">` pointing to the **origin's** page, so search engines see one event, not three. Only the origin is in its sitemap | +| **Cross Events** | Already has the baseline. Gains the shared `packages/seo`, `Organization` / `Church` data from the church profile, and the canonical rule for imported events | +| **Church App** | Public content (events, devotionals, sermons, announcements marked public) gets the baseline. Everything signed in, prayer and care is `noindex` and kept out of the sitemap. **Prayer requests are never indexable** | +| **Accounts** | `noindex` everywhere, blocked in `robots.txt`: sign-in pages should never appear in search | +| **Cross Code Hub** | `noindex` everywhere | +| **crosscode.co.za** | Already has canonical URLs, Open Graph, `Organization` / `WebPage` JSON-LD, sitemap and robots. Adds `SoftwareApplication` JSON-LD with prices (`Offer`) on each product page, `FAQPage` on the FAQs, a page per Website template, and Search Console / Bing set up and checked after each site update (§9, "Updating crosscode-site") | + +### Moving addresses + +When a church moves from the Cross Code address to its own domain (§10), every old URL +**301-redirects** to the same page on the new domain for 12 months, so it keeps its search +ranking. + +### Checks (in every product's tests) + +- Playwright: every public page has a title, description, canonical, `og:image`, exactly one + `<h1>`, and JSON-LD that parses; the sitemap lists the published pages and nothing private; + `robots.txt` blocks admin and sign-in; `noindex` pages really are `noindex`. +- Lighthouse (mobile) on a demo church's home, event and message pages, in every template: + SEO 100, accessibility 95+, performance 90+. + +--- + ## Decisions (2026-11-03) | # | Question | Decision | @@ -535,6 +631,8 @@ as a band (like event income for Cross Events). Visitors browsing without signin | 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) | ## Still open