Skip to content

CONVEX.md

Latest commit

 

History

History
96 lines (70 loc) · 2.31 KB

CONVEX.md

File metadata and controls

96 lines (70 loc) · 2.31 KB
Raw

CONVEX.md

This template is backend-first. Treat Convex as the main developer surface for agent behavior, not as a hidden implementation detail behind a custom frontend.

First Commands

When working in this repo, run these first:

npm run doctor
npx convex function-spec
npx convex run health:stack '{}'

If you changed Convex code:

npx convex dev

Keep it running so convex/_generated/ stays fresh.

Auth Rules

  • Convex auth is configured in convex/auth.config.ts
  • Clerk and Convex must agree on the same issuer URL
  • The Clerk app must have a JWT template named convex
  • For ownership checks, use identity.tokenIdentifier, not identity.subject

Auth wrappers live in convex/lib/auth.ts. Prefer:

  • authQuery
  • authMutation
  • authAction

Do not reimplement auth checks ad hoc.

Backend Modules

  • convex/agents.ts Agent-facing mutations and actions
  • convex/messages.ts Auth-scoped thread and message reads
  • convex/playground.ts Headless playground API for CLI and debugging
  • convex/health.ts Machine-checkable backend health queries
  • convex/lib/chat.ts Shared model and rate-limiter config

What To Avoid

  • Do not build logic that only works through a custom frontend
  • Do not depend on dashboard inspection when a script or query can verify the same thing
  • Do not put relational app data into Convex if it belongs in Neon
  • Do not edit convex/_generated/

Headless Flows

Preferred validation flow:

npm run doctor
npm run agent:health

If CONVEX_PLAYGROUND_API_KEY is configured:

npm run agent:new -- --title "Smoke test"
npm run agent:threads
npm run agent:send -- --thread <threadId> --prompt "Summarize current backend modules"

These commands are wrappers over the public playground API. Keep that API usable even if no app UI exists yet.

Convex Guidelines

  • Always include validators
  • Prefer bounded queries or pagination
  • Keep public functions explicit and narrow
  • Use component APIs rather than duplicating agent/thread storage logic
  • Health queries should return structured data instead of throwing vague errors

Neon Boundary

Use Neon + Drizzle for:

  • user profiles
  • structured business data
  • reporting-oriented queries

Use Convex for:

  • agent threads
  • messages
  • realtime subscriptions
  • stream state
  • rate limits