Clerk-Convex Integration

Overview

This document describes the completed integration between Clerk authentication and Convex backend for the B2C contact management application. The system now provides seamless authentication and user data management.

Architecture

Authentication Flow

1. Clerk Authentication: Handles user sign-in, sign-up, password reset, and session management
2. User Synchronization: Clerk users are automatically synced to Convex database
3. Data Bridge: clerkUsers table in Convex bridges Clerk user IDs with application data
4. Role-Based Access: Admin/user roles managed through Clerk metadata and Convex data

Database Schema Updates

New Table: clerkUsers

clerkUsers: defineTable({
  clerkUserId: v.string(), // Clerk user ID (primary key)
  email: v.string(), // User email
  name: v.string(), // User full name
  companyName: v.optional(v.string()),
  reason: v.optional(v.string()),
  isApproved: v.boolean(), // Admin approval status
  contactQuota: v.number(), // Contact quota limit
  usedQuota: v.number(), // Used contact quota
  role: v.union(v.literal("admin"), v.literal("user")),
  createdAt: v.number(),
  updatedAt: v.number(),
  lastLoginAt: v.optional(v.number()),
});

Updated Tables for Dual Compatibility

• contacts: Added createdByClerk and assignedToClerk fields
• contactRequests: Added clerkUserId field
• campaigns: Added clerkUserId field
• emailTemplates: Added createdByClerk field

Key Features Implemented

1. User Authentication

• Sign In/Sign Up: Clerk components with custom styling
• Password Reset: Built-in Clerk password reset flow
• Email Verification: Automatic through Clerk
• Route Protection: Middleware protects dashboard and admin routes

2. User Management

• Automatic Sync: Users are synced to Convex on first login
• Approval System: New users require admin approval
• Quota Management: Configurable contact quotas per user
• Role Management: Admin/user role assignment

3. Dashboard Integration

• Real-time Stats: User quota, contacts, campaigns, and requests
• Contact Requests: Users can request contacts with filters
• Request History: View all past contact requests
• Quota Tracking: Visual quota usage indicators

4. Admin Panel

• User Management: View, approve, and manage all users
• Quota Assignment: Set custom quotas for users
• Role Management: Assign admin/user roles
• System Overview: Monitor overall system usage

API Functions

Clerk User Management (convex/clerkUsers.ts)

Mutations

• syncClerkUser: Create/update user in Convex
• requestContactsForClerkUser: Request contacts for a Clerk user
• approveClerkUser: Approve/reject users (admin only)
• updateClerkUserQuota: Update user quota (admin only)
• updateClerkUserRole: Update user role (admin only)

Queries

• getClerkUser: Get user by Clerk ID
• getUserStats: Get dashboard stats for a user
• getUserContactRequests: Get user's contact requests
• getAllClerkUsers: Get all users (admin only)

Usage Examples

Sync User on Login

const syncClerkUser = useMutation(api.clerkUsers.syncClerkUser);

useEffect(() => {
  if (user) {
    syncClerkUser({
      clerkUserId: user.id,
      email: user.emailAddresses?.[0]?.emailAddress || "",
      name: user.fullName || user.firstName || "",
    });
  }
}, [user, syncClerkUser]);

Get User Stats

const userStats = useQuery(
  api.clerkUsers.getUserStats,
  user ? { clerkUserId: user.id } : "skip"
);

Request Contacts

const requestContacts = useMutation(api.clerkUsers.requestContactsForClerkUser);

await requestContacts({
  clerkUserId: user.id,
  filters: { industry: ["Technology"], country: ["United States"] },
  quantityRequested: 10,
});

File Changes Summary

Updated Files

1. Schema: convex/schema.ts - Added Clerk integration tables
2. Dashboard: app/dashboard/page.tsx - Real-time Convex data
3. Admin Panel: app/admin/page.tsx - Clerk user management
4. Request Contacts: app/dashboard/request-contacts/page.tsx - Clerk integration
5. Admin Users: app/admin/users/page.tsx - Clerk user operations

New Files

1. Clerk Functions: convex/clerkUsers.ts - All Clerk-Convex bridge functions

Environment Variables

Required environment variables in .env.local:

# Clerk
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up

# Convex
CONVEX_DEPLOYMENT=...
NEXT_PUBLIC_CONVEX_URL=...

Production Deployment

Steps

1. Clerk Setup: Configure production Clerk app
2. Convex Deploy: Deploy Convex functions to production
3. Environment Variables: Set production environment variables
4. DNS/Domains: Configure custom domains in Clerk dashboard

Security Considerations

• Clerk handles all authentication security
• Convex functions validate user permissions
• Admin actions require proper role verification
• Rate limiting on contact requests through quota system