Articles/App Development

▣ App Development/2026-04-11Advanced

Building Real-Time Collaborative SaaS with Antigravity and Convex: From Type-Safe Data Sync to Stripe Billing

A complete guide to building a real-time collaborative SaaS using Antigravity IDE and Convex. Covers schema design, Clerk authentication, file storage, and Stripe billing with production-ready code.

convex saas¹⁰ realtime⁴ stripe⁹ clerk antigravity⁴³⁵ app-dev⁴⁹

✦ Premium Article

Setup and context: Why Convex + Antigravity?

For indie developers and small teams, launching a real-time collaborative SaaS has always been a significant challenge. Managing WebSocket connections, ensuring data consistency across clients, and building scalable infrastructure — all of that used to take weeks of focused work.

Convex solves this problem at the foundation level. It provides a reactive backend platform with type-safe schema definitions, automatic real-time data sync, and seamless serverless function execution. Pair it with Antigravity IDE, and you get AI-powered code completion, error diagnosis, and architecture suggestions that dramatically accelerate your development pace.

In this guide, you'll build a real-time collaborative document editing SaaS using Convex and Antigravity. By the end, you'll have a production-ready app with authentication (Clerk), file storage, Stripe subscription billing, and deployment to Cloudflare Pages.

Who This Guide Is For

Developers with solid Next.js or React experience
Backend developers who haven't tried Convex yet
Indie hackers who want to ship a SaaS quickly using Antigravity
Anyone who has struggled to implement real-time features before

What You'll Build

By the end of this guide, you'll have a working SaaS application with:

Real-time collaborative document editing (multiple users editing simultaneously)
Authentication via Clerk (Google, GitHub, and email support)
File uploads with CDN delivery via Convex Storage
Stripe subscription billing (Free and Pro plans)
Deployment to Cloudflare Pages

1. Project Setup

1-1. Prerequisites

# Node.js 20+ required
node --version  # v20.x.x or higher
 
# pnpm recommended
npm install -g pnpm
 
# Convex CLI
pnpm add -g convex

Open Antigravity IDE and ask the Agent to scaffold your project:

Create a new project called "CollabDocs" using Next.js 14, Convex, Clerk,
Stripe, and Tailwind CSS. Use TypeScript strict mode throughout.

The Agent will automatically run the setup commands:

pnpm create next-app@latest collabdocs \
  --typescript \
  --tailwind \
  --eslint \
  --app \
  --src-dir \
  --import-alias "@/*"
 
cd collabdocs
 
# Install dependencies
pnpm add convex @clerk/nextjs stripe @stripe/stripe-js
pnpm add -D @types/stripe

1-2. Initialize Convex

cd collabdocs
npx convex dev

The first run opens your browser to the Convex dashboard for authentication. Once you log in, your project is automatically created and the following environment variable is added to .env.local:

NEXT_PUBLIC_CONVEX_URL=https://your-project.convex.cloud

1-3. Ask Antigravity to Design Your Schema

Your schema is the backbone of your SaaS. Ask Antigravity's Agent:

Design a Convex schema for a real-time collaborative document SaaS.
I need the following entities:
- Users (synced from Clerk)
- Workspaces (multiple users can join)
- Documents (belong to a workspace)
- Document operation history (for real-time sync)
- Subscription information

Review what the Agent generates and refine as needed.

✦

Thank you for reading this far.

Continue Reading

What follows includes implementation code, benchmarks, and practical content we hope you'll find useful. This site runs without ads — server and development costs are supported entirely by members like you. If it's been helpful, we'd be truly grateful for your support.

WHAT YOU'LL LEARN

✦Developers stuck on Convex real-time sync can complete their data architecture in a single day with Antigravity's AI assistance

✦Learn every code pattern needed for production SaaS — schema design, Clerk auth, file storage, and Stripe billing in one guide

✦Walk away with the technical skills and design judgment to ship a revenue-generating web app using Convex and Antigravity

