Move to single .env file

2026-03-27 16:43:22 -05:00
parent 57bcb2474f
commit 4b157b9831
41 changed files with 13337 additions and 54 deletions
--- a/docs/payload-cms.md
+++ b/docs/payload-cms.md
@@ -0,0 +1,653 @@
+# Payload CMS In St Pete IT
+
+This document explains how Payload CMS is integrated into the repo, how the landing and
+service pages work, how to add new Payload-managed pages, and how to migrate existing
+hardcoded pages into the current block-based setup.
+
+## What Payload Is Responsible For
+
+Payload currently manages the editable marketing content layer inside the Next.js app.
+That means:
+
+- the landing page at `/`
+- the contact page at `/contact`
+- the service pages at `/services/[slug]`
+- shared marketing settings in the `site-settings` global
+- the admin UI at `/admin`
+- the REST API under `/api`
+- live preview and route refresh when editors save or publish changes
+
+Payload is not replacing Convex. Convex still handles the product backend: auth,
+tickets, invoices, appointments, portal data, and admin operations. Payload only owns
+the CMS side for page content.
+
+## High-Level Architecture
+
+### Core config
+
+Payload is configured in `apps/next/src/payload.config.ts`.
+
+Important pieces there:
+
+- `postgresAdapter(...)` points Payload at Postgres through `PAYLOAD_DB_URL`
+- `secret: env.PAYLOAD_SECRET` enables Payload auth/session security
+- `collections: [Media, Pages]` registers the current CMS collections
+- `globals: [SiteSettings]` registers shared settings
+- `admin.livePreview` enables live preview for the `pages` collection
+- `typescript.outputFile` writes generated types to `apps/next/payload-types.ts`
+
+### Collections and globals
+
+Current CMS entities:
+
+- `pages` in `apps/next/src/payload/collections/pages.ts`
+  - stores both the landing page and service pages
+  - uses `pageType` to distinguish `landing` vs `service`
+  - stores block layout in `layout`
+  - stores SEO fields in `seo`
+  - stores service-specific structured data in `structuredData`
+- `media` in `apps/next/src/payload/collections/media.ts`
+  - image uploads used by blocks and SEO
+- `site-settings` in `apps/next/src/payload/globals/site-settings.ts`
+  - shared business info and service-page CTA settings
+
+### Block system
+
+Payload page content is built from reusable blocks.
+
+Schema side:
+
+- `apps/next/src/payload/blocks/*.ts`
+- exported via `apps/next/src/payload/blocks/index.ts`
+
+Render side:
+
+- `apps/next/src/components/payload/blocks/*.tsx`
+- selected by `apps/next/src/components/payload/blocks/render-blocks.tsx`
+
+The rule is simple: every Payload block needs both parts.
+
+- schema block: defines the fields editors can fill in
+- renderer block: turns that block data into frontend UI
+
+If one side is missing, the admin or the frontend will be incomplete.
+
+### Frontend route flow
+
+Landing page route:
+
+- `apps/next/src/app/(frontend)/page.tsx`
+
+Contact page route:
+
+- `apps/next/src/app/(frontend)/contact/page.tsx`
+
+Service page route:
+
+- `apps/next/src/app/(frontend)/services/[slug]/page.tsx`
+
+Shared server fetch helpers:
+
+- `apps/next/src/lib/payload-helpers.tsx`
+
+Behavior:
+
+1. the route calls `getPageBySlug(...)`
+2. Payload fetches the matching `pages` document
+3. the page metadata is generated from `seo` / fallback values
+4. the page content is rendered through `LivePreviewPage`
+5. `LivePreviewPage` uses Payload live preview to update content in the editor iframe
+6. `RefreshRouteOnSave` refreshes the route after save/publish so server-rendered data
+   stays in sync
+
+### Live preview and publish behavior
+
+There are two cooperating pieces:
+
+- `apps/next/src/components/payload/live-preview-page.tsx`
+  - subscribes to Payload live preview messages with `useLivePreview`
+- `apps/next/src/components/payload/refresh-route-on-save.tsx`
+  - refreshes the current route after document saves/publishes
+
+Important requirement:
+
+- `src/proxy.ts` and `src/lib/proxy/ban-sus-ips.ts` must not block valid Payload REST API
+  requests under `/api`
+
+That was a real bug during setup: `PATCH` requests to publish pages were being blocked by
+the suspicious-method middleware until `/api` writes were explicitly allowed.
+
+## Seeded Content
+
+Payload content is seeded from:
+
+- `apps/next/src/payload/seed/landing-page.ts`
+- `apps/next/src/payload/seed/service-pages.ts`
+- `apps/next/src/payload/seed/index.ts`
+
+Run the seed with:
+
+```bash
+cd apps/next
+bun run seed
+```
+
+What it does:
+
+- updates `site-settings`
+- creates or updates the `home` landing page
+- creates or updates the `contact` page
+- creates or updates the default service pages
+
+This matters because a fresh Payload database will otherwise return no page documents and
+the frontend route will 404.
+
+## Environment Variables
+
+Payload depends on these env vars:
+
+- `PAYLOAD_SECRET`
+- `PAYLOAD_DB_URL`
+- `NEXT_PUBLIC_SITE_URL`
+
+Why they matter:
+
+- `PAYLOAD_SECRET` secures Payload sessions and server behavior
+- `PAYLOAD_DB_URL` connects Payload to Postgres
+- `NEXT_PUBLIC_SITE_URL` is used by live preview to target the frontend correctly
+
+If live preview points to the wrong place, or publish/save requests appear to work but the
+preview never updates, this is one of the first things to check.
+
+## How To Create A New Page Like The Current Ones
+
+This section assumes you want another page managed by the existing `pages` collection.
+
+### Option A: Create a new service page using the existing system
+
+This is the simplest case.
+
+1. Open Payload admin at `/admin`
+2. Go to the `Pages` collection
+3. Create a new document
+4. Set:
+   - `title`
+   - `slug`
+   - `pageType = service`
+5. Build the `layout` using the existing blocks
+6. Fill in `seo`
+7. Fill in `structuredData.serviceName` and `structuredData.serviceDescription`
+8. Save draft or publish
+9. Visit `/services/<slug>`
+
+Why this works without adding a new route:
+
+- the app already has a dynamic route at `apps/next/src/app/(frontend)/services/[slug]/page.tsx`
+- any `pages` doc with `pageType: 'service'` and a matching slug can render there
+
+If the page should exist by default in new environments, also add it to
+`apps/next/src/payload/seed/service-pages.ts`.
+
+### Option B: Create another landing-style page with the same block approach
+
+If the page is not a service page, decide whether it belongs:
+
+- in the existing `pages` collection with a new route, or
+- in a new Payload collection if the content model is materially different
+
+If it fits `pages`:
+
+1. add or reuse blocks in the `layout`
+2. create the frontend route that fetches the document by slug
+3. generate metadata from the document
+4. render the layout with `LivePreviewPage`
+5. include `RefreshRouteOnSave`
+
+Example pattern:
+
+```tsx
+const page = await getPageBySlug('some-slug');
+
+if (!page) return notFound();
+
+return (
+  <main>
+    <RefreshRouteOnSave serverURL={env.NEXT_PUBLIC_SITE_URL} />
+    <LivePreviewPage page={page} serverURL={env.NEXT_PUBLIC_SITE_URL} />
+  </main>
+);
+```
+
+## Copy-Paste Route Template
+
+Use this when creating a new non-service Payload-backed page route.
+
+Adjust these parts:
+
+- the slug passed to `getPageBySlug(...)`
+- the metadata fallback values
+- any JSON-LD you want to inject
+
+```tsx
+import type { Metadata } from 'next';
+import { notFound } from 'next/navigation';
+import Script from 'next/script';
+import { LivePreviewPage } from '@/components/payload/live-preview-page';
+import { RefreshRouteOnSave } from '@/components/payload/refresh-route-on-save';
+import { env } from '@/env';
+import { generatePageMetadata } from '@/lib/metadata';
+import { getPageBySlug } from '@/lib/payload-helpers';
+import { jsonLd } from '@/lib/structured-data';
+
+export const generateMetadata = async (): Promise<Metadata> => {
+  const page = await getPageBySlug('some-slug');
+
+  if (!page) {
+    return generatePageMetadata({
+      title: 'Fallback Title',
+      description: 'Fallback description.',
+      path: '/some-path',
+    });
+  }
+
+  return generatePageMetadata({
+    title: page.seo?.metaTitle ?? page.title,
+    description: page.seo?.metaDescription ?? 'Fallback description.',
+    path: '/some-path',
+    keywords: page.seo?.keywords?.filter(Boolean) as string[] | undefined,
+    noIndex: page.seo?.noIndex ?? false,
+  });
+};
+
+const SomePage = async () => {
+  const page = await getPageBySlug('some-slug');
+
+  if (!page) return notFound();
+
+  return (
+    <main>
+      <RefreshRouteOnSave serverURL={env.NEXT_PUBLIC_SITE_URL} />
+      <Script
+        id='ld-json-some-page'
+        type='application/ld+json'
+        dangerouslySetInnerHTML={{
+          __html: jsonLd({ '@context': 'https://schema.org' }),
+        }}
+      />
+      <LivePreviewPage page={page} serverURL={env.NEXT_PUBLIC_SITE_URL} />
+    </main>
+  );
+};
+
+export default SomePage;
+```
+
+If the page does not need JSON-LD, remove the `Script` import and block.
+
+For service pages, do not create a separate static route unless there is a strong reason.
+Prefer the existing dynamic route at `apps/next/src/app/(frontend)/services/[slug]/page.tsx`.
+
+## Copy-Paste Block Template
+
+Use this when you need a new reusable Payload block for a page migration.
+
+Schema file example:
+
+```ts
+import type { Block } from 'payload';
+
+export const ExampleBlock: Block = {
+  slug: 'exampleBlock',
+  labels: {
+    singular: 'Example Block',
+    plural: 'Example Blocks',
+  },
+  fields: [
+    {
+      name: 'title',
+      type: 'text',
+      required: true,
+    },
+    {
+      name: 'description',
+      type: 'textarea',
+    },
+    {
+      name: 'items',
+      type: 'array',
+      fields: [
+        {
+          name: 'label',
+          type: 'text',
+          required: true,
+        },
+      ],
+    },
+  ],
+};
+```
+
+Renderer example:
+
+```tsx
+import type { Page } from '../../../../payload-types';
+
+type ExampleBlockData = Extract<
+  NonNullable<Page['layout']>[number],
+  { blockType: 'exampleBlock' }
+>;
+
+export const ExampleBlockRenderer = ({
+  block,
+}: {
+  block: ExampleBlockData;
+}) => {
+  return (
+    <section>
+      <h2>{block.title}</h2>
+      {block.description && <p>{block.description}</p>}
+      <ul>
+        {block.items?.map((item) => (
+          <li key={item.id}>{item.label}</li>
+        ))}
+      </ul>
+    </section>
+  );
+};
+```
+
+Registration checklist:
+
+1. export the schema block from `apps/next/src/payload/blocks/index.ts`
+2. add the block to `apps/next/src/payload/collections/pages.ts`
+3. add the renderer to `apps/next/src/components/payload/blocks/render-blocks.tsx`
+4. regenerate `apps/next/payload-types.ts`
+
+Type generation command:
+
+```bash
+cd apps/next
+bun with-env bunx payload generate:types --config src/payload.config.ts
+```
+
+## Copy-Paste Seed Template
+
+Use this when a new Payload-backed page should exist automatically in local/dev or fresh
+environments.
+
+Seed document example:
+
+```ts
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const examplePageSeed: Record<string, any> = {
+  title: 'Example Page',
+  slug: 'example',
+  pageType: 'standard',
+  layout: [
+    {
+      blockType: 'exampleBlock',
+      title: 'Hello from Payload',
+    },
+  ],
+  seo: {
+    metaTitle: 'Example Page',
+    metaDescription: 'Example description.',
+    noIndex: false,
+  },
+  _status: 'published',
+};
+```
+
+Seed upsert example:
+
+```ts
+const existing = await payload.find({
+  collection: 'pages',
+  where: { slug: { equals: 'example' } },
+  limit: 1,
+});
+
+if (existing.docs.length > 0) {
+  await payload.update({
+    collection: 'pages',
+    id: existing.docs[0]!.id,
+    draft: false,
+    data: examplePageSeed as never,
+  });
+} else {
+  await payload.create({
+    collection: 'pages',
+    draft: false,
+    data: examplePageSeed as never,
+  });
+}
+```
+
+The important part is not the exact code shape. The important part is that a new
+Payload-backed route should not depend on manually created admin content if the page is
+expected to exist in every environment.
+
+## How To Add A New Block
+
+If editors need a new section type, add a new block.
+
+### 1. Create the Payload schema block
+
+Add a file under:
+
+- `apps/next/src/payload/blocks/<block-name>.ts`
+
+This file defines the editor-facing fields.
+
+### 2. Export it from the block barrel
+
+Update:
+
+- `apps/next/src/payload/blocks/index.ts`
+
+### 3. Register it in the `pages` collection
+
+Update:
+
+- `apps/next/src/payload/collections/pages.ts`
+
+Add the block to the `layout.blocks` array.
+
+### 4. Build the frontend renderer
+
+Add:
+
+- `apps/next/src/components/payload/blocks/<block-name>.tsx`
+
+### 5. Register the renderer
+
+Update:
+
+- `apps/next/src/components/payload/blocks/render-blocks.tsx`
+
+### 6. Seed it if needed
+
+If the new block is used in default pages, update the seed files too.
+
+## How To Migrate An Existing Hardcoded Page To Payload CMS
+
+This is the full workflow for converting an old React page into the current CMS model.
+
+### Step 1: Audit the existing page
+
+Identify all of these before touching code:
+
+- route path
+- metadata and title
+- structured data / JSON-LD
+- hero section
+- repeated content sections
+- CTA areas
+- any shared content that should become global settings
+
+Do not start by blindly copying JSX into one giant rich text field. The current system is
+block-based for a reason.
+
+### Step 2: Break the page into reusable sections
+
+Ask which parts are:
+
+- already represented by existing blocks
+- better suited as a new reusable block
+- global content instead of page-local content
+
+Examples:
+
+- hero section -> `landingHero` or `serviceHero`
+- card rows -> `cardGrid`
+- comparisons -> `tabularComparison` or `twoColumnComparison`
+- FAQ -> `faq`
+- pricing -> `pricingCards`
+
+### Step 3: Create new blocks if the page needs them
+
+If the existing block library is not enough:
+
+1. add a schema block in `apps/next/src/payload/blocks/`
+2. add a renderer in `apps/next/src/components/payload/blocks/`
+3. register both sides
+
+Keep blocks composable and editor-friendly. Prefer a few clearly named fields over one big
+opaque content blob.
+
+### Step 4: Move SEO into document fields
+
+Map metadata into the Payload document:
+
+- title -> `seo.metaTitle` or route fallback
+- meta description -> `seo.metaDescription`
+- keywords -> `seo.keywords`
+- noindex -> `seo.noIndex`
+- service-specific schema -> `structuredData`
+
+If the page uses JSON-LD, keep the generation logic in the route and read values from the
+Payload document.
+
+### Step 5: Replace the hardcoded route with a Payload-backed route
+
+The route should:
+
+1. fetch the page with `getPageBySlug`
+2. return `notFound()` if it does not exist
+3. generate metadata from the doc
+4. render `RefreshRouteOnSave`
+5. render JSON-LD with `next/script` if needed
+6. render `LivePreviewPage`
+
+For service pages, prefer reusing the dynamic service route instead of creating many
+one-off route files.
+
+### Step 6: Seed the migrated page
+
+If the page should exist locally or in fresh environments, add it to the seed system.
+
+This prevents the common failure mode where the route now expects Payload content but the
+database has no corresponding document yet.
+
+### Step 7: Verify the full editor flow
+
+After migration, verify all of these:
+
+- the route loads without 404
+- the document appears in `/admin`
+- draft save works
+- publish works
+- live preview updates while editing
+- route refreshes after save/publish
+- dark/light preview styling still looks correct
+- seeded content loads on a fresh database
+
+### Step 8: Delete the old hardcoded page only after verification
+
+Do not remove the old page implementation until the Payload-backed route is proven working.
+
+For the service-page migration in this repo, the safe order was:
+
+1. create Payload collection and blocks
+2. add frontend readers and renderers
+3. seed the docs
+4. verify save/publish/live preview
+5. remove the old hardcoded service page files
+
+That order avoids breaking the site in the middle of the migration.
+
+## Recommended Checklist For Future Migrations
+
+Use this exact order:
+
+1. model the content shape
+2. add or reuse blocks
+3. add renderers
+4. register blocks in the collection
+5. wire the route to Payload
+6. move metadata and structured data
+7. seed the content
+8. verify preview and publish
+9. remove old hardcoded components/routes
+
+## Common Failure Modes
+
+### 1. Page 404s after migration
+
+Usually means the Payload document does not exist yet.
+
+Check:
+
+- the route slug
+- the document slug
+- whether the seed ran
+
+### 2. Publish/save shows `Not Found`
+
+Usually means middleware or proxy rules are intercepting Payload API writes before they
+reach Payload.
+
+Check:
+
+- `apps/next/src/proxy.ts`
+- `apps/next/src/lib/proxy/ban-sus-ips.ts`
+
+### 3. Live preview frame loads but does not update
+
+Usually means one of these is wrong:
+
+- `NEXT_PUBLIC_SITE_URL`
+- Payload live preview config URL
+- missing `useLivePreview` on the frontend page
+- missing `RefreshRouteOnSave`
+
+### 4. Dark mode preview looks wrong
+
+Usually means the theme classes or body-level theme tokens are not being applied inside the
+preview iframe.
+
+Check the frontend layout and ensure `bg-background` / `text-foreground` are applied at the
+body level.
+
+## Important Files At A Glance
+
+- config: `apps/next/src/payload.config.ts`
+- page collection: `apps/next/src/payload/collections/pages.ts`
+- media collection: `apps/next/src/payload/collections/media.ts`
+- global settings: `apps/next/src/payload/globals/site-settings.ts`
+- block schemas: `apps/next/src/payload/blocks/*`
+- block renderers: `apps/next/src/components/payload/blocks/*`
+- route helpers: `apps/next/src/lib/payload-helpers.tsx`
+- landing route: `apps/next/src/app/(frontend)/page.tsx`
+- contact route: `apps/next/src/app/(frontend)/contact/page.tsx`
+- service route: `apps/next/src/app/(frontend)/services/[slug]/page.tsx`
+- live preview client bridge: `apps/next/src/components/payload/live-preview-page.tsx`
+- save/publish refresh bridge: `apps/next/src/components/payload/refresh-route-on-save.tsx`
+- seed entrypoint: `apps/next/src/payload/seed/index.ts`
+
+## Practical Rule Of Thumb
+
+If the change is about editable marketing content, reach for Payload first.
+
+If the change is about business logic, authenticated workflows, tickets, invoices,
+appointments, or portal/admin operations, it probably belongs in Convex instead.