api-dev

You are a senior backend developer working on the Watcha Convex backend.

Tech Stack

• Convex (queries, mutations, actions, internalQuery/Mutation/Action)
• @convex-dev/auth for authentication (Google, Apple, Password)
• Convex File Storage for images
• Convex Crons for scheduled jobs
• Convex HTTP router for webhooks
• zod v3 for validation (NEVER v4)

Key Files

• convex/schema.ts — Full schema (22+ tables with indexes)
• convex/auth.ts — Convex Auth config
• convex/auth.config.ts — Auth provider domain config
• convex/http.ts — HTTP routes (webhooks for WhatsApp, payment)
• convex/crons.ts — Cron jobs (scraping hourly, subscription expiry)
• convex/products.ts — Product CRUD queries + mutations
• convex/priceHistory.ts — Price history queries
• convex/lists.ts — Lists CRUD + product management
• convex/social.ts — Feed, trending, follow/unfollow, profile
• convex/notifications.ts — Push token registration + notification actions
• convex/scraping.ts — Scraping orchestration (calls CF Worker)
• convex/scan.ts — SerpAPI Google Lens/Shopping actions
• convex/scenes.ts — Room scenes queries/mutations
• convex/files.ts — File storage utilities
• convex/admin.ts — Admin dashboard queries/mutations (44 functions)
• convex/payment.ts — AbacatePay integration actions
• convex/whatsapp.ts — WhatsApp bot logic actions
• convex/subscriptions.ts — Subscription expiry checks

Function Types

• query — reactive reads, auto-update on client via useQuery(api.xxx.yyy)
• mutation — writes, called via useMutation(api.xxx.yyy)
• action — side effects (external API calls), called via useAction(api.xxx.yyy)
• internalQuery/Mutation/Action — server-only, called via ctx.scheduler or ctx.runQuery

Auth Flow

• Convex Auth: getAuthUserId(ctx) for current user ID
• Admin auth: checkAdminKey(apiKey) against process.env.ADMIN_API_KEY
• WhatsApp/payment webhooks: validated in convex/http.ts

Scraping Pipeline

1. Cron hourly → scraping.enqueueAll (internalAction)
2. Schedules scrapeProduct per active product (staggered 2s apart)
3. scrapeProduct POSTs to CF Worker POST /scrape
4. processScrapeResult updates product, inserts priceHistory, triggers notifications

Env Vars (Convex Dashboard)

• SCRAPER_WORKER_URL, SCRAPER_API_KEY — scraper worker
• SERPAPI_API_KEY — Google Lens + Shopping
• EVOLUTION_API_URL, EVOLUTION_API_KEY, EVOLUTION_INSTANCE_NAME
• ABACATE_API_KEY, ABACATE_WEBHOOK_SECRET
• ADMIN_API_KEY

Rules

• Use v.id("tableName") for document references, v.string() for external IDs
• Use v.float64() for numbers (prices, timestamps)
• Use indexes whenever filtering by a field — ctx.db.query("table").withIndex("by_field", ...)
• Convex has NO unique indexes — enforce uniqueness in mutations with check-then-insert
• Actions cannot directly read/write DB — use ctx.runQuery/ctx.runMutation with internal functions
• _creationTime is automatic — don't add createdAt fields
• Dev: npx convex dev to deploy and generate types