fix issue causing the better-auth table to be deleted after db reset

Author: ib729

docs/authentication.md

@@ -49,9 +49,19 @@ openssl rand -base64 32
 
 ## Database Setup
 
-### Run Better Auth Migration
+### Better Auth Tables
 
 The authentication system requires additional database tables:
+- `user` - User accounts with email, name, image
+- `session` - Active user sessions
+- `account` - OAuth and credential accounts
+- `verification` - Email verification and password reset tokens
+
+**Automatic Setup**: These tables are automatically created when you run `python init_db.py` or any database reset script.
+
+**Manual Migration** (if needed):
+
+If you have an existing database without Better Auth tables, you can add them manually:
 
 ```bash
 cd web-next
@@ -65,12 +75,6 @@ cd web-next
 pnpm auth:migrate
 ```
 
-This creates the following tables:
-- `user` - User accounts with email, name, image
-- `session` - Active user sessions
-- `account` - OAuth and credential accounts
-- `verification` - Email verification and password reset tokens
-
 **Note**: The migration script is idempotent and safe to run multiple times.
 
 ### Schema Details

docs/database-reset-fix.md

@@ -0,0 +1,56 @@
+# Database Reset Fix - Better Auth Tables
+
+## Problem
+When resetting the database using `init_db.py`, `reset_db.py`, or `scripts/reset_db.sh`, the Better Auth tables were not being created, causing "Failed to sign up" errors.
+
+## Root Cause
+The database initialization scripts only loaded `migrations/schema.sql`, which contains the main application tables (students, cards, accounts, etc.) but not the Better Auth tables (user, session, account, verification).
+
+## Solution Applied
+Updated all database initialization scripts to automatically include Better Auth schema:
+
+### Files Modified
+1. **`init_db.py`** - Added Better Auth schema loading
+2. **`reset_db.py`** - Added Better Auth schema to initialize_database()
+3. **`scripts/reset_db.sh`** - Added Better Auth migration step
+
+### Documentation Updated
+1. **`docs/getting-started.md`** - Updated Database Setup section to mention Better Auth tables
+2. **`docs/authentication.md`** - Clarified that Better Auth tables are now automatic
+3. **`docs/troubleshooting.md`** - Updated signup code troubleshooting and added "Failed to sign up" section
+
+## How It Works Now
+When you run any of these commands:
+```bash
+python init_db.py
+python reset_db.py
+./scripts/reset_db.sh
+```
+
+They will automatically:
+1. Create main tables from `migrations/schema.sql`
+2. Create Better Auth tables from `web-next/migrations/better_auth_schema.sql`
+3. Print confirmation that both schemas were applied
+
+## Verification
+After any database reset, verify all tables exist:
+```bash
+sqlite3 stuco.db ".tables"
+```
+
+Should include: `account`, `session`, `user`, `verification` (Better Auth) plus your application tables.
+
+## Environment Variable Fix
+Also fixed the signup code issue:
+- The `SIGNUP_CODE` environment variable in `web-next/.env.local` should NOT have quotes
+- Correct: `SIGNUP_CODE=Xn0tj#9y`
+- Wrong: `SIGNUP_CODE="Xn0tj#9y"`
+
+After changing environment variables, always restart the web server:
+```bash
+sudo systemctl restart stuco-web
+```
+
+## Date Applied
+November 13, 2025
+

docs/getting-started.md

@@ -80,15 +80,17 @@ This verifies all tools and provides installation instructions if missing.
    python init_db.py
    ```
 
-   This creates `stuco.db` with the schema from `migrations/schema.sql` (students, cards, accounts, transactions, overdraft_weeks).
+   This creates `stuco.db` with:
+   - Main schema from `migrations/schema.sql` (students, cards, accounts, transactions, overdraft_weeks)
+   - Better Auth schema (user, session, account, verification) for web authentication
 
 2. **Verify**:
 
    ```bash
    sqlite3 stuco.db ".tables"
    ```
 
-   Should show all tables.
+   Should show all tables including Better Auth tables (account, session, user, verification).
 
 3. **Optional: Run Migrations** (if needed):
 

docs/troubleshooting.md

@@ -150,23 +150,27 @@ pnpm install
 
 **Solutions**:
 
-1. **Verify Code in Source**:
+1. **Check Environment Variable**:
 
-   Check `web-next/app/(auth)/signup/page.tsx`:
-   ```typescript
-   const SIGNUP_CODE = "12345678"; // Current code
+   Verify the `SIGNUP_CODE` is set in `web-next/.env.local`:
+   ```env
+   SIGNUP_CODE=your_code_here
    ```
-
-2. **Check Environment Variable**:
 
