Gabriel Brown
73 lines
3.4 KiB
Markdown
73 lines
3.4 KiB
Markdown
# 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
|
|
|
|
```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
|
|
```
|
|
|
|
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.
|