Onboarding Flow

Audience: Customer — this page documents the account setup and onboarding process.

Complete walkthrough of the Rulecatch signup and onboarding process, from first visit to data appearing in the dashboard.

Flow Overview

Select Region → Register → Verify Email → Onboarding Step 1 (Account Type) →
Onboarding Step 2 (Plan) → Payment (Stripe) → Environment (Stack) → Dashboard

Step 1: Select Region

URL: /select-region

The user chooses where their data will be stored:

Region	Location	Domain
United States	Virginia (us-east-1)	`dashboard.rulecatch.ai`
European Union	Frankfurt (eu-central-1)	`dashboard-eu.rulecatch.ai`

This selection determines which VPS cluster, MongoDB instance, and API endpoint will handle the user's data. The choice is driven by GDPR compliance requirements.

After selecting, the user is redirected to the registration page with the region as a query parameter.

Step 2: Register

URL: /register?region=us (or eu)

Field	Validation
Email	Required, valid email format
Password	Required, minimum length

POST /api/v1/auth/register

The registration endpoint:

Validates input
Checks for existing account
Hashes the password
Creates the user record in MongoDB
Generates an API key (dc_ prefix)
Sends a verification email via SendGrid
Creates a NextAuth session

Step 3: Verify Email

URL: /verify-email

The user receives an email with a verification code. They enter the code on this page.

POST /api/v1/auth/verify-email

The endpoint validates the code and marks the user's email as verified. The user is then redirected to the onboarding flow.

If the user doesn't have a code, they can request a new one.

Step 4: Onboarding — Account Type

URL: /onboarding (step 1)

The user selects their account type:

Type	Description
Individual	Solo developer
Team	Small team
Enterprise	Organization

This informs the recommended plan in the next step.

Step 5: Onboarding — Plan Selection

URL: /onboarding (step 2)

Three plan cards are displayed:

Plan	Price	Highlight
Starter	$49/seat/mo	Basic tracking
Pro	$199/seat/mo	"Popular" badge, full analytics
Enterprise	$499/seat/mo	Custom rules, SSO, compliance

All plans include a 7-day trial.

POST /api/v1/user/save-onboarding

Saves the selected plan to the user record.

Step 6: Payment

URL: /onboarding/payment

Stripe Elements embedded payment form:

User enters card details
Client calls POST /api/v1/billing/create-subscription
Server creates a Stripe subscription with trial period
Payment intent is confirmed via Stripe Elements
On success, user is redirected to environment selection

The payment page includes a TestModeHelper component in development that shows test card numbers.

Step 7: Environment (Stack Selection)

URL: /onboarding/environment

The final onboarding step. The user selects their technology stack:

Languages: TypeScript, JavaScript, Python, Go, Rust, etc.
Frameworks: React, Next.js, Express, Django, etc.
Databases: MongoDB, PostgreSQL, Redis, etc.
Tools: Docker, Git, CI/CD, etc.

POST /api/v1/user/save-stack

This endpoint:

Saves the stack selection to the user record
Maps selected technologies to rule categories
Calls assignUserRules() to sync matching rule templates from Global.ruleTemplates
Returns the number of activated categories

The user can skip this step and go directly to the dashboard (with no rules activated).

Step 8: Dashboard

URL: /dashboard

After onboarding, the user lands on the dashboard. If no events have been sent yet, the empty state shows a setup wizard with instructions to install the CLI.

Onboarding State

The user's onboarding progress is tracked in their database record:

Field	Values
`onboardingStep`	`account-type`, `plan`, `payment`, `environment`, `complete`
`accountType`	`individual`, `team`, `enterprise`
`selectedPlan`	`starter`, `pro`, `enterprise`
`stack`	Object with selected technologies
`emailVerified`	Boolean

The middleware checks onboarding state and redirects incomplete users back to the appropriate step.

Trial Period

All new accounts start with a 7-day trial:

Trial provides Pro-level features
Data retention: 14 days during trial
After trial expires, the user must subscribe to continue
The AI-Pooler pauses data collection on expired subscriptions
Users can reactivate with npx @rulecatch/ai-pooler reactivate after subscribing

Auth Flow

Authentication uses NextAuth 5.0.0-beta with:

Credentials provider — Email/password login
JWT strategy — Session stored as signed JWT in cookie
Session callback — Validates user still exists in database
Middleware — Protects dashboard routes, redirects unauthenticated users

Key API Endpoints

Endpoint	Method	Purpose
`/api/v1/auth/register`	POST	Create account
`/api/v1/auth/verify-email`	POST	Verify email code
`/api/v1/user/save-onboarding`	POST	Save onboarding choices
`/api/v1/billing/create-subscription`	POST	Create Stripe subscription
`/api/v1/user/save-stack`	POST	Save tech stack and activate rules
`/api/auth/callback/credentials`	POST	NextAuth login