Roadmap v3: four Website templates; SEO for every public site

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-04 10:04:13 +02:00
co-authored by Claude Opus 5.5
parent 5ab755cc63
commit 6bb80f75d1
+109 -11
View File
@@ -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 `<title>` 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