convex-monorepo-payload/AGENTS.md

# AGENTS.md

## Architecture

- `apps/next`: Next.js 16 frontend plus embedded Payload CMS.
- `apps/expo`: Expo scaffold; only work here when explicitly requested.
- `packages/backend/convex`: self-hosted Convex functions, schema, and auth.
- `packages/ui`: shared shadcn-based UI components.
- `tools`: shared ESLint, Prettier, Tailwind, TypeScript, and Vitest config.
- Local development uses host-run apps, local Convex on ports 3240/3241, its
  own data volume, and Payload Postgres on port 5436. Convex does not use
  Postgres unless a cloned project explicitly enables the commented option.

## Protected and generated files

- Never edit `packages/backend/convex/_generated/**` or
  `packages/backend/convex/http.ts`.
- Do not rename `apps/next/next.config.js` or `apps/next/src/proxy.ts`.
- Preserve `withPayload(...)` and `typescript.ignoreBuildErrors` in Next config.
- Do not edit Payload-generated routes, layouts, import maps, or
  `apps/next/payload-types.ts` manually.
- Do not modify Sentry config or `tools/tailwind/theme.css` unless requested.
- Generated `.cache`, `.turbo`, `.local`, and environment files are ignored.

## Environment rules

- Local `dev` and `staging` come only from Infisical via
  `scripts/with-env`; it never falls back to `.env*`.
- Run `infisical login` and `infisical init` before local development.
- Machine-generated values belong in `.local/<env>.generated.env`; never put
  the generated Convex admin key in shared Infisical.
- CI reads `staging` through `scripts/ci-export-env.mjs`, logged in as the
  read-only `convexmonorepo-ci` machine identity (Gitea secrets
  `INFISICAL_CLIENT_ID` and `INFISICAL_CLIENT_SECRET`). `scripts/export-env`
  refuses to run in CI.
- `staging` holds the production values that CI builds and deploys with.
- If you are logged in to more than one Infisical account, put
  `INFISICAL_EMAIL=...` in `scripts/flags/infisical.env` (gitignored) and the
  scripts switch the CLI to that account before exporting.
- Server code imports validated variables from `@/env`. Client components and
  `instrumentation-client.ts` import from `@/publicEnv`, which keeps zod out of
  the browser bundle. Never read `process.env` elsewhere.
- Add cache-relevant variables to `turbo.json` `globalEnv`.

## Code and dependency rules

- Use `const` arrow functions instead of function declarations.
- Add `.js` extensions to Convex generated-file imports.
- Put custom frontend routes in `apps/next/src/app/(frontend)`.
- Extend the Convex `users` table for application user data; do not add a
  profile table by default. Authenticate protected functions.
- Manage shared versions in root catalogs. Never run `bun update` in a package.
- Run root `bun install` and verify with `bun lint:ws`.
- Update this guide when architecture or workflows change.

## Local stack

```sh
bun db:up          # start Payload Postgres, Convex, and dashboard
bun dev:next       # host Next + deploy/watch local Convex functions
bun db:down        # stop and preserve both data volumes
bun db:down:wipe   # remove both volumes, generated admin key, and seed marker
bun db:sync:payload # refresh and apply the local Payload seed snapshot
bun db:sync-env    # re-push Infisical dev values into the local Convex env
bun dev:kill       # stop dev servers that survived a Ctrl-C
```

Local URLs: app `http://localhost:3000`, Convex `http://localhost:3240`,
dashboard `http://localhost:6794`, Payload Postgres `localhost:5436`.
Use `INFISICAL_ENV=staging bun dev:next` for staging services.

`db:sync:payload` is an explicit, destructive local operation. It validates a
remote staging source and localhost destination, stores the sensitive snapshot
only under `.local/`, and never changes Convex or production data. Normal
`db:up` never connects to staging; it only applies `.local/payload-staging.dump`
when `.local/payload-seed-state.env` is absent or stale. Do not store seed
markers in Payload Postgres; schema push treats unmanaged tables as drift.

## Payload schema changes

Payload schema changes ship as migrations in `apps/next/src/migrations/`.
Locally, Payload pushes schema edits straight into the localhost database. When
a change is ready, run `bun with-env bunx payload migrate:create <name>` from
`apps/next` and commit the generated files. Production runs pending migrations
on startup (`prodMigrations` in `payload.config.ts`). Push only runs against a
database on `localhost`: a push leaves a `dev` row in `payload_migrations`, and
Payload's startup migration stops on a confirmation prompt when it finds one.
For the same reason, a local production build against the local dev database
hangs; point it at a database without that row.

## Analytics and bundle size

- Plausible (`NEXT_PUBLIC_PLAUSIBLE_SRC`, the per-site script URL) loads through
  a same-origin proxy under `/pa`, clear of Payload's `/api` routes. PostHog
  (`NEXT_PUBLIC_POSTHOG_KEY`, `NEXT_PUBLIC_POSTHOG_HOST`) loads after the page
  is idle through `/ingest`. Both stay off when their env is unset.
- Session replay comes from PostHog. Sentry carries errors and traces only.
- `packages/ui/src/index.tsx` holds re-exports only (`cn` and `ccn` live in
  `utils.ts`). With `optimizePackageImports` in `next.config.js`, each page
  loads only the UI modules it imports. Declaring anything in the index breaks
  that.

## Deployment

A push to `main` runs `.gitea/workflows/build-next.yml`: the quality gate, then
`convex deploy` to production, then the image build and push, then
`ssh [email protected] convexmonorepo` (the forced-command deploy on the VPS). A
push to `main` is a production deploy.

## Validation

Use `bun typecheck`, never a production build for routine validation. The full
gate is `SKIP_E2E=1 bun run ci:check`; local-stack smoke e2e is `bun test:e2e`.
Pre-commit runs lint-staged serially and pre-push runs the bounded full gate.