Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
d27b5be
refactor(app): move site routes into frontend route group
maxitect Nov 12, 2026
5d95aaa
chore(neon): ignore local project link file
maxitect Nov 12, 2026
bbbbb1e
docs(database): add rules for payload collections and migrations
maxitect Nov 12, 2026
5307b05
docs(skills): add payload-collection skill
maxitect Nov 12, 2026
02fdd33
docs(tickets): point to neon project and payload-collection skill
maxitect Nov 12, 2026
55ca6eb
chore(git): ignore session handover log
maxitect Nov 12, 2026
bf08ee2
docs(database): correct payload storage claims and align rules with s…
maxitect Nov 12, 2026
300b170
docs(tickets): describe neon branches, preview variables and db proof
maxitect Nov 12, 2026
8bd60ba
feat(data): add cached readers for sheet content
maxitect Nov 12, 2026
d2c9ab7
feat(pages): read sheet content on the server and pass it as props
maxitect Nov 12, 2026
001183e
refactor(routes): reuse cached readers in sitemap, llms.txt and markd…
maxitect Nov 12, 2026
753ec9d
feat(config): enable cache components and read the sheet url server-side
maxitect Nov 12, 2026
53f14f6
ci(github): pass the sheet url to the build
maxitect Nov 12, 2026
d4ec217
fix(tour): build and format gig dates in utc
maxitect Nov 12, 2026
39978c1
fix(layout): render the footer on the server with a cached year
maxitect Nov 12, 2026
71e4976
fix(data): reject non-csv sheet replies and time out slow reads
maxitect Nov 12, 2026
f8361ee
docs(readme): rename sheet variable and update frontend paths
maxitect Nov 12, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
90 changes: 90 additions & 0 deletions .claude/rules/database.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
---
paths:
- "src/collections/**"
- "src/payload.config.ts"
- "src/migrations/**"
---

# Database Rules

Payload generates the Postgres schema from the collection config in `src/collections/`. The schema is designed by choosing fields, not by writing tables. These rules are non-negotiable. A PR that breaks one is rejected.

## Ownership

- **Payload owns** the `payload_*` tables (`payload_migrations`, `payload_preferences`, `payload_locked_documents`, `payload_kv` and their `_rels`), `users_sessions`, and the `id`, `created_at` and `updated_at` columns on every table. Never write to them, alter them or query them from site code. They hold `jsonb` and generic `_rels` joins; that is Payload's business and exempt from the rules below.
- **We own** every collection: its fields, names, constraints and access.
- Read and write through Payload's local API (`getPayload`, `payload.find`). Reach for `payload.db.drizzle` only for a query the local API cannot express, and say why in the PR.

## Normalisation

- **3NF.** Every field depends on the document it sits on, the whole document and nothing but the document.
- **Don't store anything derivable.** Whether a tour date is past or upcoming comes from `eventDate` at render time. An embed URL comes from the stored ID. Never add a field the page can compute.
- **Atomic columns only.** These field types are banned in our collections:
- `json`: one `jsonb` column.
- `richText`: Lexical state, one `jsonb` column. Use `textarea` for multi-line copy and lyrics.
- `blocks`: one table per block type hanging off one field, a polymorphic list. Never set `blocksAsJSON` on the adapter either.
- `point`: a PostGIS `geometry` column holding two values.
- `hasMany` on `text` or `number`: stored in generic `<collection>_texts` and `<collection>_numbers` tables keyed by a text `path`. Use an `array`.
- Any delimited or encoded text (no "a,b,c" in a `text` field).
- **Repeating data** is an `array` field. Payload stores it as a child table `<collection>_<field>` keyed by parent and order, with a real foreign key.
- **Controlled redundancy** is allowed only when the database keeps it consistent, through a constraint or trigger in a hand-written migration. Site code never syncs a redundant value. Every case goes in the register at the end of this file.

## Relationships

- **No polymorphic relationships.** `relationTo` is always one collection slug, never an array.
- **No `hasMany` on `relationship` or `upload` fields.** Payload stores those in a generic `<collection>_rels` table with one nullable column per target and a text `path`, so nothing guarantees a row points where the field says. For many-to-many, use an `array` field holding one single `relationship`, or a join collection with two single relationships.
- A single `relationship` or `upload` becomes a `<field>_id` column with a foreign key. That is the only shape we use.
- Check the generated migration: a `_rels`, `_texts` or `_numbers` table for one of our collections means a rule was broken.

## Languages

- The site is English and French. Translatable text uses Payload localisation: `localization: { locales: ['en', 'fr'], defaultLocale: 'en', fallback: true }` in the config and `localized: true` on the field. Payload moves those columns to `<collection>_locales`, one row per document per locale.
- Never pair fields by language (`titleEn` and `titleFr`, `lyrics` and `paroles`).
- Language-neutral data stays unlocalised: dates, URLs, venue and city names, embed IDs, images.
- Read with the visitor's locale and `fallbackLocale: 'en'`.

## Enums, lookups and checks

