[0.4] User Signup

1. Front Matter

• Title: User Signup

• Author: Sean Patrick Caintic

• Reviewers: Joshua Uriel Tribiana

• Created: February 2026

• Status: Approved

• References:

  • Issue: [0.4] User SignUp #14

  • Milestone: [0] Auth & Security

2. Introduction & Goals

• Problem Summary: New users need a secure, frictionless way to create accounts. The system should support both traditional email/password and social login (Google OAuth) while syncing user data to the application database.

• Goals:

  • Enable email/password registration with OTP verification

  • Support Google OAuth for one-click signup

  • Sync new users to app_users table via webhook

  • Assign default CREATOR role

• Non-Goals:

  • Additional OAuth providers (GitHub, Facebook)

  • Passwordless/magic link signup

  • Admin-created accounts

• Glossary:

  • OTP: One-time password for email verification

  • Webhook: Server-to-server callback from Clerk on user events

3. High-Level Architecture

• System Diagram:

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Signup Form    │────▶│  Clerk Auth     │────▶│  User Creation  │
│  (Email/Google) │     │  (Registration) │     │  (Clerk)        │
└─────────────────┘     └─────────────────┘     └─────────────────┘
        │                       │                       │
        ▼                       ▼                       ▼
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Email Verify   │     │  OAuth Consent  │     │  Webhook Sync   │
│  (OTP Flow)     │     │  (Google)       │     │  (app_users)    │
└─────────────────┘     └─────────────────┘     └─────────────────┘

• Technologies Used:

  • Clerk - Authentication, OAuth, email verification

  • Svix - Webhook signature verification

  • Supabase - User data storage (app_users)

4. Detailed Design & Implementation

• Data Model / Schema:

  app_users Table:

  Column	Type	Description
  id	UUID PK	Auto-generated
  clerk_id	TEXT UNIQUE	Clerk user ID
  email	TEXT	Primary email
  first_name	TEXT	From registration
  last_name	TEXT	From registration
  avatar_url	TEXT	Profile image URL
  role	TEXT	Default: CREATOR
  agency_id	UUID FK	Optional agency association
  created_at	TIMESTAMPTZ	Registration timestamp

• API Specification:

  • POST /api/webhooks/clerk - Clerk webhook for user sync

  Webhook Events Handled:

  • user.created → Insert to app_users

  • user.updated → Update app_users

  • user.deleted → Soft delete from app_users

• Logic & Workflows:

  Email Registration Flow:

  1. User enters email + password

  2. Clerk sends OTP to email

  3. User enters OTP code

  4. Account created in Clerk

  5. Webhook triggers → sync to app_users

  6. Redirect to /creator

  Google OAuth Flow:

  1. User clicks "Sign up with Google"

  2. Google consent screen

  3. Profile imported (name, avatar, email pre-verified)

  4. Account created in Clerk

  5. Webhook triggers → sync to app_users

  6. Redirect to /creator

  Key Files:

  • app/(auth)/sign-up/[[...sign-up]]/page.tsx - Signup form

  • app/api/webhooks/clerk/route.ts - Webhook handler

5. Infrastructure & Operations

• Dependencies:

  • Clerk - Authentication

  • Google OAuth - Social login

  • Supabase - User data storage

• Monitoring & Alerting:

  • Clerk Dashboard: Registration metrics, failed signups

  • Supabase Logs: Webhook insert failures

• Deployment Plan:

  1. Configure CLERK_WEBHOOK_SECRET env var

  2. Add webhook endpoint URL in Clerk dashboard

  3. Test webhook with Clerk CLI

  4. Deploy to production

6. Testing & Quality Assurance

• Test Strategy:

  • Manual: Email signup, Google OAuth

  • Integration: Webhook sync to app_users

• Known Limitations:

  • Only Google OAuth supported (no GitHub, Facebook)

  • Email verification required for email signups

7. Maintenance & Support

• Troubleshooting:

  • User not in app_users → Check webhook logs, verify signature

  • Google OAuth fails → Verify Google OAuth credentials in Clerk

  • Email already exists → User may have existing account

• Changelog:

  • 1.0 (Feb 2026): Initial implementation

Document Version

1.0 - Approved, Feature deployed to production, 02/14/2026