convex-doctor

Convex doctor code quality

This codebase maintains a 100/100 convex-doctor score. All new Convex code must follow these patterns to avoid regressions.

Security

• Never use api.* for server-to-server calls. Always use internal.* references.
• All HTTP actions and public endpoints must check authentication unless they are intentionally public (RSS, sitemap, CORS preflight).
• Never expose Node actions directly to the browser. Use mutation-scheduled internal actions with a job table for status tracking.
• Public functions use query, mutation, action. Internal functions use internalQuery, internalMutation, internalAction.

Correctness

• Never use Date.now() inside a query function. It breaks caching and reactivity. Accept a now argument or compute timestamps in mutations/actions.
• Use .unique() for lookups on indexes that enforce uniqueness by design. Use .first() only for intentional ordered picks where multiple rows are expected.
• Never use .collect().filter(). Use .withIndex() and iterate directly, or use .take(n) for bounded results.

Performance

• Bound all public .collect() calls with .take(n) or pagination.
• Batch sequential ctx.runQuery and ctx.runMutation calls in actions. Create a single internal query that returns all needed data instead of making multiple separate calls.
• Use indexes for all query patterns. Never scan full tables.
• Avoid N+1 query patterns. Batch document fetches into internal queries that accept arrays of IDs.

Schema

• Name indexes with by_ prefix and snake_case: by_slug, by_published, by_session_and_context.
• Add indexes for foreign key fields that have query patterns against them.
• Do not add indexes for foreign keys inside nested arrays (Convex cannot index into arrays).
• Remove redundant indexes that are prefixes of existing compound indexes.

Architecture

• Keep handlers focused. Extract helper functions for email templates, data transformation, and multi-step logic.
• Per-handler auth checks are intentional in this codebase. Do not extract auth into middleware or shared wrappers.
• Organize files by domain (posts, pages, newsletter, stats). Do not split purely for file size.
• Use ConvexError instead of throw new Error(...) in user-facing handlers when the error message should reach the client.