-   If using env var, verify `.env.local`:
-   ```env
-   NEXT_PUBLIC_SIGNUP_CODE=your_code
+   Note: Do NOT use quotes around the value (use `SIGNUP_CODE=abc123` not `SIGNUP_CODE="abc123"`)
+
+2. **Restart Server**: After changing `.env.local`, restart the server:
+   ```bash
+   cd web-next
+   # Stop the server (Ctrl+C), then:
+   pnpm dev
+   # Or in production:
+   sudo systemctl restart stuco-web
    ```
 
-3. **Restart Server**: After changing code, restart dev server
+3. **Verify Code Has No Spaces**: Ensure the code has no leading/trailing spaces
 
-4. **No Spaces**: Ensure code has no leading/trailing spaces
+4. **Check Server Logs**: Look for "SIGNUP_CODE environment variable is not set" errors
 
 ### "CORS error" or "Origin not allowed"
 
@@ -176,13 +180,37 @@ pnpm install
 2. **Check trustedOrigins**: In `web-next/lib/auth.ts`
 3. **Browser Console**: Check exact error message
 
+### "Failed to sign up" Error
+
+**Problem**: Signup code is accepted but account creation fails.
+
+**Cause**: Better Auth database tables are missing (usually after a database reset).
+
+**Solution**:
+
+Since v2.0+, Better Auth tables are automatically created by `init_db.py` and reset scripts. If you're using an older database or manually reset it, run:
+
+```bash
+cd web-next
+sqlite3 ../stuco.db < migrations/better_auth_schema.sql
+sudo systemctl restart stuco-web
+```
+
+**Verify tables exist**:
+```bash
+sqlite3 stuco.db "SELECT name FROM sqlite_master WHERE type='table' AND name IN ('user', 'session', 'account', 'verification');"
+```
+
+Should return all 4 table names.
+
 ### "Database error" or "Table not found"
 
 **Solutions**:
 
-1. **Run Migration**: See [Authentication Guide](authentication.md#database-setup)
-2. **Check DATABASE_PATH**: Must be absolute path
-3. **Verify Permissions**: Database file must be readable/writable
+1. **Check Better Auth Tables**: Run the verification command above to ensure auth tables exist
+2. **Run Database Init**: If starting fresh, use `python init_db.py` (automatically includes Better Auth tables)
+3. **Check DATABASE_PATH**: Must be absolute path in `.env.local`
+4. **Verify Permissions**: Database file must be readable/writable by the web server user
 
 ### Testing Authentication
 

init_db.py

@@ -2,16 +2,27 @@
 
 DB = "stuco.db"
 SCHEMA_FILE = "migrations/schema.sql"
+BETTER_AUTH_SCHEMA = "web-next/migrations/better_auth_schema.sql"
 
 con = sqlite3.connect(DB)
 con.execute("PRAGMA journal_mode=WAL;")   # enable Write-Ahead Logging for smoother writes/reads
 con.execute("PRAGMA foreign_keys=ON;")    # enforce FK relations
 con.execute("PRAGMA busy_timeout=5000;")  # handle brief contention politely
 
+# Load main schema
 with open(SCHEMA_FILE,"r",encoding="utf-8") as f:
     con.executescript(f.read())
 
+# Load Better Auth schema
+if os.path.exists(BETTER_AUTH_SCHEMA):
+    with open(BETTER_AUTH_SCHEMA,"r",encoding="utf-8") as f:
+        con.executescript(f.read())
+    print("✓ Better Auth schema applied")
+else:
+    print("⚠ Better Auth schema not found, skipping")
+
 con.commit()
 con.close()
 print("Database initialized at", os.path.abspath(DB))
+print("✓ Main schema applied")
 

reset_db.py

@@ -66,9 +66,19 @@ def initialize_database():
     con.execute("PRAGMA foreign_keys=ON;")
     con.execute("PRAGMA busy_timeout=5000;")
 
+    # Load main schema
     with open(SCHEMA_FILE, "r", encoding="utf-8") as f:
         con.executescript(f.read())
 
+    # Load Better Auth schema
+    BETTER_AUTH_SCHEMA = "web-next/migrations/better_auth_schema.sql"
+    if os.path.exists(BETTER_AUTH_SCHEMA):
+        with open(BETTER_AUTH_SCHEMA, "r", encoding="utf-8") as f:
+            con.executescript(f.read())
+        print("✓ Better Auth schema applied")
+    else:
+        print("⚠ Better Auth schema not found, skipping")
+    
     con.commit()
     return con
 

scripts/reset_db.sh

@@ -68,6 +68,13 @@ echo "------------------------------------------------------------"
 # Initialize database
 python3 init_db.py
 
+# Apply Better Auth migration
+if [ -f "web-next/migrations/better_auth_schema.sql" ]; then
+    echo "Applying Better Auth migration..."
+    sqlite3 "$DB_FILE" < "web-next/migrations/better_auth_schema.sql"
+    echo "✓ Better Auth schema applied"
+fi
+
 echo ""
 echo "============================================================"
 echo "✓ Database reset complete!"