Tutorials & GuidesFebruary 22, 202617 min read

Convex + AI: Build Real-Time Backend in Hours, Not Weeks

Founder & CEO, Agentik {OS}

Convex eliminates most backend code. Pair it with AI and you're shipping real-time features that would have taken weeks in a few hours.

Convex + AI: Build Real-Time Backend in Hours, Not Weeks

I spent six years building backends the traditional way. Express, Django, Rails. ORMs, migrations, connection pooling, caching layers. It was valuable learning. Now it's mostly unnecessary.

Convex replaces approximately 60% of what a traditional backend requires. Not the interesting parts. The infrastructure parts. The connection management, the real-time plumbing, the transaction handling, the caching strategy. Convex handles these and exposes a model that's dramatically simpler to reason about.

Pair Convex with an AI agent for implementation, and you're shipping backends that used to require a team in days that a single developer can manage.

Here's the complete picture.

What Convex Is (And Why It's Different)

Convex is a backend-as-a-service that's built specifically for reactive, real-time applications. The mental model:

Database: Document-based, with a TypeScript schema you define
Queries: Reactive. When the underlying data changes, every subscribed client automatically gets the update. No WebSocket management. No polling.
Mutations: ACID transactions. Guaranteed consistency.
Actions: For external API calls, file operations, anything that isn't a database operation
Scheduled jobs: Cron-like scheduling built in
File storage: Built-in with Convex Storage

The key insight: you don't write a backend server. You write functions. Convex handles deploying them, scaling them, connecting clients, and maintaining real-time subscriptions.

The Stack

Layer	Technology
Frontend	Next.js 16 (App Router)
Backend	Convex
Auth	Clerk + Convex Auth
AI	Anthropic API (in Convex Actions)
File uploads	Convex Storage
Deployment	Vercel (frontend) + Convex (backend auto-deploys)

Step 1: Project Setup

bash

# Create Next.js app
npx create-next-app@latest my-app --typescript --tailwind --app
cd my-app

# Add Convex
npm install convex
npx convex dev  # This creates your project and starts dev mode

# Add Clerk for auth
npm install @clerk/nextjs

# Add Anthropic
npm install @anthropic-ai/sdk

Step 2: Schema Definition

The schema is the source of truth. Convex generates TypeScript types from it automatically.

typescript

// convex/schema.ts
import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export default defineSchema({
  // Example: a collaborative notes app
  workspaces: defineTable({
    name: v.string(),
    ownerId: v.string(), // Clerk user ID
    members: v.array(v.string()), // Array of Clerk user IDs
    createdAt: v.number(),
  }).index("by_owner", ["ownerId"]),

  notes: defineTable({
    workspaceId: v.id("workspaces"),
    title: v.string(),
    content: v.string(),
    authorId: v.string(),
    lastEditedBy: v.string(),
    lastEditedAt: v.number(),
    tags: v.array(v.string()),
    embedding: v.optional(v.array(v.float64())), // For semantic search
    isArchived: v.boolean(),
  }).index("by_workspace", ["workspaceId"])
    .index("by_author", ["authorId"])
    .vectorIndex("by_embedding", {
      vectorField: "embedding",
      dimensions: 1536,
      filterFields: ["workspaceId"],
    }),

  aiSummaries: defineTable({
    noteId: v.id("notes"),
    summary: v.string(),
    keyPoints: v.array(v.string()),
    generatedAt: v.number(),
  }).index("by_note", ["noteId"]),
});

Step 3: Queries and Mutations

typescript

// convex/notes.ts
import { query, mutation, action } from "./_generated/server";
import { v } from "convex/values";
import { api } from "./_generated/api";

// Real-time query - clients auto-update when data changes
export const getWorkspaceNotes = query({
  args: {
    workspaceId: v.id("workspaces"),
    includeArchived: v.optional(v.boolean()),
  },
  handler: async (ctx, { workspaceId, includeArchived = false }) => {
    // Auth check
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) throw new Error("Unauthenticated");

    const workspace = await ctx.db.get(workspaceId);
    if (!workspace) throw new Error("Workspace not found");

    const isMember = workspace.members.includes(identity.subject) ||
                     workspace.ownerId === identity.subject;
    if (!isMember) throw new Error("Access denied");

    // Convex's reactive queries automatically re-run when data changes
    const notes = await ctx.db
      .query("notes")
      .withIndex("by_workspace", q => q.eq("workspaceId", workspaceId))
      .filter(q => q.eq(q.field("isArchived"), includeArchived))
      .order("desc")
      .collect();

    return notes;
  },
});

