Convex Doctor

Convex doctor workflow

This skill codifies the full convex-doctor remediation workflow used in this codebase (score 42 to 100 across 17 passes). Follow it whenever running convex-doctor or fixing its findings.

What is convex-doctor

convex-doctor is a static analysis tool for Convex backends. It scores your codebase 0 to 100 across five categories: security, correctness, performance, schema, and architecture.

Run it with:

npx convex-doctor@latest

Configuration

This project has a convex-doctor.toml at the repo root with intentional suppressions. Always check it before working on findings.

Current suppressions and rationale

Ignored files

• convex/_generated/** (generated code)
• convex/authComponent.ts (thin auth component forwarders)

Fix priority order

When convex-doctor reports findings, fix them in this order:

1. Security errors (highest priority)

   • Add auth to HTTP actions and public endpoints
   • Convert api.* server-to-server calls to internal.*
   • Move public actions to mutation-scheduled internal actions

2. Correctness errors

   • Remove Date.now() from queries (breaks caching and reactivity)
   • Convert .first() to .unique() only where the index enforces uniqueness
   • Fix collect then filter patterns with indexed queries

3. Performance warnings

   • Replace unbounded .collect() with .take(n) or pagination
   • Batch sequential ctx.run* calls into single internal queries
   • Eliminate N+1 patterns in HTTP and RSS endpoints

4. Schema warnings

   • Add missing indexes for foreign keys where query patterns exist
   • Rename indexes to by_field snake_case convention
   • Remove redundant indexes (prefixes of compound indexes)

5. Architecture warnings

   • Extract helper functions from large handlers
   • Split provider modules from orchestration logic
   • Replace throw new Error(...) with ConvexError in user-facing handlers

Common fix patterns

Convert public action to queued job

Instead of calling a public action from the browser, create a job table and mutation-scheduled internal action:

1. Add a job table to convex/schema.ts with status, result, and error fields
2. Create a public mutation that inserts a pending job and schedules the internal action
3. Create a public query that returns job status for the UI
4. Convert the action to internalAction that updates the job record on completion or failure
5. Update the frontend to call the mutation and poll the query

This pattern was used for: AI image generation, AI chat responses, URL imports.

Convert api.* to internal.*

When a Convex function calls another Convex function on the server side:

1. Create an internal* version if only a public version exists
2. Replace api.module.fn with internal.module.fn in the caller
3. If the function needs both public and internal access, keep both and have the public version call the internal one

Batch sequential ctx.run* calls

When an action makes multiple ctx.runQuery calls for independent data:

1. Create a single internal query that returns all needed data in one object
2. Replace the sequential calls with one ctx.runQuery to the batched query
3. This reduces transaction overhead and eliminates the sequential-run-calls warning