- A fixed option set that carries only a name is a `select` field. Payload creates a Postgres enum `enum_<collection>_<field>`; changing the options needs a migration. `hasMany` on a `select` is fine: it becomes a child table of enum values.
- A lookup is its own collection, and only when the options carry extra attributes or editors must add options without a deploy. State the reason in the PR.
- `required`, `unique` and `index` on a field become `NOT NULL`, a unique index and an index. Use them; they are the first line of integrity.
- Two cases drop the `NOT NULL` silently: a collection with `versions.drafts` on (every required column becomes nullable, because a draft may be incomplete) and a required field with `admin.condition`. Don't put `admin.condition` on a required field. Turning drafts on is a departure: record it in the register.
- Numeric ranges and cross-field rules that must hold for direct SQL too go in a `CHECK` constraint in a hand-written migration. Rules that only shape editor input go in the field's `validate`.

## Naming

- Collection slugs are plural kebab-case (`tour-dates`); Payload snake-cases them for tables. Field names are camelCase.
- Don't set `dbName` unless a generated name exceeds Postgres's 63 characters.
- IDs are Payload's default serial integers. Don't switch `idType` once data exists.

## Access

- Every collection declares `access.read` explicitly, so who can read it is visible in the file. Payload's access functions are the only row-level security here.
- `read: () => true` only for content the public site shows; otherwise `read: ({ req }) => Boolean(req.user)`. Leave `create`, `update` and `delete` unset: Payload's default is signed-in users only.
- The `users` collection is never publicly readable.

## Migrations

- `src/migrations/` is written by `pnpm exec payload migrate:create <concern>` and applied by `pnpm exec payload migrate`. One concern per migration.
- Read the generated SQL before committing it. Reject `jsonb` and `geometry` columns and `_rels`, `_texts` and `_numbers` tables on our collections.
- Hand-written SQL (triggers, functions, `CHECK` constraints, partial indexes) goes in its own blank migration: `pnpm exec payload migrate:create <concern> --force-accept-warning`, run when no config change is pending (otherwise the file is not blank). Never mix it into a generated one. The one exception is a rename: Payload generates a drop and an add, which loses data, so replace those statements with `ALTER TABLE … RENAME` in the generated file and say so in the PR. Payload's generator does not know these objects exist, so a later rename can orphan them: list each one in the register below.
- Never edit a migration after it has merged. A migration must work with the previous deploy still running.
- `pnpm dev` pushes the schema straight to whatever `DATABASE_URL` points at. `.env.local` must point at the Neon `dev` branch, never `preview` or `main`. Those two change only through `payload migrate`.
- `src/payload-types.ts` and `src/app/(payload)/admin/importMap.js` are generated. Regenerate (`payload generate:types`, `payload generate:importmap`); never hand-edit. The other files in `src/app/(payload)/` were copied in once from Payload's template and are left alone, except `custom.scss`, which is ours to edit. Derive every content type in site code from `payload-types.ts`.

## Uploads

- Files live in Neon Object Storage through `@payloadcms/storage-s3`; the `media` table holds the key and metadata, never the bytes.
- Storage branches with the database. A file uploaded on `preview` does not exist on `main`.

## Proof

There is no test framework. Every constraint, trigger and hand-written index is proven on the Neon `preview` branch with SQL (the `db` method in `docs/tickets/INSTRUCTIONS.md` §3), after `payload migrate` has applied it there: show that valid data passes and that the misuse it guards against fails. The `dev` branch cannot be used for this: it only ever receives dev-mode pushes, so migrations never run on it.

## Register of departures

Every denormalisation, banned field type used anyway, and hand-written database object, with its reason and the migration that holds it.

| Object | Kind | Reason | Migration |
| --- | --- | --- | --- |
| None yet | | | |
80 changes: 80 additions & 0 deletions .claude/skills/payload-collection/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
---
name: payload-collection
description: Add or change a Payload collection end to end (config, generated types, migration, proof on a Neon branch) following .claude/rules/database.md. Use when adding a collection, adding, renaming or removing a field, or writing a hand-made constraint or trigger.
---

# Payload Collection

Changes one collection in `src/collections/`, following `.claude/rules/database.md`. Start from the nearest existing collection (`TourDates.ts` for content, `Media.ts` for uploads) for layout, but the rules win wherever an existing file differs from them: the first collections were written for a spike, before the rules.

Every Neon command needs the Tandem profile: `export NEON_PROFILE=tandem`. The `--profile` flag alone is not enough for project-scoped commands.

## 0. Read first

- `.claude/rules/database.md`, all of it.
- The Payload docs for each field type you plan to use, through context7 (`/websites/payloadcms`). Field options change between minor versions.
- `pnpm dev` pushes the schema to whatever `DATABASE_URL` in `.env.local` points at, and that must be the Neon `dev` branch. Check without printing a value: `grep -c '^NEON_BRANCH="\?dev"\?$' .env.local` must print `1`. If it prints `0`, run `neon checkout dev`, which rewrites the Neon variables in `.env.local`.
- The admin logins for `dev` and `preview` are not in the repo. `PROMPT.md` (not committed) says where they are; if it doesn't, ask the user. Never reset a branch or a password to get in.

