Skip to main content

WF-001: User Registration Workflow

Overview​

This workflow handles new user registration for CODITECT, creating user accounts in Firebase Auth, storing user data in PostgreSQL, and initializing the user's personal organization.

Trigger: HTTP POST to /register endpoint Duration: ~2-5 seconds Related Workflows: WF-002 (Subscription Checkout), WF-004 (Workstation Provisioning)

Prerequisites​

Before starting, ensure you have:

  • Required tools installed
  • Access to necessary resources
  • Basic understanding of concepts

Verify setup:

# Verification command

Workflow Diagram​

User Registration Flow

Step-by-Step Narrative​

Step 1: Registration Request Received​

  • Node: Registration Webhook
  • Type: HTTP POST Endpoint
  • Path: /register
  • Actions:
    • Receives registration payload from web application
    • Validates required fields: email, password, display_name
    • Extracts optional fields: company_name, referral_code
    • Passes validated data to next node

Step 2: Create Firebase User​

  • Node: Firebase Create User
  • Type: HTTP Request to Firebase Admin API
  • Actions:
    • Calls Firebase Admin SDK endpoint
    • Creates user with email and password
    • Sets emailVerified: false initially
    • Returns Firebase uid for subsequent operations
    • Handles duplicate email errors (returns 400)

Step 3: Insert User Record in Database​

  • Node: Insert User Record
  • Type: PostgreSQL Insert
  • Table: public.users
  • Actions:
    • Generates UUID for internal user ID
    • Stores Firebase UID for authentication reference
    • Records email, display name, preferences
    • Sets created_at timestamp
    • Sets subscription_status: 'trial'

Step 4: Create Personal Organization​

  • Node: Create Personal Org
  • Type: PostgreSQL Insert
  • Table: public.organizations
  • Actions:
    • Creates default organization for the user
    • Names it "{display_name}'s Workspace"
    • Sets user as owner in organization_members
    • Assigns subscription_tier: 'free'
    • Initializes with 1 seat allowance

Step 5: Send Welcome Email​

  • Node: Send Welcome Email
  • Type: Email Send (SMTP/SendGrid)
  • Actions:
    • Sends branded HTML welcome email
    • Includes verification link with token
    • Provides "Get Started" call-to-action
    • Links to documentation and support
    • Sent from: welcome@coditect.ai

Step 6: Publish User Created Event​

  • Node: Publish User Event
  • Type: Google Cloud Pub/Sub
  • Topic: projects/coditect-prod/topics/user-events
  • Actions:
    • Publishes user.created event
    • Includes user ID, organization ID, timestamp
    • Enables downstream analytics and integrations
    • Triggers any registered event subscribers

Step 7: Return Success Response​

  • Node: Success Response
  • Type: Webhook Response
  • Actions:
    • Returns HTTP 200 with JSON body
    • Includes user_id and org_id
    • Confirms email_verification_sent: true
    • Client can now redirect to dashboard

Data Flow​

Input:
{
  "email": "user@example.com",
  "password": "SecurePass123!",
  "display_name": "John Doe",
  "company_name": "Acme Corp"  // optional
}

Output:
{
  "success": true,
  "user_id": "uuid-here",
  "org_id": "uuid-here",
  "email_verification_sent": true
}

Error Handling​

ErrorCauseResponse
400 Bad RequestMissing required fields{ "error": "Email is required" }
409 ConflictEmail already exists{ "error": "Email already registered" }
500 Internal ErrorFirebase/DB failure{ "error": "Registration failed, please try again" }

Security Considerations​

  • Password hashed by Firebase (bcrypt with salt)
  • Email verification required before full access
  • Rate limiting on registration endpoint (10/minute per IP)
  • CAPTCHA required for suspicious patterns
  • Audit log entry created for compliance

Troubleshooting​

Common Issue 1​

Problem: Description of issue Solution: Steps to resolve

Common Issue 2​

Problem: Description of issue Solution: Steps to resolve

Next Steps​

After completing this guide:

  1. Explore: Additional related features
  2. Practice: Apply concepts in your project
  3. Reference: Related documentation