export const createNote = mutation({
  args: {
    workspaceId: v.id("workspaces"),
    title: v.string(),
    content: v.string(),
    tags: v.optional(v.array(v.string())),
  },
  handler: async (ctx, { workspaceId, title, content, tags = [] }) => {
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) throw new Error("Unauthenticated");

    const now = Date.now();
    const noteId = await ctx.db.insert("notes", {
      workspaceId,
      title,
      content,
      authorId: identity.subject,
      lastEditedBy: identity.subject,
      lastEditedAt: now,
      tags,
      isArchived: false,
    });

    // Schedule AI summary generation (non-blocking)
    await ctx.scheduler.runAfter(0, api.notes.generateAiSummary, { noteId });

    return noteId;
  },
});

// AI-powered action
export const generateAiSummary = action({
  args: { noteId: v.id("notes") },
  handler: async (ctx, { noteId }) => {
    const note = await ctx.runQuery(api.notes.getNote, { noteId });
    if (!note || note.content.length < 100) return; // Skip short notes

    const { Anthropic } = await import("@anthropic-ai/sdk");
    const anthropic = new Anthropic();

    const response = await anthropic.messages.create({
      model: "claude-haiku-4-20250514",
      max_tokens: 512,
      messages: [
        {
          role: "user",
          content: `Summarize this note and extract 3-5 key points. Return JSON only.
{ "summary": "2-3 sentence summary", "keyPoints": ["point1", "point2", ...] }

Note:\n${note.content}`,
        },
      ],
    });

    const text = response.content[0].type === "text" ? response.content[0].text : "{}";

    try {
      const { summary, keyPoints } = JSON.parse(text);

      // Check if summary already exists
      const existingSummary = await ctx.runQuery(api.notes.getNoteSummary, { noteId });

      if (existingSummary) {
        await ctx.runMutation(api.notes.updateSummary, {
          summaryId: existingSummary._id,
          summary,
          keyPoints,
        });
      } else {
        await ctx.runMutation(api.notes.createSummary, {
          noteId,
          summary,
          keyPoints,
          generatedAt: Date.now(),
        });
      }
    } catch (error) {
      console.error("Failed to generate or store summary:", error);
    }
  },
});

Step 4: Semantic Search with Vector Indexes

Convex has native vector search. This is one of the most powerful capabilities for AI applications.

typescript

// convex/search.ts
import { action, query } from "./_generated/server";
import { v } from "convex/values";

// Generate embedding for a query
async function generateEmbedding(text: string): Promise<number[]> {
  const { OpenAI } = await import("openai");
  const openai = new OpenAI();

  const response = await openai.embeddings.create({
    model: "text-embedding-3-small",
    input: text,
  });

  return response.data[0].embedding;
}

export const semanticSearch = action({
  args: {
    workspaceId: v.id("workspaces"),
    query: v.string(),
    limit: v.optional(v.number()),
  },
  handler: async (ctx, { workspaceId, query, limit = 5 }) => {
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) throw new Error("Unauthenticated");

    // Generate embedding for the search query
    const queryEmbedding = await generateEmbedding(query);

    // Vector search using Convex's built-in index
    const results = await ctx.vectorSearch("notes", "by_embedding", {
      vector: queryEmbedding,
      limit,
      filter: (q) => q.eq("workspaceId", workspaceId),
    });

    // Fetch full note data for each result
    const notes = await Promise.all(
      results.map(async ({ _id, _score }) => {
        const note = await ctx.runQuery(api.notes.getNote, { noteId: _id });
        return { ...note, relevanceScore: _score };
      })
    );

    return notes.filter(Boolean);
  },
});

Step 5: Real-Time Frontend

tsx

// app/workspace/[id]/page.tsx
"use client";
import { useQuery, useMutation } from "convex/react";
import { api } from "@/convex/_generated/api";
import { Id } from "@/convex/_generated/dataModel";