Secure payment via Stripe · Cancel anytime

✦

Unlock This Article

Get full access to the rest of this article. Buy once, read anytime. This site is ad-free — your support goes directly toward keeping it running.

Unlock all articles with Membership →

2. Convex Schema Design

2-1. Table Definitions

Create convex/schema.ts:

import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";
 
export default defineSchema({
  // Users table (synced from Clerk)
  users: defineTable({
    clerkId: v.string(),
    email: v.string(),
    name: v.string(),
    imageUrl: v.optional(v.string()),
    plan: v.union(v.literal("free"), v.literal("pro")),
    stripeCustomerId: v.optional(v.string()),
    stripeSubscriptionId: v.optional(v.string()),
    createdAt: v.number(),
  })
    .index("by_clerk_id", ["clerkId"])
    .index("by_email", ["email"]),
 
  // Workspaces table
  workspaces: defineTable({
    name: v.string(),
    ownerId: v.id("users"),
    plan: v.union(v.literal("free"), v.literal("pro")),
    memberIds: v.array(v.id("users")),
    createdAt: v.number(),
    updatedAt: v.number(),
  })
    .index("by_owner", ["ownerId"]),
 
  // Documents table
  documents: defineTable({
    title: v.string(),
    content: v.string(),       // JSON string (editor internal format)
    workspaceId: v.id("workspaces"),
    authorId: v.id("users"),
    collaboratorIds: v.array(v.id("users")),
    storageId: v.optional(v.id("_storage")),  // attached file
    isPublic: v.boolean(),
    createdAt: v.number(),
    updatedAt: v.number(),
  })
    .index("by_workspace", ["workspaceId"])
    .index("by_author", ["authorId"]),
 
  // Operation history (for OT / CRDT-based diff recording)
  documentOperations: defineTable({
    documentId: v.id("documents"),
    userId: v.id("users"),
    operation: v.string(),     // JSON string (diff data)
    version: v.number(),
    timestamp: v.number(),
  })
    .index("by_document", ["documentId"])
    .index("by_document_version", ["documentId", "version"]),
});

2-2. Schema Design Insights from Antigravity

Ask Antigravity to review your schema: "What are the potential issues with this schema and how can I improve it?" You'll get feedback like:

The content field stored as a string works, but using v.any() or a dedicated type improves type safety
The memberIds array can become a performance bottleneck for large workspaces — consider a junction table
documentOperations benefits from a composite index on ["documentId", "timestamp"] for time-ordered queries

This kind of iterative AI-assisted schema refinement is where Antigravity really shines.

3. Queries, Mutations, and Actions

3-1. Document CRUD

Create convex/documents.ts:

import { query, mutation } from "./_generated/server";
import { v } from "convex/values";
import { getCurrentUser } from "./users";
 
// List documents (automatically real-time synced)
export const listByWorkspace = query({
  args: { workspaceId: v.id("workspaces") },
  handler: async (ctx, args) => {
    const user = await getCurrentUser(ctx);
    if (!user) return [];
 
    const docs = await ctx.db
      .query("documents")
      .withIndex("by_workspace", (q) =>
        q.eq("workspaceId", args.workspaceId)
      )
      .order("desc")
      .collect();
 
    return docs.filter(
      (doc) =>
        doc.isPublic ||
        doc.authorId === user._id ||
        doc.collaboratorIds.includes(user._id)
    );
  },
});
 
// Create a document
export const create = mutation({
  args: {
    title: v.string(),
    workspaceId: v.id("workspaces"),
  },
  handler: async (ctx, args) => {
    const user = await getCurrentUser(ctx);
    if (!user) throw new Error("Authentication required");
 
    const now = Date.now();
    return await ctx.db.insert("documents", {
      title: args.title,
      content: JSON.stringify({ type: "doc", content: [] }),
      workspaceId: args.workspaceId,
      authorId: user._id,
      collaboratorIds: [],
      isPublic: false,
      createdAt: now,
      updatedAt: now,
    });
  },
});
 
