Skip to main content

Source: ocean/docs/adr/017-synchronous-user-provisioning.md | ✏️ Edit on GitHub

17. Synchronous User Provisioning During Signup

Date: 2025-08-13

Status​

Accepted

Context​

Our platform requires provisioning resources in external services (Stripe and Neon) when users sign up. The initial implementation used an asynchronous webhook-based approach that had several critical issues:

  1. Silent Failures: Provisioning failures were not visible to users, resulting in broken accounts
  2. Poor User Experience: Users could log in to incomplete accounts missing critical resources
  3. No Rollback: Failed provisioning left partial data across systems
  4. Debugging Difficulty: Async webhooks made it hard to trace provisioning failures

Decision​

We will provision user resources synchronously during the signup flow, specifically during the window between sending the OTP email and the user entering their verification code.

Implementation Details​

  1. Provisioning Trigger: Immediately after signInWithOtp succeeds (user created, email sent) — before OTP entry
  2. Parallel Execution: Stripe customer and Neon database creation happen concurrently with idempotency guards
  3. GraphQL Mutation: Direct API call via provisionUserResources(email, metadata) — server derives userId by email using service role
  4. Fire-and-Forget: Provisioning runs in background while user waits for email; resolver may short-poll for the organization record
  5. Region Selection: Users must select their data region during signup (permanent choice)

Architecture Flow​

User Signup Form
    ↓
signInWithOtp (Creates user, sends email)
    ↓
provisionUserResources(email, metadata) (Runs immediately)
    ├─→ Create Stripe Customer
    └─→ Create Neon Database
    ↓
User enters OTP code
    ↓
User logs in (resources ready)

Data Storage​

  • Supabase: User profiles, organizations, database metadata, billing information
  • Neon: Actual tenant databases (region-specific)
  • Stripe: Customer records and billing data

Region Mapping​

We support 6 Neon regions mapped from user selection:

  • us-east-1 → aws-us-east-1
  • us-east-2 → aws-us-east-2
  • us-west-2 → aws-us-west-2
  • eu-central-1 → aws-eu-central-1
  • eu-west-2 → aws-eu-west-2
  • ap-southeast-1 → aws-ap-southeast-1

Consequences​

Positive​

  1. Immediate Feedback: Provisioning errors can be logged and monitored
  2. Better UX: Resources are ready by the time user completes signup
  3. Simplified Architecture: No webhook complexity or retry logic needed
  4. Easier Debugging: Direct API calls with clear error paths
  5. Time Efficiency: Uses the natural waiting period (email delivery) productively

Negative​

  1. No User Feedback on Failure: Since it's fire-and-forget, users won't see provisioning errors
  2. Potential Orphaned Accounts: User accounts may exist without properly provisioned resources
  3. No Retry Logic: Failed provisioning requires manual intervention

Mitigations​

  1. Monitoring: Sentry alerts on provisioning failures for immediate response
  2. Admin Tools: Build admin interface to manually trigger re-provisioning
  3. Health Checks: Regular checks for accounts missing resources

Alternatives Considered​

  1. Synchronous Blocking: Wait for provisioning before showing OTP screen

    • Rejected: Would add 3-5 seconds to signup flow

  2. Webhook with Retry: Keep async but add retry logic

    • Rejected: Complex, still has visibility issues

  3. Two-Phase Signup: Create account first, provision on first login

    • Rejected: Poor UX, users expect immediate access

Implementation Notes​

  • API Keys stored in Supabase Edge Function secrets
  • Stripe requests include an Idempotency-Key per organization to avoid duplicates
  • Neon connection string stored in Supabase Secrets (Vault); no plaintext credentials in tables
  • Resolver derives user by email (service role) and short-polls briefly for organization creation if needed
  • Region mapping centralized; UI values are AWS-style (e.g., us-east-1)
  • Region selection is permanent (cannot be changed after creation)
  • Clear UI warnings about permanent region choice
  • Provisioning errors logged to Sentry for monitoring; metrics emitted for attempts/success/errors

References​