managing-convex

name	managing-convex
description	Manages Convex backend: schema, queries, mutations, and actions. Use for: database operations, server logic, real-time subscriptions. DO NOT use for: frontend components (use developing-nextjs), API routes (use Next.js actions).

Managing Convex

Convex backend overview. Use the specific skills below for actual tasks.

Skill Routing

Task	Use Skill
Add a new database table	adding-convex-table
Write query/mutation/action	writing-convex-functions
Preload data for SSR	preloading-convex-data

Source of Truth

Concern	Location
Schema	convex/schema.ts
Functions	convex/*.ts
Lib Utilities	convex/lib/
Generated Types	convex/_generated/

Function Types

Type	Use Case	Access
query	Read data (reactive)	ctx.db.query()
mutation	Write data	ctx.db.insert/patch/delete()
action	External APIs	fetch(), ctx.runQuery()

Current Tables

Table	Purpose
users	User accounts
generatedImages	Generation history
favorites	Saved images
follows	User follows
promptLibrary	Saved prompts
referenceImages	Uploaded references

Lib Utilities

File	Purpose
convex/lib/pollinations.ts	API URL building
convex/lib/r2.ts	Cloudflare R2 storage
convex/lib/retry.ts	Retry with backoff
convex/lib/subscription.ts	Subscription helpers
convex/lib/videoThumbnail.ts	FFmpeg thumbnails

Auth Pattern

const identity = await ctx.auth.getUserIdentity();
if (!identity) throw new Error("Unauthenticated");
const userId = identity.subject; // Clerk user ID

Guardrails

• Always index fields used in queries
• Always validate args with v.* validators
• Auth required for user-scoped data
• Actions can't access db — use ctx.runQuery/runMutation