// Update content (the core of real-time sync)
export const updateContent = mutation({
  args: {
    documentId: v.id("documents"),
    content: v.string(),
    operation: v.string(),   // diff data
  },
  handler: async (ctx, args) => {
    const user = await getCurrentUser(ctx);
    if (!user) throw new Error("Authentication required");
 
    const doc = await ctx.db.get(args.documentId);
    if (!doc) throw new Error("Document not found");
 
    const canEdit =
      doc.authorId === user._id ||
      doc.collaboratorIds.includes(user._id);
    if (!canEdit) throw new Error("Edit permission denied");
 
    const now = Date.now();
 
    await ctx.db.patch(args.documentId, {
      content: args.content,
      updatedAt: now,
    });
 
    const lastOp = await ctx.db
      .query("documentOperations")
      .withIndex("by_document", (q) =>
        q.eq("documentId", args.documentId)
      )
      .order("desc")
      .first();
 
    await ctx.db.insert("documentOperations", {
      documentId: args.documentId,
      userId: user._id,
      operation: args.operation,
      version: (lastOp?.version ?? 0) + 1,
      timestamp: now,
    });
  },
});

3-2. How Real-Time Sync Works

Convex's killer feature is that queries automatically stay in sync in real time. Using useQuery in your React components means that when any data changes on the server, the UI updates immediately — no manual polling, no WebSocket management.

// app/workspace/[id]/page.tsx
"use client";
 
import { useQuery } from "convex/react";
import { api } from "@/convex/_generated/api";
import { Id } from "@/convex/_generated/dataModel";
 
export default function WorkspacePage({
  params,
}: {
  params: { id: string };
}) {
  // This query re-runs automatically whenever the data changes
  const documents = useQuery(api.documents.listByWorkspace, {
    workspaceId: params.id as Id<"workspaces">,
  });
 
  if (documents === undefined) {
    return <div className="animate-pulse">Loading...</div>;
  }
 
  return (
    <div className="grid gap-4 p-6">
      {documents.map((doc) => (
        <DocumentCard key={doc._id} document={doc} />
      ))}
    </div>
  );
}

When User A calls updateContent, User B's screen — open in another tab or browser — updates automatically within milliseconds.

4. Clerk Authentication Integration

4-1. Clerk + Convex Configuration

// convex/auth.config.ts
export default {
  providers: [
    {
      domain: process.env.CLERK_JWT_ISSUER_DOMAIN!,
      applicationID: "convex",
    },
  ],
};

// convex/users.ts
import { internalMutation, query, QueryCtx } from "./_generated/server";
import { v } from "convex/values";
 
export const getCurrentUser = async (ctx: QueryCtx) => {
  const identity = await ctx.auth.getUserIdentity();
  if (!identity) return null;
 
  return await ctx.db
    .query("users")
    .withIndex("by_clerk_id", (q) =>
      q.eq("clerkId", identity.subject)
    )
    .unique();
};
 
export const syncUser = internalMutation({
  args: {
    clerkId: v.string(),
    email: v.string(),
    name: v.string(),
    imageUrl: v.optional(v.string()),
  },
  handler: async (ctx, args) => {
    const existing = await ctx.db
      .query("users")
      .withIndex("by_clerk_id", (q) => q.eq("clerkId", args.clerkId))
      .unique();
 
    if (existing) {
      await ctx.db.patch(existing._id, {
        email: args.email,
        name: args.name,
        imageUrl: args.imageUrl,
      });
      return existing._id;
    }
 
    return await ctx.db.insert("users", {
      ...args,
      plan: "free",
      createdAt: Date.now(),
    });
  },
});

4-2. Clerk Webhook Handler

Create app/api/clerk/webhook/route.ts:

import { Webhook } from "svix";
import { headers } from "next/headers";
import { WebhookEvent } from "@clerk/nextjs/server";
import { ConvexHttpClient } from "convex/browser";
import { api } from "@/convex/_generated/api";
 
