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 3210/3211, its own data volume, and Payload Postgres on port 5432. 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 uses Gitea-injected secrets or CI_ENV_FILE and must not call Infisical.
• App code imports validated variables from @/env, never process.env.
• 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

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

Local URLs: app http://localhost:3000, Convex http://localhost:3210, dashboard http://localhost:6791, Payload Postgres localhost:5432. 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.

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.