Convex + Better Auth Dual-Database Architecture

Problem

When using Better Auth with Convex, users exist in TWO separate locations:

1. Better Auth component tables: betterAuth.user, betterAuth.account, betterAuth.session
2. App's users table: Your custom users table in the main schema

This causes confusing errors like "User not found" when the user exists in one location but not the other.

Context / Trigger Conditions

• "User not found" during login or password reset, but you see the user in your app's database
• User can't authenticate despite having a record in the users table
• Need to manually create an admin user in production
• Debugging auth flows where users should exist but operations fail
• Export shows users in _components/betterAuth/user/documents.jsonl separate from users/documents.jsonl

Architecture