const convex = new ConvexHttpClient(process.env.NEXT_PUBLIC_CONVEX_URL!);
 
export async function POST(req: Request) {
  const WEBHOOK_SECRET = process.env.CLERK_WEBHOOK_SECRET;
  if (!WEBHOOK_SECRET) {
    throw new Error("CLERK_WEBHOOK_SECRET not set");
  }
 
  const headerPayload = headers();
  const svix_id = headerPayload.get("svix-id");
  const svix_timestamp = headerPayload.get("svix-timestamp");
  const svix_signature = headerPayload.get("svix-signature");
 
  if (!svix_id || !svix_timestamp || !svix_signature) {
    return new Response("Bad Request", { status: 400 });
  }
 
  const payload = await req.json();
  const body = JSON.stringify(payload);
  const wh = new Webhook(WEBHOOK_SECRET);
  let evt: WebhookEvent;
 
  try {
    evt = wh.verify(body, {
      "svix-id": svix_id,
      "svix-timestamp": svix_timestamp,
      "svix-signature": svix_signature,
    }) as WebhookEvent;
  } catch {
    return new Response("Signature verification failed", { status: 400 });
  }
 
  if (evt.type === "user.created" || evt.type === "user.updated") {
    const { id, email_addresses, first_name, last_name, image_url } = evt.data;
    await convex.mutation(api.users.syncUser, {
      clerkId: id,
      email: email_addresses[0]?.email_address ?? "",
      name: `${first_name ?? ""} ${last_name ?? ""}`.trim(),
      imageUrl: image_url,
    });
  }
 
  return new Response("OK", { status: 200 });
}

5. File Storage

Convex includes built-in file storage, so you don't need to set up S3 or Cloudflare R2 separately.

5-1. File Upload Flow

// convex/files.ts
import { mutation, query } from "./_generated/server";
import { v } from "convex/values";
import { getCurrentUser } from "./users";
 
export const generateUploadUrl = mutation({
  handler: async (ctx) => {
    const user = await getCurrentUser(ctx);
    if (!user) throw new Error("Authentication required");
    return await ctx.storage.generateUploadUrl();
  },
});
 
export const attachToDocument = mutation({
  args: {
    documentId: v.id("documents"),
    storageId: v.id("_storage"),
  },
  handler: async (ctx, args) => {
    const user = await getCurrentUser(ctx);
    if (!user) throw new Error("Authentication required");
 
    await ctx.db.patch(args.documentId, {
      storageId: args.storageId,
      updatedAt: Date.now(),
    });
  },
});
 
export const getFileUrl = query({
  args: { storageId: v.id("_storage") },
  handler: async (ctx, args) => {
    return await ctx.storage.getUrl(args.storageId);
  },
});

5-2. File Upload Component

// components/FileUpload.tsx
"use client";
 
import { useMutation } from "convex/react";
import { api } from "@/convex/_generated/api";
import { Id } from "@/convex/_generated/dataModel";
import { useCallback, useState } from "react";
 
export function FileUpload({ documentId }: { documentId: Id<"documents"> }) {
  const [uploading, setUploading] = useState(false);
  const generateUploadUrl = useMutation(api.files.generateUploadUrl);
  const attachToDocument = useMutation(api.files.attachToDocument);
 
  const handleUpload = useCallback(
    async (e: React.ChangeEvent<HTMLInputElement>) => {
      const file = e.target.files?.[0];
      if (!file) return;
 
      setUploading(true);
      try {
        // Step 1: Get upload URL
        const uploadUrl = await generateUploadUrl();
 
        // Step 2: Upload the file
        const result = await fetch(uploadUrl, {
          method: "POST",
          headers: { "Content-Type": file.type },
          body: file,
        });
        const { storageId } = await result.json();
 
        // Step 3: Link to document
        await attachToDocument({ documentId, storageId });
      } finally {
        setUploading(false);
      }
    },
    [generateUploadUrl, attachToDocument, documentId]
  );
 
  return (
    <label className="cursor-pointer inline-flex items-center gap-2 px-4 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700">
      {uploading ? "Uploading..." : "Attach File"}
      <input
        type="file"
        className="hidden"
        onChange={handleUpload}
        disabled={uploading}
      />
    </label>
  );
}

