Overview

StarterApp uses Convex for real-time data synchronization with TypeScript type safety, reactive queries, and server functions. This guide covers the actual implementation patterns used in production.

Architecture

Convex provides a complete backend infrastructure:

Tables Pattern (Single Source of Truth)

The codebase uses a centralized table definition system in /convex/tables.ts:

import { T, V, type UserId, type SupportTicketId } from "./tables";

// ✅ Good - uses T.supportTickets constant
export const getTicket = query({
  args: { id: V.supportTicketId },
  handler: async (ctx, { id }) => {
    return await ctx.db.get(id);
  },
});

// ❌ Bad - hardcoded string and type
export const getTicket = query({
  args: { id: v.id("supportTickets") },
  handler: async (ctx, { id }) => {
    return await ctx.db.get(id as Id<"supportTickets">);
  },
});

Builder Pattern (Auth + Guards)

All user-facing functions use custom builders from /convex/_helpers/builders.ts that auto-inject authentication and permissions:

import { userQuery } from "./_helpers/builders";
import { T } from "./tables";

export const getUserSupportTickets = userQuery({
  args: {},
  handler: async (ctx) => {
    // ctx.viewerId is auto-injected and authenticated
    // ctx.db automatically scopes to current user
    return await ctx.db
      .query(T.supportTickets)
      .order("desc")
      .collect();
  },
});

import { userMutation } from "./_helpers/builders";
import { T, type UserId } from "./tables";
import { assertLimitAction } from "./rateLimits";

export const createSupportTicket = userMutation({
  args: {
    title: v.string(),
    description: v.string(),
  },
  handler: async (ctx, { title, description }) => {
    const userId = ctx.viewerId as UserId;

    // Rate limiting: 10 tickets per minute
    await assertLimitAction(ctx, {
      scope: "support:create",
      viewerId: userId,
      max: 10,
      windowMs: 60_000,
    });

    return await ctx.db.insert(T.supportTickets, {
      userId,
      title,
      description,
      status: "Open",
      updatedAt: Date.now(),
    });
  },
});

import { userAction } from "./_helpers/builders";

export const premiumExport = userAction({
  args: { format: v.literal("csv") },
  handler: async (ctx, args) => {
    // Auto-injected Autumn billing integration
    await ctx.check({ featureId: "exports" });

    // Generate export...
    const url = await generateExport(ctx, args.format);

    // Track usage
    ctx.track({ featureId: "exports", amount: 1 });

    return { url };
  },
});

Authentication & Authorization

The application uses identity helpers from /convex/lib/identity.ts:

import { getUserIdOrThrow, assertOwnerByUserId } from "./lib/identity";
import { T, type UserId } from "./tables";

export const getMyNote = query({
  args: { noteId: V.supportTicketId },
  handler: async (ctx, { noteId }) => {
    // Get authenticated user ID (throws UNAUTHENTICATED if not logged in)
    const userId = await getUserIdOrThrow(ctx);

    const note = await ctx.db.get(noteId);

    // Verify ownership (throws FORBIDDEN or NOT_FOUND)
    assertOwnerByUserId(note, userId, { concealExistence: true });

    return note;
  },
});

Error Handling

The application uses typed errors from /convex/_helpers/errors.ts:

import { AppError } from "./_helpers/errors";

// Throw typed errors with proper HTTP status codes
throw new AppError("UNAUTHENTICATED");  // 401
throw new AppError("FORBIDDEN");         // 403
throw new AppError("NOT_FOUND");         // 404
throw new AppError("RATE_LIMITED");      // 429
throw new AppError("PLAN_REQUIRED");     // 402
throw new AppError("USAGE_EXCEEDED");    // 429

Each error code maps to the appropriate HTTP status in /convex/_helpers/errors.ts.

Rate Limiting

Durable rate limiting implementation in /convex/rateLimits.ts:

import { assertLimitAction } from "./rateLimits";

export const sendMessage = action({
  args: { content: v.string() },
  handler: async (ctx, { content }) => {
    const userId = await getUserIdOrThrow(ctx);

    // 10 messages per minute
    await assertLimitAction(ctx, {
      scope: "messages",
      viewerId: userId,
      max: 10,
      windowMs: 60_000,
    });

    // Send message logic here
  },
});

The rate limiter uses bucket-based counting with automatic cleanup of expired entries.

Project Structure

Naming Convention

Always:

• Use user not users
• Use supportTickets not supportTicket (for compound names)
• Import from tables.ts to avoid typos

Available Guides

Related Documentation