export default function WorkspacePage({ params }: { params: { id: string } }) {
  const workspaceId = params.id as Id<"workspaces">;

  // This query is live - updates automatically when data changes
  // Works across browser tabs in real-time
  const notes = useQuery(api.notes.getWorkspaceNotes, { workspaceId });
  const createNote = useMutation(api.notes.createNote);

  if (notes === undefined) return <div>Loading...</div>;

  return (
    <div>
      <button
        onClick={() => createNote({
          workspaceId,
          title: "New Note",
          content: "",
        })}
      >
        New Note
      </button>

      <div className="grid gap-4">
        {notes.map(note => (
          <NoteCard key={note._id} note={note} />
        ))}
      </div>
    </div>
  );
}

The useQuery hook does the heavy lifting. When another user in the same workspace creates a note, your component re-renders immediately. No WebSocket code. No polling. No state management for the real-time updates.

Scheduled Jobs

Convex has first-class scheduling support:

typescript

// convex/jobs.ts
import { cronJobs } from "convex/server";
import { api } from "./_generated/api";

const crons = cronJobs();

// Run every night at midnight
crons.daily(
  "generate-workspace-reports",
  { hourUTC: 0, minuteUTC: 0 },
  api.reports.generateDailyReports
);

// Run every hour
crons.hourly(
  "cleanup-expired-sessions",
  { minuteUTC: 0 },
  api.sessions.cleanupExpired
);

export default crons;

What Convex Doesn't Do Well

Honesty matters. Convex has real limitations:

Complex SQL queries. If your data access patterns require complex JOINs, aggregations across many records, or sophisticated GROUP BY logic, Convex's document model is awkward. It works, but it's not natural.

Very high write throughput. Convex's consistency guarantees have throughput limits. For applications with extremely high write rates (thousands of writes per second), you may need a different solution.

Migrating existing Postgres data. If you have an existing Postgres database with complex relational data, migrating to Convex's document model requires careful planning.

For greenfield projects with real-time requirements, Convex is the fastest path to a working backend I've found. For complex data requirements or migration scenarios, evaluate carefully.

FAQ

Q: How do you build applications with Convex and AI agents?

Build with Convex by defining your schema, letting AI agents generate queries, mutations, and actions following Convex patterns. AI agents work exceptionally well with Convex because it is TypeScript-first (providing type safety guidance), convention-based (predictable file structure), and well-documented. A complete Convex backend can be built in hours.

Q: What makes Convex a good choice for AI-built applications?

Convex is ideal for AI-built apps because its TypeScript-first approach provides type safety that guides AI output, built-in real-time subscriptions eliminate WebSocket boilerplate, automatic caching and indexing reduce performance optimization work, and its convention-based structure makes it easy for AI agents to generate consistent code.

Q: How long does it take to build a Convex backend with AI?

AI agents can build a complete Convex backend with authentication, real-time data, file storage, and scheduled functions in 1-2 days. The same scope with a traditional backend (Express + PostgreSQL + WebSockets) takes 2-4 weeks. Convex's built-in features dramatically reduce the amount of code AI needs to generate.

Sources