6. Stripe Billing Integration

6-1. Stripe Webhook Handler

// app/api/stripe/webhook/route.ts
import Stripe from "stripe";
import { headers } from "next/headers";
import { ConvexHttpClient } from "convex/browser";
import { api } from "@/convex/_generated/api";
 
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
const convex = new ConvexHttpClient(process.env.NEXT_PUBLIC_CONVEX_URL!);
 
export async function POST(req: Request) {
  const body = await req.text();
  const sig = headers().get("stripe-signature")!;
 
  let event: Stripe.Event;
  try {
    event = stripe.webhooks.constructEvent(
      body,
      sig,
      process.env.STRIPE_WEBHOOK_SECRET!
    );
  } catch {
    return new Response("Signature verification failed", { status: 400 });
  }
 
  switch (event.type) {
    case "checkout.session.completed": {
      const session = event.data.object as Stripe.CheckoutSession;
      const clerkId = session.metadata?.clerkId;
      if (!clerkId) break;
 
      await convex.mutation(api.subscriptions.activate, {
        clerkId,
        stripeCustomerId: session.customer as string,
        stripeSubscriptionId: session.subscription as string,
      });
      break;
    }
 
    case "customer.subscription.deleted": {
      const subscription = event.data.object as Stripe.Subscription;
      await convex.mutation(api.subscriptions.deactivate, {
        stripeSubscriptionId: subscription.id,
      });
      break;
    }
  }
 
  return new Response("OK", { status: 200 });
}

6-2. Subscription Mutations

// convex/subscriptions.ts
import { internalMutation } from "./_generated/server";
import { v } from "convex/values";
 
export const activate = internalMutation({
  args: {
    clerkId: v.string(),
    stripeCustomerId: v.string(),
    stripeSubscriptionId: v.string(),
  },
  handler: async (ctx, args) => {
    const user = await ctx.db
      .query("users")
      .withIndex("by_clerk_id", (q) => q.eq("clerkId", args.clerkId))
      .unique();
 
    if (!user) throw new Error("User not found");
 
    await ctx.db.patch(user._id, {
      plan: "pro",
      stripeCustomerId: args.stripeCustomerId,
      stripeSubscriptionId: args.stripeSubscriptionId,
    });
  },
});
 
export const deactivate = internalMutation({
  args: { stripeSubscriptionId: v.string() },
  handler: async (ctx, args) => {
    const user = await ctx.db
      .query("users")
      .filter((q) =>
        q.eq(q.field("stripeSubscriptionId"), args.stripeSubscriptionId)
      )
      .unique();
 
    if (!user) return;
 
    await ctx.db.patch(user._id, {
      plan: "free",
      stripeSubscriptionId: undefined,
    });
  },
});

7. Debugging and Refactoring with Antigravity

7-1. Common Errors Antigravity Helps You Fix

Error 1: Convex query argument type mismatch

Type 'string' is not assignable to type 'Id<"workspaces">'

Paste this into Antigravity's chat and ask it to fix the error. It'll immediately suggest:

// Before
const docs = useQuery(api.documents.listByWorkspace, {
  workspaceId: params.id,  // string type — wrong
});
 
// After
import { Id } from "@/convex/_generated/dataModel";
 
const docs = useQuery(api.documents.listByWorkspace, {
  workspaceId: params.id as Id<"workspaces">,  // correct
});

Error 2: Calling external APIs from Convex queries

Convex queries and mutations can't call external APIs directly. Use action instead:

