{"slug":"strategy/business-strategy/USER_ONBOARDING_FLOW","title":"User Onboarding Flow","section":"strategy","sectionLabel":"Strategy","status":"unclassified","type":"document","path":"strategy/business-strategy/USER_ONBOARDING_FLOW.mdx","bytes":23542,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n> **Status: CURRENT CODE-DERIVED VIEW, NOT A CANONICAL CONTRACT.** Use this file\n> to trace the implemented onboarding path. If behavior conflicts with\n> [`docs/architecture/ARCHITECTURE_LOCK.md`](docs/architecture/ARCHITECTURE_LOCK.md)\n> or\n> [`docs/architecture/CONSOLIDATED_PRODUCT_PLATFORM_CONTRACT_v1.2.md`](docs/architecture/CONSOLIDATED_PRODUCT_PLATFORM_CONTRACT_v1.2.md),\n> the frozen contracts win.\n\n**Generated:** July 29, 2026  \n**Based on:** Frontend onboarding implementation, Gateway onboarding service, Workspace API\n\n---\n\n## High-Level Onboarding Flow\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│                          ENTRY POINTS                                         │\n├─────────────────────────────────────────────────────────────────────────────┤\n│                                                                             │\n│  ┌──────────────┐                    ┌──────────────┐                      │\n│  │   Direct     │                    │  Marketplace  │                      │\n│  │   Sign-up    │                    │   Connector  │                      │\n│  └──────┬───────┘                    └──────┬───────┘                      │\n│         │                                   │                               │\n│         └─────────────────┬─────────────────┘                               │\n│                           │                                                  │\n│                           ▼                                                  │\n│                    ┌──────────────┐                                         │\n│                    │ Clerk OAuth  │                                         │\n│                    │  (Google/    │                                         │\n│                    │   GitHub)    │                                         │\n│                    └──────┬───────┘                                         │\n│                           │                                                  │\n│                           ▼                                                  │\n│              ┌──────────────────────────────┐                                │\n│              │  Gateway: getOrCreateUser    │                                │\n│              │  - Check existing user       │                                │\n│              │  - Create new user if needed  │                                │\n│              │  - Set onboarding intent     │                                │\n│              └──────────────┬───────────────┘                                │\n│                           │                                                  │\n│                           ▼                                                  │\n└───────────────────────────────────┼───────────────────────────────────────────┘\n                                    │\n┌───────────────────────────────────┼───────────────────────────────────────────┐\n│                      ONBOARDING SHELL (4 Steps)                               │\n├───────────────────────────────────┼───────────────────────────────────────────┤\n│                                   │                                          │\n│         ┌─────────────────────────┼─────────────────────────┐                 │\n│         │                         │                         │                 │\n│         ▼                         ▼                         ▼                 │\n│  ┌──────────────┐        ┌──────────────┐        ┌──────────────┐              │\n│  │   Step 1     │        │   Step 2     │        │   Step 3     │              │\n│  │   Welcome    │        │   Profile    │        │   Goals      │              │\n│  │   Use Case   │        │  Industry/   │        │  Workspace   │              │\n│  │  Selection   │        │ Department   │        │   Creation   │              │\n│  └──────┬───────┘        └──────┬───────┘        └──────┬───────┘              │\n│         │                       │                       │                      │\n│         │ personal/work/business│ industry + department │ goal + workspace    │\n│         │                       │ + company size        │ name + type          │\n│         │                       │                       │                      │\n│         └───────────────────────┴───────────────────────┘                      │\n│                                   │                                          │\n│                                   ▼                                          │\n│                          ┌──────────────┐                                    │\n│                          │   Step 4     │                                    │\n│                          │  Complete    │                                    │\n│                          │  Success +   │                                    │\n│                          │  Redirect    │                                    │\n│                          └──────┬───────┘                                    │\n│                                 │                                          │\n│         ┌───────────────────────┴───────────────────────┐                    │\n│         │                                               │                    │\n│         ▼                                               ▼                    │\n│  ┌──────────────┐                                ┌──────────────┐              │\n│  │  Workbench   │                                │  Marketplace  │              │\n│  │  /app        │                                │  Connector   │              │\n│  └──────────────┘                                │  Activation  │              │\n│                                                 └──────────────┘              │\n│                                                                             │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## Detailed Step-by-Step Flow\n\n### Step 1: Welcome (Use Case Selection)\n\n**Route:** `/onboarding`  \n**Component:** `WelcomeStep.tsx`\n\n**User Selection:**\n\n- **Personal** - Organize personal work\n- **Work** - Professional workflow\n- **Business** - Company data & workflows\n\n**Data Collected:**\n\n```typescript\n{\n  useCase: \"personal\" | \"work\" | \"business\";\n}\n```\n\n**Backend Action:**\n\n- Calls `updateOnboardingState({ currentStep: \"workspace\", completedSteps: [\"welcome\"] })`\n- Stores preference in backend session\n\n**Domain Resolution:**\n\n```typescript\npersonal → PERSONAL domain\nwork → Maps department to domain (SALES, MARKETING, REVOPS, etc.)\nbusiness → Maps department to domain (SALES, MARKETING, REVOPS, etc.)\n```\n\n---\n\n### Step 2: Profile (Industry & Department)\n\n**Route:** `/onboarding/profile`  \n**Component:** `ProfileStep.tsx`\n\n**User Selection:**\n\n**Industry Options (12):**\n\n- Technology / SaaS\n- Professional Services\n- Healthcare\n- Education\n- Manufacturing\n- Automotive / Mobility\n- Retail / E-commerce\n- Financial Services\n- Logistics / Supply Chain\n- Media / Entertainment\n- Government / Public Sector\n- Other\n\n**Department Groups (4 categories):**\n\n- **Revenue & Growth:** Sales, Marketing, RevOps, Customer Success\n- **Technology:** Engineering, Product Management, IT/Technology\n- **Operations:** Operations, Supply Chain, Service Operations, Project Management\n- **Corporate:** Finance/Accounting, Legal, Human Resources\n\n**Company Size:**\n\n- Just me, 2-10, 11-50, 51-200, 201-500, 500+\n\n**Data Collected:**\n\n```typescript\n{\n  industry: string,\n  department: string,\n  companySize: string\n}\n```\n\n**Spine Schema Init:**\n\n- When industry + department selected, triggers `handleSpineInit`\n- Calls `updateOnboardingState({ currentStep: \"configuration\" })`\n- Configures adaptive Spine schema for domain\n\n**Domain Mapping:**\n\n```typescript\nSALES → SALES domain\nMARKETING → MARKETING domain\nCUSTOMER_SUCCESS → CUSTOMER_SUCCESS domain\nENGINEERING → PRODUCT_ENGINEERING domain\nFINANCE → FINANCE domain\nOPERATIONS → CUSTOMER_SUCCESS domain\n// ... (full mapping in OnboardingShell.tsx)\n```\n\n---\n\n### Step 3: Goals & Workspace\n\n**Route:** `/onboarding/workspace`  \n**Component:** `GoalsStep.tsx`\n\n**User Selection:**\n\n**Primary Goals (5):**\n\n- **Organize knowledge** - Database icon\n- **Get insights** - Sparkles icon\n- **Track context** - Target icon\n- **Improve team** - Users icon\n- **Automate work** - Zap icon\n\n**Workspace Types (4):**\n\n- Company\n- Department\n- Client\n- Project\n\n**Workspace Name:** Free text input (default: \"Acme Corp\")\n\n**Data Collected:**\n\n```typescript\n{\n  goal: string,\n  workspaceName: string,\n  workspaceType: string\n}\n```\n\n**Backend Actions:**\n\n1. **Update Onboarding State:**\n\n```typescript\nawait updateOnboardingState({\n  currentStep: \"activation\",\n  completedSteps: [\"workspace\", \"configuration\", \"connectors\"],\n  preferences: { useCase, industry, department, companySize, goal, workspaceName, workspaceType },\n});\n```\n\n2. **Initialize Spine:**\n\n```typescript\nawait initializeSpine({\n  domain: resolvedDomain,\n  industry: data.industry,\n  department: data.department,\n  connectors: [],\n});\n```\n\n3. **Update User Profile:**\n\n```typescript\nawait updateUser({\n  onboarding_complete: true,\n  domain: resolvedDomain,\n  department: data.department,\n  useCase: data.useCase,\n  userName: workspaceName,\n});\n```\n\n4. **Complete Onboarding:**\n\n```typescript\nawait completeOnboarding({\n  preferences: {\n    /* all onboarding data */\n  },\n});\n```\n\n5. **Create Free Subscription:**\n\n```typescript\nawait apiFetch(\"/api/v1/subscriptions\", {\n  method: \"POST\",\n  body: { tenantId, planId: \"free\" },\n});\n```\n\n---\n\n### Step 4: Completion\n\n**Route:** `/onboarding/complete`  \n**Component:** `CompletionScreen`\n\n**Behavior:**\n\n- Shows success message with checkmark\n- Auto-redirects to workbench after 3 seconds\n- Two manual options:\n  - **Browse Marketplace** - Go to connector marketplace\n  - **Go to Workbench Now** - Immediate redirect\n\n**Marketplace Intent Handling:**\n\n- If user came from marketplace connector activation\n- Shows \"Connect [Connector Name]\" button\n- Redirects to `/marketplace?activate=[connector-id]`\n\n**Auto-redirect:**\n\n```typescript\nsetTimeout(() => {\n  navigate(\"/app\", { replace: true });\n}, 2000);\n```\n\n---\n\n## Backend Onboarding Service\n\n### Gateway Onboarding (`services/gateway/src/onboarding.ts`)\n\n**Key Functions:**\n\n#### `getOrCreateUser`\n\n```typescript\n// Called after OAuth callback\n// - Checks if user exists in tenant\n// - Creates new user if needed\n// - Returns OnboardingContext with isNewUser flag\n```\n\n#### `getAvailableRoles`\n\n```typescript\n// Returns 10 predefined roles:\n// - sales_rep, sales_manager\n// - cs_manager, cs_specialist\n// - finance_manager, support_lead\n// - engineering_lead, marketing_manager\n// - ops_manager, ceo\n// Each with: suggestedConnectors, defaultDomain, defaultView\n```\n\n#### `getAvailableConnectors`\n\n```typescript\n// Returns 15+ connectors filtered by subscription tier:\n// - CRM: Salesforce, Freshsales, HubSpot\n// - Enrichment: Apollo\n// - Accounting: Stripe, Razorpay, QuickBooks\n// - Communications: Zendesk, Intercom, Gmail, Slack, Zoom\n// - Analytics: GitHub, Jira, Google Analytics\n// Tiers: free, starter, pro, enterprise\n```\n\n#### `completeOnboarding`\n\n```typescript\n// Finalizes onboarding:\n// - Updates user role in users table\n// - Stores connector selections in tenant_spine_config\n// - Logs onboarding event in audit_log\n// - Marks onboarding_completed_at timestamp\n```\n\n---\n\n## Workspace API Endpoints\n\n### `/api/v1/workspace/initialize-spine`\n\n**Method:** POST  \n**Purpose:** Initialize Spine schema for tenant\n\n**Request:**\n\n```typescript\n{\n  domain: \"CUSTOMER_SUCCESS\" | \"SALES\" | \"REVOPS\" | ...,\n  industry?: string,\n  department?: string,\n  connectors: Array<{\n    provider: string,\n    flowType: \"A\" | \"B\" | \"C\"\n  }>\n}\n```\n\n**Response:**\n\n```typescript\n{\n  tenantConfig: {\n    id: string,\n    domain: string,\n    connectors: Record<string, any>\n  },\n  syncJobs: Array<{\n    jobId: string,\n    connector: string,\n    status: string\n  }>\n}\n```\n\n---\n\n### `/api/v1/workspace/onboarding-state`\n\n**Methods:** GET, PATCH  \n**Purpose:** Manage onboarding session state\n\n**GET Response:**\n\n```typescript\n{\n  onboarding: {\n    status: \"not_started\" | \"in_progress\" | \"completed\",\n    currentStep: string,\n    completedSteps: string[],\n    connectorsConfig?: Array<{...}>,\n    creamyJobId?: string,\n    normalizerJobId?: string,\n    preferences?: Record<string, unknown>,\n    entry?: { source: \"direct\" | \"marketplace\" | \"mcp\" }\n  }\n}\n```\n\n**PATCH Request:**\n\n```typescript\n{\n  currentStep?: \"welcome\" | \"workspace\" | \"configuration\" | \"connectors\" | \"activation\" | \"complete\",\n  completedSteps?: string[],\n  preferences?: Record<string, unknown>\n}\n```\n\n---\n\n### `/api/v1/workspace/complete-onboarding`\n\n**Method:** POST  \n**Purpose:** Finalize onboarding and trigger background jobs\n\n**Request:**\n\n```typescript\n{\n  preferences?: Record<string, any>\n}\n```\n\n**Response:**\n\n```typescript\n{\n  success: boolean,\n  redirectUrl: string,\n  backgroundJobs: Array<{\n    jobId: string,\n    type: string,\n    status: string\n  }>\n}\n```\n\n---\n\n### `/api/v1/workspace/progress`\n\n**Method:** GET  \n**Purpose:** Poll sync job progress during onboarding\n\n**Response:**\n\n```typescript\n{\n  type: \"sync_progress\",\n  jobs: Array<{\n    jobId: string,\n    connector: string,\n    phase: \"creamy\" | \"needed\" | \"delta\",\n    status: \"pending\" | \"running\" | \"completed\" | \"failed\",\n    progress: {\n      total?: number,\n      processed?: number,\n      percentage?: number,\n      stage?: string\n    }\n  }>\n}\n```\n\n---\n\n## Onboarding Intent System\n\n**Purpose:** Carry entry point through hosted authentication without putting connector identity in OAuth URL\n\n**File:** `apps/web/src/lib/onboarding-intent.ts`\n\n**Intent Types:**\n\n```typescript\ntype OnboardingIntent =\n  | { version: 1; source: \"direct\" }\n  | {\n      version: 1;\n      source: \"marketplace\";\n      connector: { id: string; name: string; authType: \"oauth\" | \"api_key\" };\n    };\n```\n\n**Functions:**\n\n- `getOnboardingIntent()` - Read from sessionStorage\n- `ensureDirectOnboardingIntent()` - Set direct intent if none exists\n- `setMarketplaceConnectorIntent()` - Set marketplace connector intent\n- `clearOnboardingIntent()` - Clear after onboarding complete\n\n**Storage:** SessionStorage (navigation convenience, not source of truth)\n\n---\n\n## Domain Resolution Logic\n\n**File:** `apps/web/src/OnboardingShell.tsx`\n\n**Mapping Function:**\n\n```typescript\nfunction resolveDomain(useCase: string, department: string): string;\n```\n\n**Domain Mappings:**\n\n| Use Case | Department             | Domain              |\n| -------- | ---------------------- | ------------------- |\n| personal | any                    | PERSONAL            |\n| work     | SALES                  | SALES               |\n| work     | MARKETING              | MARKETING           |\n| work     | REVOPS                 | REVOPS              |\n| work     | CUSTOMER_SUCCESS       | CUSTOMER_SUCCESS    |\n| work     | ENGINEERING/PRODUCT/IT | PRODUCT_ENGINEERING |\n| work     | OPERATIONS             | CUSTOMER_SUCCESS    |\n| work     | SUPPLY_CHAIN           | PROCUREMENT         |\n| work     | SERVICE_OPS            | SERVICE             |\n| work     | PROJECT_MANAGEMENT     | CUSTOMER_SUCCESS    |\n| work     | FINANCE                | FINANCE             |\n| work     | LEGAL/HR               | CUSTOMER_SUCCESS    |\n| business | (same as work)         | (same as work)      |\n\n**Fallback:** If no match, defaults to CUSTOMER_SUCCESS (business) or PERSONAL (personal)\n\n---\n\n## Draft Persistence\n\n**Storage Key:** `iw_onboarding_draft_{userId}`  \n**Storage:** SessionStorage\n\n**Persisted Data:**\n\n```typescript\n{\n  version: 1,\n  currentPath: string,\n  data: {\n    useCase?: string,\n    industry?: string,\n    department?: string,\n    companySize?: string,\n    goal?: string,\n    workspaceName?: string,\n    workspaceType?: string\n  },\n  updatedAt: number\n}\n```\n\n**Behavior:**\n\n- Auto-saves on each step completion\n- Restores on page reload\n- Cleared after successful onboarding completion\n\n---\n\n## Step Indicator\n\n**Visual Progress:** 4 dots with connecting lines\n\n```\n●──●──●──●\nStep 1 of 4\n```\n\n**Steps:**\n\n1. Welcome (`/onboarding`)\n2. Profile (`/onboarding/profile`)\n3. Workspace (`/onboarding/workspace`)\n4. Done (`/onboarding/complete`)\n\n**Current Step Highlighting:** Primary color for completed and current steps\n\n---\n\n## Animation & Transitions\n\n**Library:** Framer Motion\n\n**Transitions:**\n\n- Fade in/out between steps\n- Slide up/down for step changes\n- Scale effects on button interactions\n- Pulse animation for spine initialization indicator\n\n**Loading States:**\n\n- Spinner during async operations\n- Disabled button states during submission\n- Progress indicators for background jobs\n\n---\n\n## Error Handling\n\n**Frontend:**\n\n- Try-catch around all async operations\n- Console error logging with context\n- Graceful degradation (continue on failure)\n- User-friendly error messages\n\n**Backend:**\n\n- Database transaction rollback on failure\n- Audit logging for all onboarding events\n- Idempotency for retry scenarios\n- Tenant isolation enforcement\n\n---\n\n## Post-Onboarding Flow\n\n**Immediate Actions:**\n\n1. Clear sessionStorage draft\n2. Clear onboarding intent\n3. Redirect to workbench or marketplace\n\n**Workbench Entry:**\n\n- User sees role-specific modules\n- Spine projection based on domain\n- Empty state with \"Get Started\" prompts\n- Suggested connectors based on role\n\n**Marketplace Entry (if connector intent):**\n\n- Pre-selected connector from intent\n- OAuth flow initiation\n- Connector activation wizard\n\n---\n\n## Subscription Creation\n\n**Default Plan:** Free tier\n\n**API Call:**\n\n```typescript\nPOST /api/v1/subscriptions\n{\n  tenantId: string,\n  planId: \"free\"\n}\n```\n\n**Behavior:**\n\n- Best-effort (failure doesn't block onboarding)\n- Console error logging\n- Can be completed later in settings\n\n---\n\n## Architecture Compliance\n\n**Frozen Architecture Alignment:**\n\n✅ **Product = Three Concepts Only**\n\n- Onboarding (initial setup)\n- User Workbench (role-specific projection)\n- Silent Twin (contextual assistance)\n\n✅ **Spine is SSOT**\n\n- Onboarding configures Spine schema\n- Spine owns all operational truth\n- Memory informs truth, not vice versa\n\n✅ **Governance is Hard Gate**\n\n- No connector activation without approval\n- OAuth flows properly gated\n- Tenant isolation enforced\n\n✅ **Workbench is One Surface**\n\n- No L1/L2/L4/L7 in onboarding UI\n- Single progressive flow\n- Role projection configured, not layered\n\n✅ **Twin is Silent by Default**\n\n- Twin not involved in onboarding\n- No AI assistance during setup\n- User-driven configuration only\n\n---\n\n## Key Files Reference\n\n| File                                                                  | Purpose                                                                        |\n| --------------------------------------------------------------------- | ------------------------------------------------------------------------------ |\n| `apps/web/src/OnboardingShell.tsx`                                    | Main onboarding shell with 4-step flow                                         |\n| `apps/web/src/components/activation/onboarding/steps/WelcomeStep.tsx` | Step 1: Use case selection                                                     |\n| `apps/web/src/components/activation/onboarding/steps/ProfileStep.tsx` | Step 2: Industry/department selection                                          |\n| `apps/web/src/components/activation/onboarding/steps/GoalsStep.tsx`   | Step 3: Goals and workspace creation                                           |\n| `apps/web/src/api/workspace.ts`                                       | Workspace API client (initialize-spine, onboarding-state, complete-onboarding) |\n| `apps/web/src/lib/onboarding-intent.ts`                               | Onboarding intent management (direct vs marketplace)                           |\n| `services/gateway/src/onboarding.ts`                                  | Backend onboarding service (roles, connectors, user creation)                  |\n| `services/gateway/src/index.ts`                                       | Gateway routing for onboarding endpoints                                       |\n\n---\n\n## Summary\n\nThe IntegrateWise onboarding flow is a **4-step progressive wizard** that:\n\n1. **Captures user intent** (personal/work/business use case)\n2. **Configures the Spine** (industry + department → domain resolution)\n3. **Creates the workspace** (goals + workspace name + type)\n4. **Initializes Spine schema** and redirects to workbench or marketplace\n\nThe flow is **entry-point agnostic** - works equally well for direct sign-up and marketplace connector activation. It uses **session storage for draft persistence**, **backend session for state management**, and **Clerk OAuth for authentication**.\n\nKey architectural principles maintained:\n\n- Single Workbench surface (no layer complexity)\n- Spine as single source of truth\n- Role-based domain projection\n- Governance gates for connector activation\n- Silent Twin (no AI during onboarding)\n"}