## 1. Design

For each piece of data, decide before writing config:

1. Is it derivable? Then it is not a field.
2. Is it translatable text? Then `localized: true`. Dates, URLs, names of places and IDs are not.
3. Does it repeat? Then an `array` field, never delimited text.
4. Does it point at another document? Then one `relationship` or `upload` with a single `relationTo` and no `hasMany`.
5. Is it one of a fixed set? Then `select`.

If the answer needs `json`, `richText`, `blocks`, `point`, a polymorphic `relationTo`, or `hasMany` on a relationship, upload, text or number field, stop and ask. A yes goes in the register in `database.md`.

## 2. Config

1. Write or edit `src/collections/<Name>.ts`: export a `CollectionConfig` with a plural kebab-case `slug`, `admin.useAsTitle`, explicit `access`, and the fields with `required`, `unique` and `index` set where they hold.
2. A new collection is added to `collections` in `src/payload.config.ts`. An upload collection that stores files is also added to the `s3Storage` plugin's `collections`.
3. Run `pnpm exec payload generate:types`. Run `pnpm exec payload generate:importmap` if the admin gained a custom component.

## 3. Try it on `dev`

1. `pnpm dev --port <4000 + issue number>`. Dev mode pushes the schema to the `dev` branch.
- A change that removes or renames a field makes the push stop and ask `Accept warnings and push schema to database?` in the terminal. A background server then hangs on its first request. For such a change, read the server output for the prompt, tell the user what would be dropped, and run the server in the foreground to answer it only once they agree.
2. In `/admin`, create, edit and delete a document. Read the dev server output for errors.
3. Stop the server by port.

## 4. Migration

1. `pnpm exec payload migrate:create <concern>`.
2. Read the generated SQL in `src/migrations/`. It must contain no `jsonb` or `geometry` column and no `_rels`, `_texts` or `_numbers` table for our collections, and each relationship must be a `<field>_id` column with a foreign key.
3. A rename shows up as drop and add, which loses data. Write the `ALTER TABLE … RENAME` by hand in that migration instead and say so in the PR.

## 5. Hand-written objects

Only when a rule must hold for direct SQL too.

1. With no config change pending, `pnpm exec payload migrate:create <concern> --force-accept-warning` writes a blank migration. Put the SQL in `up` and its reverse in `down`, using `db.execute(sql\`…\`)`.
2. Functions set `search_path` explicitly and are not `SECURITY DEFINER` unless they must be.
3. Add the object to the register in `database.md`.

## 6. Apply to `preview` and prove

1. Pull the `preview` branch's variables to a file outside the working tree: `neon env pull --branch preview --file .git/ticket/<issue number>/artefacts/preview.env`. Never print it.
2. Load that file into a subshell and check the target before migrating. Payload's CLI reads `.env.local` by itself, so if the file fails to load, the command silently runs against `dev`:

```bash
(set -a; . .git/ticket/<issue number>/artefacts/preview.env; set +a
echo "$NEON_BRANCH" # must print: preview
pnpm exec payload migrate:status
pnpm exec payload migrate)
```
3. Prove with SQL through `neon psql preview -- -Atc "<query>"`: the table and columns exist, valid data passes, and each constraint rejects what it guards against. Keep the output for the PR.
4. After the PR's deploy preview is ready, create a document in the preview's admin and load the page that shows it.

## 7. Production

Never run a migration against `main`. List the step in the PR's notes for the user: `payload migrate` against the `main` branch, and any environment variable the change needs.

## 8. Using the content

- Server components read with `getPayload({ config })` and `payload.find`, passing the visitor's locale and `fallbackLocale: 'en'`.
- Types come from `src/payload-types.ts`. Never write a type by hand for collection data.
- With `cacheComponents` on, a read is either inside `"use cache"` with a `cacheTag`, or inside `<Suspense>` after `await connection()`. Invoke `vercel:next-cache-components` first.
2 changes: 2 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -17,3 +17,5 @@ jobs:
- run: pnpm lint
- run: pnpm typecheck
- run: pnpm build
env:
SHEET_CSV_URL: ${{ vars.SHEET_CSV_URL }}
4 changes: 4 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -43,3 +43,7 @@ next-env.d.ts

# netlify
.netlify
.neon

# session handover log
PROMPT.md
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,7 @@ Create a `.env.local` file in the root directory:

```bash
# Google Sheets Configuration
NEXT_PUBLIC_CSV_URL=https://docs.google.com/spreadsheets/d/[SHEET_ID]/export?format=csv
SHEET_CSV_URL=https://docs.google.com/spreadsheets/d/[SHEET_ID]/export?format=csv

# Site Configuration
NEXT_PUBLIC_SITE_URL=https://clarksbowlingclub.com
Expand Down
Loading
Loading