// convex/ai.ts
import { action } from "./_generated/server";
import { v } from "convex/values";
 
export const summarizeDocument = action({
  args: { content: v.string() },
  handler: async (ctx, args) => {
    // Actions can call external APIs
    const response = await fetch("https://api.example.com/summarize", {
      method: "POST",
      body: JSON.stringify({ text: args.content }),
    });
    const data = await response.json();
    return data.summary;
  },
});

7-2. Automated Code Review with Antigravity

After writing any significant chunk of code, ask Antigravity: "Please review this code for security vulnerabilities and performance issues." You'll get actionable feedback like:

Missing permission checks in Convex mutations
Using collect() where paginate() should be used for large datasets
Queries that aren't using indexes properly

This kind of AI-assisted code review catches production-level bugs before they ever ship.

8. Deploying to Cloudflare Pages

8-1. Configuration

pnpm add -D @cloudflare/next-on-pages

Create wrangler.toml:

name = "collabdocs"
compatibility_date = "2024-01-01"
compatibility_flags = ["nodejs_compat"]
 
[build]
command = "pnpm run build"

Add to package.json:

{
  "scripts": {
    "pages:build": "npx @cloudflare/next-on-pages",
    "deploy": "pnpm pages:build && wrangler pages deploy .vercel/output/static"
  }
}

8-2. Environment Variables

Set these in your Cloudflare Pages dashboard:

NEXT_PUBLIC_CONVEX_URL — Your Convex deployment URL
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY — Clerk publishable key
CLERK_SECRET_KEY — Clerk secret key
CLERK_WEBHOOK_SECRET — Clerk webhook signing secret
STRIPE_SECRET_KEY — Stripe secret key
STRIPE_WEBHOOK_SECRET — Stripe webhook signing secret
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY — Stripe publishable key

8-3. Deploy Convex to Production

npx convex deploy

This deploys your Convex functions and schema to the production environment and gives you a production URL to set in Cloudflare.

9. Enforcing Plan Limits

Gating features by plan creates a natural upgrade path for your users.

// convex/workspaces.ts
export const create = mutation({
  args: { name: v.string() },
  handler: async (ctx, args) => {
    const user = await getCurrentUser(ctx);
    if (!user) throw new Error("Authentication required");
 
    // Enforce Free plan limits
    if (user.plan === "free") {
      const existingWorkspaces = await ctx.db
        .query("workspaces")
        .withIndex("by_owner", (q) => q.eq("ownerId", user._id))
        .collect();
 
      if (existingWorkspaces.length >= 3) {
        throw new Error(
          "Free plan is limited to 3 workspaces. Upgrade to Pro to create more."
        );
      }
    }
 
    const now = Date.now();
    return await ctx.db.insert("workspaces", {
      name: args.name,
      ownerId: user._id,
      plan: user.plan,
      memberIds: [user._id],
      createdAt: now,
      updatedAt: now,
    });
  },
});

Summary

The Antigravity + Convex stack has turned a multi-week real-time SaaS project into something achievable in a few focused days. Here's a recap of the key implementation patterns from this guide:

Schema design: Type-safe table definitions with thoughtful indexes
Real-time sync: useQuery eliminates all WebSocket management
Clerk auth: Webhooks keep your Convex user table in sync automatically
File storage: Convex's built-in storage removes the need for S3 or R2
Stripe billing: Webhooks feed directly into Convex mutations for clean plan management
Plan gating: Server-side checks in mutations make feature limits secure by default

To deepen your understanding of production SaaS architecture with these tools, Full-Stack SaaS Development with Next.js is an excellent companion resource.

For related implementation guides, check out Antigravity × Supabase Real-Time Fullstack Guide and Antigravity × Stripe App Monetization Guide.

Thank You for Reading

Antigravity Lab is ad-free, supported entirely by members like you. We publish practical guides daily with implementation code, benchmarks, and production-ready patterns. If you've found it useful, we'd love to have you on board.