docs(about-blog): design for a named author, an About page and a Payload blog
The site reads as synthetic because nobody is accountable for the numbers, no editorial judgement is visible, and the voice is institutional third person. This designs the fix: a named author (first name, photo, explicitly not an education expert), a coded /about page, and a blog backed by Payload CMS running inside the existing Next app. Also fills a hole in the SEO programme, which has eight workstreams and no E-E-A-T or authorship signal on a YMYL corpus. Records two collisions found while designing, both of which fail badly if missed: Payload's default /api route fights the existing FastAPI catch-all proxy, and withPayload() is ESM-only so next.config.js — which carries staging's noindex header — has to become next.config.mjs. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FT1Ls4GbgLDXoQX7NAuHGT
This commit is contained in:
TudorandClaude Opus 5 committed
1 parent
e236669fde
commit
748ef32180
1 file changed
+341
@@ -0,0 +1,341 @@
|
|||||||
|
# Giving schoolcompare a human author: an About page and a blog
|
||||||
|
|
||||||
|
**Date:** 2026-09-02
|
||||||
|
**Status:** Design — awaiting review
|
||||||
|
**Scope:** A named author for the site, an `/about` page, and a Payload-CMS-backed
|
||||||
|
blog at `/blog`.
|
||||||
|
|
||||||
|
## Why
|
||||||
|
|
||||||
|
The site reads as synthetic. Not because of its tone, but because of three
|
||||||
|
specific absences:
|
||||||
|
|
||||||
|
1. **Nobody is accountable for the numbers.** There is no author, no statement
|
||||||
|
of why the site exists, and no one who can be wrong. The only human trace on
|
||||||
|
the entire site is `contact@schoolcompare.co.uk` in the footer.
|
||||||
|
2. **No visible judgement.** Every figure is presented as though it fell out of
|
||||||
|
a machine. Hundreds of editorial decisions went into this codebase — which
|
||||||
|
metrics to show, when a benchmark is invalid, what to suppress — and not one
|
||||||
|
of them is visible to a reader. `isSpecialSchool()` silently drops the
|
||||||
|
England comparison for special schools and PRUs because that comparison is
|
||||||
|
meaningless; nowhere does the site *say* so.
|
||||||
|
3. **The voice is institutional third person.** "schoolcompare brings it all
|
||||||
|
into one place." "Built for parents, governors, journalists." That is
|
||||||
|
brochure register, and it is precisely the register that machine-generated
|
||||||
|
content defaults to.
|
||||||
|
|
||||||
|
There is a second, independent reason. The SEO programme
|
||||||
|
(`2026-08-20-seo-programme-design.md`) defines eight workstreams and none of
|
||||||
|
them address E-E-A-T or authorship. School performance data is YMYL territory;
|
||||||
|
an anonymous site republishing DfE figures has no authorship signal at all. This
|
||||||
|
work fills that hole, and the blog gives W6 (explainer content) somewhere to
|
||||||
|
live.
|
||||||
|
|
||||||
|
### The failure mode to avoid
|
||||||
|
|
||||||
|
The standard fix — a stock photo and "Hi, I'm Tudor, and I'm passionate about
|
||||||
|
education!" — reads as *more* synthetic than the current coldness. Manufactured
|
||||||
|
warmth is a stronger machine-tell than plain institutional voice. Everything
|
||||||
|
here has to be specific, occasionally awkward, and willing to be unflattering,
|
||||||
|
or it makes the problem worse.
|
||||||
|
|
||||||
|
## Positioning
|
||||||
|
|
||||||
|
The author is **Tudor**: first name only, real photograph, no surname, no
|
||||||
|
employer named.
|
||||||
|
|
||||||
|
The credibility claim is deliberately **not** educational expertise. The About
|
||||||
|
page states plainly: *"I'm not an education expert."* Authority comes from two
|
||||||
|
things that are actually true:
|
||||||
|
|
||||||
|
- **Experience.** A parent going through primary admissions in south-west London
|
||||||
|
right now. Google's E-E-A-T leads with Experience, and lived experience of the
|
||||||
|
thing is exactly what the DfE's own service lacks.
|
||||||
|
- **Method.** Every number's provenance is stated, so a reader can check the
|
||||||
|
site rather than trust it.
|
||||||
|
|
||||||
|
This is more durable than borrowed expertise: it cannot be undermined by someone
|
||||||
|
noticing the author has no teaching qualification.
|
||||||
|
|
||||||
|
**Consequence for the design.** A `Person` entity with no surname is a weak
|
||||||
|
search signal and cannot be corroborated off-site. The credibility load
|
||||||
|
therefore shifts onto the methodology being visibly rigorous. That is a design
|
||||||
|
constraint, not a caveat — it is why the About page carries a substantial
|
||||||
|
"how this is built and where it can be wrong" section rather than a short bio.
|
||||||
|
|
||||||
|
### Voice rules
|
||||||
|
|
||||||
|
Applied to About and every post. Recorded here so the voice does not drift.
|
||||||
|
|
||||||
|
- First person singular. "I built", not "we provide".
|
||||||
|
- Concrete over general. "when we were looking at schools in Wandsworth" beats
|
||||||
|
any amount of stated warmth.
|
||||||
|
- State limits before someone else finds them. Every post that presents a
|
||||||
|
metric says what it does not show.
|
||||||
|
- No mission statements, no "passionate about", no invented team.
|
||||||
|
- Short sentences. The existing code comments in this repo are already written
|
||||||
|
this way; the prose should match.
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
**In:**
|
||||||
|
|
||||||
|
- `/about` — a coded page (not CMS-managed).
|
||||||
|
- `/blog` and `/blog/[slug]` — Payload-backed, with an index and post pages.
|
||||||
|
- Payload CMS installed into the existing Next application.
|
||||||
|
- Footer and navigation links to both.
|
||||||
|
- `Person`, `Organization`, `BlogPosting`, `BreadcrumbList` JSON-LD.
|
||||||
|
- RSS feed and sitemap integration.
|
||||||
|
- One first post, so the blog does not launch empty.
|
||||||
|
|
||||||
|
**Out (deliberately):**
|
||||||
|
|
||||||
|
- Rewriting existing homepage/how-it-works copy into first person. Worth doing,
|
||||||
|
but it would double the review surface of this PR. Separate change.
|
||||||
|
- In-product signed notes on school pages (the "distributed humanity" idea).
|
||||||
|
Revisit once About and the blog exist.
|
||||||
|
- Comments, newsletter, author accounts beyond one.
|
||||||
|
- A team page. There is no team.
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
### Topology
|
||||||
|
|
||||||
|
Payload 3 installs **into the existing Next application** and serves `/admin`
|
||||||
|
from the same container. One image, one deploy, no new service. This is
|
||||||
|
Payload 3's native model and it makes on-demand revalidation trivial, because
|
||||||
|
the CMS hooks run in the same process as the Next cache.
|
||||||
|
|
||||||
|
Accepted costs: the public site's image now carries Payload, so a CMS security
|
||||||
|
patch redeploys the whole site; and the image grows substantially.
|
||||||
|
|
||||||
|
### Two collisions that must be handled
|
||||||
|
|
||||||
|
**1. `/api` is already taken.** `app/api/[...path]/route.ts` is a catch-all that
|
||||||
|
proxies `/api/*` to FastAPI at runtime. Payload's default API route is also
|
||||||
|
`/api`. Left alone, these fight, and the failure is not clean — the catch-all
|
||||||
|
would swallow Payload's admin API calls and forward them to FastAPI.
|
||||||
|
|
||||||
|
Payload's API route is therefore remapped:
|
||||||
|
|
||||||
|
```ts
|
||||||
|
routes: { api: '/cms-api', admin: '/admin' }
|
||||||
|
```
|
||||||
|
|
||||||
|
with its route group at `app/(payload)/cms-api/[...slug]/route.ts`. The
|
||||||
|
`/cms-api` prefix must also be added to the FastAPI proxy's excluded-paths list
|
||||||
|
as a defensive second line.
|
||||||
|
|
||||||
|
**2. `next.config.js` is CommonJS.** Payload's `withPayload()` wrapper is ESM
|
||||||
|
only. The config must become `next.config.mjs`, converting `module.exports` to
|
||||||
|
`export default` and wrapping the export. All existing content — the standalone
|
||||||
|
output, `outputFileTracingIncludes`, the staging `X-Robots-Tag` header block,
|
||||||
|
the CSP — carries over unchanged. This is mechanical but it touches the file
|
||||||
|
that controls staging's noindex, so it needs care and an explicit test.
|
||||||
|
|
||||||
|
### Database
|
||||||
|
|
||||||
|
Payload uses the existing `sc_database` Postgres instance, in its **own
|
||||||
|
`payload` schema**:
|
||||||
|
|
||||||
|
```ts
|
||||||
|
db: postgresAdapter({
|
||||||
|
pool: { connectionString: process.env.DATABASE_URL },
|
||||||
|
schemaName: 'payload',
|
||||||
|
})
|
||||||
|
```
|
||||||
|
|
||||||
|
The frontend container is already on the `backend` Docker network, so it can
|
||||||
|
reach `sc_database:5432` with no networking change. It needs a new
|
||||||
|
`DATABASE_URL` environment variable.
|
||||||
|
|
||||||
|
Schema isolation is not cosmetic. `public` currently holds the application
|
||||||
|
tables and Airflow's metadata, and `scripts/migrate_csv_to_db.py --drop` exists
|
||||||
|
to drop and reimport. Blog content living in its own schema means no data
|
||||||
|
pipeline operation can destroy it. **Before implementation, confirm that
|
||||||
|
`--drop` is schema-scoped and cannot reach `payload`.**
|
||||||
|
|
||||||
|
Putting CMS tables in this instance is consistent with existing practice —
|
||||||
|
Airflow already stores its metadata there.
|
||||||
|
|
||||||
|
### Migrations
|
||||||
|
|
||||||
|
Payload's Postgres adapter auto-pushes schema in development and requires
|
||||||
|
explicit migrations in production. Use `prodMigrations`, which runs pending
|
||||||
|
migrations during server initialisation:
|
||||||
|
|
||||||
|
```ts
|
||||||
|
db: postgresAdapter({ /* ... */, prodMigrations: migrations })
|
||||||
|
```
|
||||||
|
|
||||||
|
This is preferred over a one-shot init container (the `airflow-init` pattern)
|
||||||
|
because the app is a single long-running process and there is no ordering
|
||||||
|
problem to solve. Migration files are generated with `payload migrate:create`
|
||||||
|
and committed, so schema changes travel through the same PR and staging gate as
|
||||||
|
code.
|
||||||
|
|
||||||
|
### Media
|
||||||
|
|
||||||
|
Uploads go to a Docker named volume, consistent with `postgres_data`,
|
||||||
|
`typesense_data` and `airflow_logs`.
|
||||||
|
|
||||||
|
- `staticDir` must be an **absolute** path in Payload 3: `/app/media`.
|
||||||
|
- The container runs as `nextjs` (uid 1001). The Dockerfile must
|
||||||
|
`mkdir -p /app/media && chown nextjs:nodejs /app/media` **before** the volume
|
||||||
|
is mounted, or Docker will create the mountpoint root-owned and every upload
|
||||||
|
will fail with EACCES.
|
||||||
|
- `sharp` moves from `devDependencies` to `dependencies` — Payload needs it at
|
||||||
|
runtime to generate `imageSizes`.
|
||||||
|
- The volume must be added to the backup routine alongside Postgres. A blog
|
||||||
|
post's images are not reproducible from the pipeline.
|
||||||
|
|
||||||
|
### Rendering
|
||||||
|
|
||||||
|
**Constraint:** CI builds the image with no database reachable. Blog pages
|
||||||
|
therefore cannot use build-time `generateStaticParams` — that would either fail
|
||||||
|
the build or bake in an empty post list.
|
||||||
|
|
||||||
|
Instead: ISR. Post and index pages declare a `revalidate` window and render on
|
||||||
|
first request, with Payload `afterChange` / `afterDelete` hooks calling
|
||||||
|
`revalidatePath('/blog')` and `revalidatePath('/blog/' + slug)` for immediate
|
||||||
|
publication. Because Payload runs in the same process, the hook calls
|
||||||
|
`revalidatePath` from `next/cache` directly — no webhook, no shared secret.
|
||||||
|
|
||||||
|
The ISR cache lives on container disk and is cleared by a redeploy. For a
|
||||||
|
single container serving a handful of posts this is fine.
|
||||||
|
|
||||||
|
### Collections
|
||||||
|
|
||||||
|
- **`posts`** — `title`, `slug`, `publishedAt`, `excerpt`, `heroImage`
|
||||||
|
(relation to `media`), `content` (Lexical rich text), `seo` group
|
||||||
|
(`metaTitle`, `metaDescription`), `_status` (drafts enabled).
|
||||||
|
- **`media`** — upload collection, `alt` required, `imageSizes` for thumbnail
|
||||||
|
and hero widths, public read access.
|
||||||
|
- **`users`** — Payload's auth collection. One account. Public creation
|
||||||
|
disabled.
|
||||||
|
|
||||||
|
Drafts are enabled so posts can be written over several sittings and previewed
|
||||||
|
before publication.
|
||||||
|
|
||||||
|
**Payload Blocks** are how posts embed live product components — a real trend
|
||||||
|
chart or comparison table inside a post, rendered from live data rather than
|
||||||
|
screenshotted. This is the main thing the CMS has to earn back against
|
||||||
|
file-based MDX, and it directly serves the goal: showing judgement in context.
|
||||||
|
Ship with one block (a callout/aside for "what this number doesn't tell you");
|
||||||
|
add a live-chart block once a post needs it.
|
||||||
|
|
||||||
|
### Security
|
||||||
|
|
||||||
|
`/admin` is the first authenticated surface on this site. Public, hardened:
|
||||||
|
|
||||||
|
- `PAYLOAD_SECRET` — long, random, set in the Portainer stack environment, never
|
||||||
|
committed. The same variable must exist in staging with a *different* value.
|
||||||
|
- Strong unique password on the single admin account.
|
||||||
|
- Login rate limiting via Payload's `maxLoginAttempts` / `lockTime`.
|
||||||
|
- `X-Robots-Tag: noindex, nofollow` on `/admin/*` and `/cms-api/*`, and a
|
||||||
|
`robots.ts` disallow. The admin panel must never be indexed.
|
||||||
|
- Public user creation disabled; no open registration.
|
||||||
|
- Verify the existing CSP `frame-ancestors` directive does not break the admin
|
||||||
|
panel.
|
||||||
|
|
||||||
|
Residual risk, accepted: a future Payload authentication CVE is live against the
|
||||||
|
public internet. Mitigation is prompt patching, which the staging→prod pipeline
|
||||||
|
already supports. If this becomes uncomfortable, restricting `/admin` at the
|
||||||
|
proxy to LAN/VPN is a one-line change later.
|
||||||
|
|
||||||
|
Staging note: staging runs the same image on `stx.`, so it gets its own admin
|
||||||
|
panel and its own database. It must have its own `PAYLOAD_SECRET` and its own
|
||||||
|
credentials — never production's.
|
||||||
|
|
||||||
|
## Deployment changes
|
||||||
|
|
||||||
|
- `nextjs-app/Dockerfile` — create and chown `/app/media`; ensure Payload's
|
||||||
|
admin bundle and `sharp` survive standalone output file tracing.
|
||||||
|
- `docker-compose.portainer.yml` and the staging equivalent — add
|
||||||
|
`DATABASE_URL` and `PAYLOAD_SECRET` to the `frontend` service, add a
|
||||||
|
`payload_media` volume mounted at `/app/media`, and add
|
||||||
|
`depends_on: sc_database`.
|
||||||
|
- Document both new environment variables in the compose header comment block,
|
||||||
|
which is where this stack records its configuration.
|
||||||
|
|
||||||
|
## SEO
|
||||||
|
|
||||||
|
- `Person` (Tudor, with photo) and `Organization` JSON-LD on `/about`.
|
||||||
|
- `BlogPosting` + `BreadcrumbList` on post pages, with `author` referencing the
|
||||||
|
same `Person`.
|
||||||
|
- Canonical URLs on `/blog` and every post.
|
||||||
|
- Posts and `/about` added to the existing sitemap (`app/sitemap.xml/route.ts`
|
||||||
|
and `app/sitemaps/[...parts]`). Post URLs come from Payload at request time.
|
||||||
|
- RSS feed at `/blog/rss.xml`.
|
||||||
|
- Footer links to both pages, under a new "About" column.
|
||||||
|
|
||||||
|
**Navigation is deliberately left alone.** `Navigation.tsx` renders a bottom tab
|
||||||
|
bar on mobile that already carries four items (Search, Compare, Rankings,
|
||||||
|
Admissions). A fifth tab makes each one cramped at 320px, and About and Blog are
|
||||||
|
both lower-intent than any of the four. Both live in the footer; About
|
||||||
|
additionally gets a byline link from every post, which is where a reader who
|
||||||
|
cares actually asks the question. Revisit only if analytics show people hunting
|
||||||
|
for it.
|
||||||
|
|
||||||
|
## Testing
|
||||||
|
|
||||||
|
Unit (Jest):
|
||||||
|
|
||||||
|
- Post rendering, including a post with no hero image and one with no excerpt.
|
||||||
|
- Slug generation and collision handling.
|
||||||
|
- JSON-LD shape for `BlogPosting` and `Person`.
|
||||||
|
- The `next.config.mjs` conversion preserves the staging `X-Robots-Tag` rule —
|
||||||
|
this guards the riskiest mechanical change in the plan.
|
||||||
|
|
||||||
|
E2E (Playwright, `e2e/`, required by CLAUDE.md for user-facing change):
|
||||||
|
|
||||||
|
- `/about` renders, shows the author name and photo, and is reachable from the
|
||||||
|
footer and nav.
|
||||||
|
- `/blog` lists at least one post; clicking through reaches the post.
|
||||||
|
- A post page renders title, date, body and byline.
|
||||||
|
- `/admin` responds with `noindex` and does not leak a stack trace when
|
||||||
|
unauthenticated.
|
||||||
|
|
||||||
|
Note the known constraint: new journeys cannot be proven in PR checks, because
|
||||||
|
the staging E2E gate runs post-merge.
|
||||||
|
|
||||||
|
## Risks
|
||||||
|
|
||||||
|
| Risk | Mitigation |
|
||||||
|
|---|---|
|
||||||
|
| `next.config.mjs` conversion silently drops the staging noindex header, making staging a crawlable duplicate | Unit test asserting the header rule; verify on staging before promotion |
|
||||||
|
| Payload API route collides with the FastAPI `/api` proxy | Remap to `/cms-api`; add to the proxy's exclusion list |
|
||||||
|
| Media volume mounts root-owned; all uploads fail with EACCES | `mkdir`+`chown` in the Dockerfile before the mount; test an upload on staging |
|
||||||
|
| Build fails or bakes empty content because CI has no DB | No build-time DB access; ISR only |
|
||||||
|
| A pipeline `--drop` destroys blog content | Separate `payload` schema; verify `--drop` blast radius before building |
|
||||||
|
| Media volume not backed up; images unrecoverable | Add `payload_media` to the backup routine |
|
||||||
|
| Payload auth CVE exposed publicly | Prompt patching; proxy restriction available as a fallback |
|
||||||
|
| Blog launches empty or goes stale | Ship with one post; cadence is explicitly "a few times a year", so no cadence is promised anywhere on the page — no dates implying a schedule |
|
||||||
|
|
||||||
|
## Sequence
|
||||||
|
|
||||||
|
Each step is independently reviewable and mergeable.
|
||||||
|
|
||||||
|
1. **Payload foundation** — install, `next.config.mjs` conversion, `payload`
|
||||||
|
schema, `/cms-api` remap, `users` collection, `/admin` hardening, compose and
|
||||||
|
Dockerfile changes. No public-facing change yet. Verify on staging that the
|
||||||
|
site is unchanged and `/admin` works.
|
||||||
|
2. **`/about`** — coded page, photo, `Person`/`Organization` JSON-LD, footer and
|
||||||
|
nav links, e2e journey. Independently valuable and does not depend on the
|
||||||
|
blog.
|
||||||
|
3. **Blog** — `posts` and `media` collections, `/blog` index and post pages, ISR
|
||||||
|
plus revalidation hooks, RSS, sitemap, structured data, e2e journeys.
|
||||||
|
4. **First post** — written in the admin panel, published through the normal
|
||||||
|
flow, proving the whole path end to end.
|
||||||
|
|
||||||
|
Step 1 carries all the infrastructure risk and none of the visible benefit, so
|
||||||
|
it should be verified on staging carefully before step 2 starts.
|
||||||
|
|
||||||
|
## Dependencies on Tudor
|
||||||
|
|
||||||
|
- **A photograph.** Blocks step 2. Nothing else in the plan is blocked by it.
|
||||||
|
- **The first post's subject.** Blocks step 4 only. Suggested: what school
|
||||||
|
performance data cannot tell you — it demonstrates judgement, is genuinely
|
||||||
|
useful, and is the kind of thing an anonymous or machine-written site will not
|
||||||
|
publish.
|
||||||
|
- **Confirmation** that `scripts/migrate_csv_to_db.py --drop` is schema-scoped.
|
||||||
Reference in new issue
Block a user