What Convex Is (And Why It's Different)

Convex is a backend-as-a-service that's built specifically for reactive, real-time applications. The mental model:

Database: Document-based, with a TypeScript schema you define
Queries: Reactive. When the underlying data changes, every subscribed client automatically gets the update. No WebSocket management. No polling.
Mutations: ACID transactions. Guaranteed consistency.
Actions: For external API calls, file operations, anything that isn't a database operation
Scheduled jobs: Cron-like scheduling built in
File storage: Built-in with Convex Storage

The key insight: you don't write a backend server. You write functions. Convex handles deploying them, scaling them, connecting clients, and maintaining real-time subscriptions.

The Stack

Layer	Technology
Frontend	Next.js 16 (App Router)
Backend	Convex
Auth	Clerk + Convex Auth
AI	Anthropic API (in Convex Actions)
File uploads	Convex Storage
Deployment	Vercel (frontend) + Convex (backend auto-deploys)

Step 1: Project Setup

bash

# Create Next.js app
npx create-next-app@latest my-app --typescript --tailwind --app
cd my-app

# Add Convex
npm install convex
npx convex dev  # This creates your project and starts dev mode

# Add Clerk for auth
npm install @clerk/nextjs

# Add Anthropic
npm install @anthropic-ai/sdk

Step 2: Schema Definition

The schema is the source of truth. Convex generates TypeScript types from it automatically.

typescript

// convex/schema.ts
import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export default defineSchema({
  // Example: a collaborative notes app
  workspaces: defineTable({
    name: v.string(),
    ownerId: v.string(), // Clerk user ID
    members: v.array(v.string()), // Array of Clerk user IDs
    createdAt: v.number(),
  }).index("by_owner", ["ownerId"]),

  notes: defineTable({
    workspaceId: v.id("workspaces"),
    title: v.string(),
    content: v.string(),
    authorId: v.string(),
    lastEditedBy: v.string(),
    lastEditedAt: v.number(),
    tags: v.array(v.string()),
    embedding: v.optional(v.array(v.float64())), // For semantic search
    isArchived: v.boolean(),
  }).index("by_workspace", ["workspaceId"])
    .index("by_author", ["authorId"])
    .vectorIndex("by_embedding", {
      vectorField: "embedding",
      dimensions: 1536,
      filterFields: ["workspaceId"],
    }),

  aiSummaries: defineTable({
    noteId: v.id("notes"),
    summary: v.string(),
    keyPoints: v.array(v.string()),
    generatedAt: v.number(),
  }).index("by_note", ["noteId"]),
});

Step 3: Queries and Mutations

typescript

// convex/notes.ts
import { query, mutation, action } from "./_generated/server";
import { v } from "convex/values";
import { api } from "./_generated/api";

// Real-time query - clients auto-update when data changes
export const getWorkspaceNotes = query({
  args: {
    workspaceId: v.id("workspaces"),
    includeArchived: v.optional(v.boolean()),
  },
  handler: async (ctx, { workspaceId, includeArchived = false }) => {
    // Auth check
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) throw new Error("Unauthenticated");

    const workspace = await ctx.db.get(workspaceId);
    if (!workspace) throw new Error("Workspace not found");

    const isMember = workspace.members.includes(identity.subject) ||
                     workspace.ownerId === identity.subject;
    if (!isMember) throw new Error("Access denied");

    // Convex's reactive queries automatically re-run when data changes
    const notes = await ctx.db
      .query("notes")
      .withIndex("by_workspace", q => q.eq("workspaceId", workspaceId))
      .filter(q => q.eq(q.field("isArchived"), includeArchived))
      .order("desc")
      .collect();

    return notes;
  },
});

export const createNote = mutation({
  args: {
    workspaceId: v.id("workspaces"),
    title: v.string(),
    content: v.string(),
    tags: v.optional(v.array(v.string())),
  },
  handler: async (ctx, { workspaceId, title, content, tags = [] }) => {
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) throw new Error("Unauthenticated");

    const now = Date.now();
    const noteId = await ctx.db.insert("notes", {
      workspaceId,
      title,
      content,
      authorId: identity.subject,
      lastEditedBy: identity.subject,
      lastEditedAt: now,
      tags,
      isArchived: false,
    });

    // Schedule AI summary generation (non-blocking)
    await ctx.scheduler.runAfter(0, api.notes.generateAiSummary, { noteId });

    return noteId;
  },
});

// AI-powered action
export const generateAiSummary = action({
  args: { noteId: v.id("notes") },
  handler: async (ctx, { noteId }) => {
    const note = await ctx.runQuery(api.notes.getNote, { noteId });
    if (!note || note.content.length < 100) return; // Skip short notes

    const { Anthropic } = await import("@anthropic-ai/sdk");
    const anthropic = new Anthropic();

    const response = await anthropic.messages.create({
      model: "claude-haiku-4-20250514",
      max_tokens: 512,
      messages: [
        {
          role: "user",
          content: `Summarize this note and extract 3-5 key points. Return JSON only.
{ "summary": "2-3 sentence summary", "keyPoints": ["point1", "point2", ...] }

Note:\n${note.content}`,
        },
      ],
    });

    const text = response.content[0].type === "text" ? response.content[0].text : "{}";

    try {
      const { summary, keyPoints } = JSON.parse(text);

      // Check if summary already exists
      const existingSummary = await ctx.runQuery(api.notes.getNoteSummary, { noteId });

      if (existingSummary) {
        await ctx.runMutation(api.notes.updateSummary, {
          summaryId: existingSummary._id,
          summary,
          keyPoints,
        });
      } else {
        await ctx.runMutation(api.notes.createSummary, {
          noteId,
          summary,
          keyPoints,
          generatedAt: Date.now(),
        });
      }
    } catch (error) {
      console.error("Failed to generate or store summary:", error);
    }
  },
});

