User Onboarding Flow

Complete user journey from anonymous visitor to fully verified platform user.

Overview

The onboarding flow consists of several stages:

1. Anonymous visit with referral attribution
2. Registration and email verification
3. Profile completion
4. KYC verification (required for investments and payouts)

---

Main Flow Diagram

---

Step Details

1. Anonymous Visit

Trigger: User lands on the platform via referral link or direct visit.

Referral Link Format:

https://platform.com/?ref=ABC123&utm_source=instagram&utm_medium=post&utm_campaign=summer

Cookie Storage:

Key	Value	Duration
iwm_ref_code	Partner referral code	30 days
iwm_ref_link_id	Specific link ID (if tracked)	30 days
iwm_first_touch	First visit timestamp	30 days
iwm_utm	JSON with UTM params	Session

Attribution Data Stored:

{
  "partner_code": "ABC123",
  "link_id": "uuid-of-link",
  "first_touch_at": "2024-01-15T10:30:00Z",
  "last_touch_at": "2024-01-15T10:30:00Z",
  "utm_source": "instagram",
  "utm_medium": "post",
  "utm_campaign": "summer",
  "landing_page": "/products",
  "ip_address": "192.168.1.1",
  "user_agent": "Mozilla/5.0..."
}

---

2. Registration

Endpoint: POST /auth/register

Request Body:

{
  "email": "user@example.com",
  "password": "SecureP@ss123",
  "firstName": "John",
  "lastName": "Doe",
  "phone": "+7900123456",
  "acceptTerms": true,
  "acceptMarketing": false
}

Validation Rules:

Field	Rules
email	Required, valid email format, unique in DB
password	Min 8 chars, 1 uppercase, 1 lowercase, 1 number, 1 special
firstName	Required, 2-100 chars, letters only
lastName	Required, 2-100 chars, letters only
phone	Optional, E.164 format
acceptTerms	Required, must be true

Error Scenarios:

Code	Scenario	Response
400	Validation failed	{ "errors": [...] }
409	Email exists	{ "code": "EMAIL_EXISTS" }
429	Rate limit exceeded	Retry-After header

---

3. Email Verification

Verification Token:

• Format: UUID v4
• Expiry: 24 hours
• Single use (deleted after verification)

Verification Email Content:

• Subject: "Verify your email - IWM Platform"
• Link: https://platform.com/verify?token={token}
• Includes: User name, expiry notice, support contact

Resend Logic:

• Max 3 resends per hour
• New token generated each time
• Previous tokens invalidated

Timeout Handling:

• Token expires after 24 hours
• User can request new token
• Account auto-deleted after 7 days if unverified

---

4. Profile Completion

Endpoint: PATCH /users/me/profile

Optional Fields:

{
  "middleName": "Ivanovich",
  "dateOfBirth": "1990-05-15",
  "avatarUrl": "https://cdn.example.com/avatar.jpg",
  "language": "ru",
  "timezone": "Europe/Moscow"
}

Avatar Upload:

• Endpoint: POST /users/me/avatar
• Max size: 5MB
• Formats: JPEG, PNG, WebP
• Resized to: 200x200, 400x400

---

5. KYC Submission

KYC Levels:

Level	Requirements	Capabilities
NONE	Default	Browse, basic purchases
BASIC	Email verified	All purchases
STANDARD	ID + Selfie verified	Investments up to 1M RUB
ENHANCED	Address proof + Income proof	Unlimited investments

Required Documents (STANDARD):

Document	Accepted Types
ID Document	Passport, National ID, Driver's License
Selfie	Photo with ID visible

Document Upload:

• Endpoint: POST /kyc/documents
• Max size: 10MB per file
• Formats: JPEG, PNG, PDF
• Encrypted at rest (AES-256)

Validation Rules:

• Document must be legible
• Selfie must clearly show face and ID
• ID not expired
• Name matches profile

---

6. KYC Review Process

Status Flow:

NOT_STARTED -> DOCUMENTS_PENDING -> SUBMITTED -> UNDER_REVIEW -> APPROVED/REJECTED/NEEDS_INFO

Review Timeline:

• Standard: 24-48 business hours
• Priority (large investments): 4-8 hours

Rejection Reasons:

Code	Description	User Action
DOCUMENT_BLURRY	Document not readable	Re-upload clearer image
DOCUMENT_EXPIRED	ID has expired	Upload valid ID
SELFIE_MISMATCH	Face doesn't match ID	Retake selfie
INFO_MISMATCH	Details don't match profile	Update profile or upload correct docs
SUSPECTED_FRAUD	Suspicious activity	Contact support

Re-submission:

• Max 3 attempts per document type
• After 3 failures, manual review required
• Cool-down: 24 hours between submissions

---

Error Scenarios

Registration Errors

Scenario	HTTP Code	Error Code	User Message
Email already registered	409	EMAIL_EXISTS	"This email is already registered. Try logging in."
Weak password	400	WEAK_PASSWORD	"Password does not meet requirements."
Invalid email format	400	INVALID_EMAIL	"Please enter a valid email address."
Terms not accepted	400	TERMS_REQUIRED	"You must accept the terms to continue."
Rate limited	429	RATE_LIMITED	"Too many attempts. Please wait."

Verification Errors

Scenario	HTTP Code	Error Code	User Message
Token expired	400	TOKEN_EXPIRED	"This link has expired. Request a new one."
Token already used	400	TOKEN_USED	"This link has already been used."
Token not found	404	TOKEN_NOT_FOUND	"Invalid verification link."

KYC Errors

Scenario	HTTP Code	Error Code	User Message
File too large	413	FILE_TOO_LARGE	"File exceeds 10MB limit."
Invalid file type	400	INVALID_FILE_TYPE	"Please upload JPEG, PNG, or PDF."
KYC already approved	400	ALREADY_VERIFIED	"Your identity has already been verified."
Max attempts exceeded	400	MAX_ATTEMPTS	"Please contact support for assistance."

---

Related Documents

• Architecture Overview
• Core Schema (Users, KYC)
• Auth Flow Diagram
• Partner Journey
• Security Standards