convex-fundamentals

What this skill does

# Convex Fundamentals for TypeScript Agents

## Overview

Convex is a reactive backend-as-a-service that provides real-time data synchronization, ACID transactions, and TypeScript-first development. This skill covers the core mental model, function types, layered architecture patterns, and HTTP action implementation.

## TypeScript: NEVER Use `any` Type

**CRITICAL RULE:** This codebase has `@typescript-eslint/no-explicit-any` enabled. Using `any` will cause build failures.

**❌ WRONG:**

```typescript
function handleData(data: any) { ... }
const items: any[] = [];
```

**✅ CORRECT:**

```typescript
function handleData(data: { id: string; name: string }) { ... }
const items: Doc<"items">[] = [];
```

## When to Use This Skill

Use this skill when:

- Building Convex backend applications from scratch
- Creating queries, mutations, or actions
- Understanding the difference between function types
- Implementing layered architecture patterns
- Setting up HTTP webhooks with route handlers
- Migrating from other backends to Convex
- Understanding Convex's reactive data model

## Philosophy: Why Convex Feels "Wrong" (And Why That's Right)

Convex intentionally constrains you. When something feels like an anti-pattern, it's usually Convex telling you to rethink the approach.

### The Intentional Friction

| What feels wrong                            | What Convex is telling you                                                               |
| ------------------------------------------- | ---------------------------------------------------------------------------------------- |
| "I can't use `.filter()` on queries"        | Define an index. Queries should be O(log n), not O(n).                                   |
| "Actions can't access `ctx.db`"             | Side effects and transactions don't mix. Route through mutations.                        |
| "My mutation keeps failing with OCC errors" | You're writing too often to the same document. Redesign your data model or use Workpool. |
| "I can't call `fetch()` in a mutation"      | Mutations must be deterministic. Schedule an action instead.                             |
| "Queries re-run on every document change"   | You're collecting too much data. Narrow your index or denormalize.                       |
| "I can't do joins"                          | Denormalize. Embed related data or use lookup tables.                                    |

### Core Invariants

1. **Mutations are ACID transactions** — All writes succeed together or fail together.
2. **Queries are reactive** — They re-run when any read document changes.
3. **Actions are non-transactional orchestration** — No reactivity, no `ctx.db`. Can do external I/O and must call queries/mutations via `ctx.run*`.
4. **Scheduling is atomic with mutations** — If mutation fails, scheduled functions don't run.

## Core Mental Model

Everything in Convex falls into these categories:

| Kind               | Visibility    | Purpose                               |
| ------------------ | ------------- | ------------------------------------- |
| `query`            | public        | Read from DB, reactive subscriptions  |
| `mutation`         | public        | Write to DB, ACID transactions        |
| `action`           | public        | External APIs, non-deterministic work |
| `httpAction`       | public (HTTP) | Webhooks, third-party integrations    |
| `internalQuery`    | private       | Read primitives for internal use      |
| `internalMutation` | private       | Write primitives for internal use     |
| `internalAction`   | private       | Orchestration, external calls         |

**Rule: Export a thin public surface. All real logic lives in internal primitives.**

> `internal*` variants have identical execution semantics to their public counterparts. The only difference is visibility — internal functions appear on `internal.*`, not `api.*`, and cannot be called from clients.

## Layered Architecture

### Layer 1: Client Surface (Public API)

Only entrypoints live here. Thin wrappers that validate, auth-check, and delegate.

```typescript
// convex/jobs.ts — PUBLIC SURFACE
import { mutation, query } from "./_generated/server";
import { v } from "convex/values";
import { internal } from "./_generated/api";

// Public mutation: client entrypoint
export const startGeneration = mutation({
  args: { prompt: v.string() },
  returns: v.id("jobs"),
  handler: async (ctx, args) => {
    // 1. Auth check
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) throw new Error("Unauthorized");

    // 2. Delegate to internal mutation
    const jobId = await ctx.runMutation(internal.jobs.createJob, {
      userId: identity.subject,
      prompt: args.prompt,
    });

    // 3. Schedule background work
    await ctx.scheduler.runAfter(0, internal.jobs.processJob, { jobId });

    return jobId;
  },
});

// Public query: reactive subscription
export const getJob = query({
  args: { jobId: v.id("jobs") },
  returns: v.union(
    v.object({
      _id: v.id("jobs"),
      _creationTime: v.number(),
      status: v.string(),
      prompt: v.string(),
      result: v.optional(v.string()),
    }),
    v.null()
  ),
  handler: async (ctx, args) => {
    return await ctx.db.get(args.jobId);
  },
});
```

### Layer 2: Domain Logic (Internal Primitives)

Where the real logic lives. These are your backend's private API.

```typescript
// convex/jobs.ts — INTERNAL PRIMITIVES (same file, different exports)
import { internalMutation, internalQuery } from "./_generated/server";
import { v } from "convex/values";

export const createJob = internalMutation({
  args: {
    userId: v.string(),
    prompt: v.string(),
  },
  returns: v.id("jobs"),
  handler: async (ctx, args) => {
    return await ctx.db.insert("jobs", {
      userId: args.userId,
      prompt: args.prompt,
      status: "pending",
    });
  },
});

export const markComplete = internalMutation({
  args: {
    jobId: v.id("jobs"),
    result: v.string(),
  },
  returns: v.null(),
  handler: async (ctx, args) => {
    await ctx.db.patch(args.jobId, {
      status: "completed",
      result: args.result,
    });
    return null;
  },
});

export const markFailed = internalMutation({
  args: {
    jobId: v.id("jobs"),
    error: v.string(),
  },
  returns: v.null(),
  handler: async (ctx, args) => {
    await ctx.db.patch(args.jobId, {
      status: "failed",
      error: args.error,
    });
    return null;
  },
});

export const getById = internalQuery({
  args: { jobId: v.id("jobs") },
  returns: v.union(
    v.object({
      _id: v.id("jobs"),
      _creationTime: v.number(),
      userId: v.string(),
      prompt: v.string(),
      status: v.string(),
      result: v.optional(v.string()),
      error: v.optional(v.string()),
    }),
    v.null()
  ),
  handler: async (ctx, args) => {
    return await ctx.db.get(args.jobId);
  },
});
```

### Layer 3: Orchestration (Actions + Scheduler)

For multi-step, external, or long-running work.

```typescript
// convex/jobs.ts — ORCHESTRATION
import { internalAction } from "./_generated/server";
import { v } from "convex/values";
import { internal } from "./_generated/api";

export const processJob = internalAction({
  args: { jobId: v.id("jobs") },
  returns: v.null(),
  handler: async (ctx, args) => {
    // 1. Read current state
    const job = await ctx.runQuery(internal.jobs.getById, {
      jobId: args.jobId,
    });
    if (!job || job.status !== "pending") return null;

    try {
      // 2. External API call (non-deterministic)
      const result = await fetch("https://api.example.com/generate", {
        method: "POST",
        body: JSON.stringify({ prompt: job.prompt }),
      });
      const data = await result.json();

      // 3. Write result via mutation
      await ctx.runMutation(internal.jobs.markComplete, {
        jobId: args.jobId,
        result: data.output,
      });
    } catch (e) {
      await ctx.runMutation(internal.jobs.markFailed