# Payload CMS

Payload is embedded in `apps/next` and manages marketing content. Convex remains
the application backend for auth, realtime data, files, and workflows.

Configuration lives in `apps/next/src/payload.config.ts`. Payload uses
`PAYLOAD_SECRET`, `PAYLOAD_DB_URL`, and `NEXT_PUBLIC_SITE_URL` from the validated
environment contract. Local `dev` values come from Infisical and point Payload
to Postgres at `localhost:5432`, because Next runs on the host.

Start the isolated services with `bun db:up`, then run `bun dev:next`. The local
database persists across `bun db:down`; `bun db:down:wipe` removes it. Local
Convex data is stored in a separate volume and Convex does not receive
`POSTGRES_URL` by default.

To refresh the local seed snapshot from current staging/production-derived
Payload content, stop Next and run `bun db:sync:payload`. The command uses
staging only as a read-only dump source, verifies the restore destination is
localhost, writes `.local/payload-staging.dump`, and force-applies it locally.
Normal `bun db:up` never contacts staging; it only restores that local snapshot
when `.local/payload-seed-state.env` is absent or does not match the current
snapshot. The marker stays outside Postgres so Payload schema push does not see
an unmanaged table. The snapshot is gitignored and contains sensitive
production-derived records, including Payload users and password hashes. Do not
share or commit it.

The public landing page is in `apps/next/src/app/(frontend)/page.tsx`; schemas
are under `apps/next/src/payload`, and rendering components are under
`apps/next/src/components/landing`. Custom routes belong in `(frontend)`, not
the generated `(payload)` route group.

Do not manually edit Payload-generated routes, layouts, import maps, or
`apps/next/payload-types.ts`. When schema changes require regeneration, run the
Payload generators through the package's environment wrapper:

```sh
cd apps/next
bun with-env bunx payload generate:types --config src/payload.config.ts
bun with-env bunx payload generate:db-schema --config src/payload.config.ts
```

For staging, use `INFISICAL_ENV=staging`; CI uses temporary Gitea-injected
configuration and never Infisical. Production Payload may use the existing
external/VPN Postgres URL or the commented optional Compose Postgres service.