Workflow: User Registration (Sign Up)

This document details the critical path for a new user signing up to LogicSpike. It involves a Distributed Transaction across multiple entities (User, Identity, Tenant, Membership).

1. The Flow Chart

2. Step-by-Step Logic

Step 1: Input Validation

• Endpoint: POST /api/v1/auth/register
• Body:
  • email: Email, required.
  • password: Min 8 chars, 1 uppercase, 1 symbol.
  • name: String (Optional, defaults to "User").
• Check: Does email already exist?
  • Optimisation: unique constraint on DB will catch this, but a pre-check saves DB/Hashing CPU processing.

Step 2: Hashing

• Algorithm: Argon2id.
• Salt: Randomly generated by the library.
• Result: A string like $argon2id$v=19$m=65536,t=3,p=1$... stored in password_hash.

Step 3: Verification (OTP)

Before creating the user, we verify ownership of the contact method.

1. Frontend: Calls POST /auth/send-otp (Body: { "email": "..." }).
2. Manager API:
   • Generates 6-digit code (e.g., 123456).
   • Stores in verifications table (Expires in 10m).
   • Sends Email (Resend).
3. Frontend: Prompts user for code.
4. Manager API: POST /auth/verify-otp.
   • Checks code.
   • Returns verification_token (Short-lived JWT, signed with secret).
5. Frontend: Calls POST /auth/register with verification_token.

Step 4: The "Starter" Entities (Transaction)

When a user signs up, we don't just create a user. We create their World. We must ensure All or Nothing execution.

1. User: The identity record.
2. Auth Provider: The password record.
3. Tenant: "My Workspace" (Default name).
4. Membership: Link User -> Tenant as Owner.
5. Entitlements: Populate tenant_services with the "Free Plan" defaults (Blog: enabled, Store: disabled).

Step 4: Token Generation

• Access Token:
  • sub: User ID
  • tid: New Tenant ID
  • role: "owner"
  • permissions: ["*"] (Wildcard for owner)
  • exp: 15 minutes
• Refresh Token:
  • sub: User ID
  • exp: 7 days
  • Stored in HTTPOnly Cookie.

3. Edge Cases

• Email Collision: Return 409 Conflict.
• Database Down during Transaction: Rollback everything. User is not created.
• Rate Limiting: Prevent bot spam creation (5 req/min per IP).

4. OAuth Registration (Sign up with Google)

The Difference

Instead of a password, we receive a Trusted Identity from Google.

The Flow

1. Frontend: Redirects to GET /auth/oauth/google.
2. User: Approves access on Google.
3. Callback: Google redirects to GET /auth/oauth/google/callback?code=xyz.
4. Manager API:
   • Exchanges code for id_token.
   • Extracts email and sub (Google ID).

The Logic (Smart Linking)

• Scenario A: Brand New User
  • Action: Same transaction as Email/Password (Create User, Tenant, Membership).
  • Auth Provider: Insert { provider: "google", provider_user_id: "sub_123", password: NULL }.
• Scenario B: Existing User (Same Email)
  • Action: Detect email exists.
  • Link: Insert new row into user_auth_providers { user_id: existing_id, provider: "google", ... }.
  • Result: User can now login with BOTH Password and Google.

5. User Journey: The Registration Experience

Persona: Sarah (Freelancer)

Goal: Sarah wants to start a blog using LogicSpike.

Step 1: The Landing Page

• Sarah visits logicspike.com.
• She enters her email sarah@freelance.com in the hero section and clicks "Get Started".

Step 2: The Choice

• She is taken to /register.
• Screen asks: "How do you want to sign in?"
  • [ Button ] Continue with Google
  • [ Input ] Password
• Sarah chooses Password to keep it separate from her personal Gmail.

Step 3: The Setup

• She enters a strong password.
• System prompts: "What should we call your workspace?"
• She types: "Sarah's Design Log" (System generates slug sarahs-design-log).

Step 4: The magic

• She clicks "Create Account".
• Spinner... (1.2s).
• Success! She is redirected to sarahs-design-log.logicspike.com/dashboard.

Step 5: Onboarding

• A welcome modal appears: "Welcome to your new workspace, Sarah!".
• She sees "Step 1: Write your first post".
• She is now the Owner of this tenant.