Developer guide

Convex backend

Use the shared backend package for schema, functions, authentication checks, and server-owned domain rules.

Before you edit

Read packages/backend/AGENTS.md and packages/backend/convex/_generated/ai/guidelines.md. The generated guidance overrides generic Convex patterns.

Use the shared API

Functions live in packages/backend/convex. Clients import the generated API instead of copying schema or backend code.

import { api } from '@beegreat/backend/convex/_generated/api'

Required boundaries

• Verify Clerk identity and row ownership for user-scoped operations.
• Validate every client and agent-tool input.
• Keep limits, economy rules, clocks, and ledgers on the server.
• Use idempotency for confirmations, rewards, purchases, and lifecycle commands.

Verify changes

bun run --cwd packages/backend typecheck
bun run --cwd packages/backend test:run