Step 4: Semantic Search with Vector Indexes

Convex has native vector search. This is one of the most powerful capabilities for AI applications.

typescript

// convex/search.ts
import { action, query } from "./_generated/server";
import { v } from "convex/values";

// Generate embedding for a query
async function generateEmbedding(text: string): Promise<number[]> {
  const { OpenAI } = await import("openai");
  const openai = new OpenAI();

  const response = await openai.embeddings.create({
    model: "text-embedding-3-small",
    input: text,
  });

  return response.data[0].embedding;
}

export const semanticSearch = action({
  args: {
    workspaceId: v.id("workspaces"),
    query: v.string(),
    limit: v.optional(v.number()),
  },
  handler: async (ctx, { workspaceId, query, limit = 5 }) => {
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) throw new Error("Unauthenticated");

    // Generate embedding for the search query
    const queryEmbedding = await generateEmbedding(query);

    // Vector search using Convex's built-in index
    const results = await ctx.vectorSearch("notes", "by_embedding", {
      vector: queryEmbedding,
      limit,
      filter: (q) => q.eq("workspaceId", workspaceId),
    });

    // Fetch full note data for each result
    const notes = await Promise.all(
      results.map(async ({ _id, _score }) => {
        const note = await ctx.runQuery(api.notes.getNote, { noteId: _id });
        return { ...note, relevanceScore: _score };
      })
    );

    return notes.filter(Boolean);
  },
});

Step 5: Real-Time Frontend

tsx

// app/workspace/[id]/page.tsx
"use client";
import { useQuery, useMutation } from "convex/react";
import { api } from "@/convex/_generated/api";
import { Id } from "@/convex/_generated/dataModel";

export default function WorkspacePage({ params }: { params: { id: string } }) {
  const workspaceId = params.id as Id<"workspaces">;

  // This query is live - updates automatically when data changes
  // Works across browser tabs in real-time
  const notes = useQuery(api.notes.getWorkspaceNotes, { workspaceId });
  const createNote = useMutation(api.notes.createNote);

  if (notes === undefined) return <div>Loading...</div>;

  return (
    <div>
      <button
        onClick={() => createNote({
          workspaceId,
          title: "New Note",
          content: "",
        })}
      >
        New Note
      </button>

      <div className="grid gap-4">
        {notes.map(note => (
          <NoteCard key={note._id} note={note} />
        ))}
      </div>
    </div>
  );
}

Scheduled Jobs

Convex has first-class scheduling support:

typescript

// convex/jobs.ts
import { cronJobs } from "convex/server";
import { api } from "./_generated/api";

const crons = cronJobs();

// Run every night at midnight
crons.daily(
  "generate-workspace-reports",
  { hourUTC: 0, minuteUTC: 0 },
  api.reports.generateDailyReports
);

// Run every hour
crons.hourly(
  "cleanup-expired-sessions",
  { minuteUTC: 0 },
  api.sessions.cleanupExpired
);

export default crons;

What Convex Doesn't Do Well

Honesty matters. Convex has real limitations:

Migrating existing Postgres data. If you have an existing Postgres database with complex relational data, migrating to Convex's document model requires careful planning.

For greenfield projects with real-time requirements, Convex is the fastest path to a working backend I've found. For complex data requirements or migration scenarios, evaluate carefully.

FAQ

Q: How do you build applications with Convex and AI agents?

Q: What makes Convex a good choice for AI-built applications?

Q: How long does it take to build a Convex backend with AI?

Convex + AI: Build Real-Time Backend in Hours, Not Weeks

What Convex Is (And Why It's Different)

The Stack

Step 1: Project Setup

Step 2: Schema Definition

Step 3: Queries and Mutations

Step 4: Semantic Search with Vector Indexes

Step 5: Real-Time Frontend

Scheduled Jobs

What Convex Doesn't Do Well

FAQ

Sources

Further Reading

Related Articles

Want to Implement This?

Convex + AI: Build Real-Time Backend in Hours, Not Weeks

What Convex Is (And Why It's Different)

The Stack

Step 1: Project Setup

Step 2: Schema Definition

Step 3: Queries and Mutations

Step 4: Semantic Search with Vector Indexes

Step 5: Real-Time Frontend

Scheduled Jobs

What Convex Doesn't Do Well

FAQ

Sources

Further Reading

Related Articles

Want to Implement This?