Skip to main content

​
08 — Onboarding & Activation

Ring: 1 (Launch Blocker) Dependency: R1-1 (Auth), R1-4 (Billing — needed to show plan limits) Handbook: Ch. 6 (WOW moment), Ch. 10 (activation metric), Ch. 98 (discovery in first session)

​
Problem

  • Empty page after signup — user doesn’t know what to do.
  • “WOW moment” is not guaranteed — user can get lost without knowing the product/country.
  • First experience is critical: in B2B SaaS, the first 5 minutes either win or lose the user.
  • Handbook: “These are the 5 companies most likely to buy your product” — this moment MUST be created.

​
Decisions

​
D1: Onboarding Flow (4 Steps)

SIGNUP
  → Email/password or Google/Apple OAuth
  → Account is created

STEP 1: CREATE ORG
  ┌────────────────────────────────────────────┐
  │  Tell Us About Your Company                │
  │                                            │
  │  Company name: [Dose Kimya            ]    │
  │  Industry:     [Chemical products     ▼]   │
  │                                            │
  │                        [Continue →]        │
  └────────────────────────────────────────────┘

STEP 2: WHAT DO YOU EXPORT?
  ┌────────────────────────────────────────────┐
  │  Describe Your Products                    │
  │                                            │
  │  Product description:                      │
  │  [textile stain remover spray         ]    │
  │                                            │
  │  Tip: The more detail you provide,         │
  │  the more accurate results will be.        │
  │                                            │
  │  Example: "industrial textile cleaning     │
  │  chemicals for denim washing"              │
  │                                            │
  │             [← Back]   [Continue →]        │
  └────────────────────────────────────────────┘

STEP 3: TARGET MARKET
  ┌────────────────────────────────────────────┐
  │  Where Do You Want to Sell?                │
  │                                            │
  │  [🇩🇪 Germany    ] [🇮🇹 Italy       ]     │
  │  [🇬🇧 UK         ] [🇫🇷 France      ]     │
  │  [🇵🇱 Poland     ] [🇪🇸 Spain       ]     │
  │  [+ Add another country...]                │
  │                                            │
  │  Pick a country — we'll start your         │
  │  first discovery!                          │
  │                                            │
  │             [← Back]   [Discover! →]       │
  └────────────────────────────────────────────┘

STEP 4: FIRST DISCOVERY (runs automatically)
  ┌────────────────────────────────────────────┐
  │  🔍 Finding the best-fit companies         │
  │     for you...                             │
  │                                            │
  │  ████████████░░░░░░ Finding companies...   │
  │                                            │
  │  ✅ 25 companies found!                    │
  │                                            │
  │  ⭐ Top 5 — Best Fit Candidates:          │
  │  1. TextilChem GmbH (FitScore: 92) 🔥     │
  │  2. ChemTrade AG (FitScore: 88) 🔥        │
  │  3. Mueller Textil KG (FitScore: 85) 🔥   │
  │  4. Deutsche Farben GmbH (FitScore: 81)🔥  │
  │  5. Import Chemie AG (FitScore: 78)        │
  │                                            │
  │  [View Results →]                          │
  └────────────────────────────────────────────┘

​
D2: Onboarding Discovery = FREE

The first discovery during onboarding:
  → Does NOT affect plan limits (bonus)
  → NOT written to usage_monthly table
  → Written to ai_job_runs (for cost tracking)
  → Written to activity_log: action = 'onboarding.discovery'
  → Results are the same as a normal discovery (saved to DB, FitScore calculated)

Why free:
  → This is our advertisement
  → Friction must be zero to guarantee the WOW moment
  → A "you used 1 of your 3 quotas" message kills the WOW moment
  → Starting limits after the user sees value is more fair

​
D3: Onboarding Completion Check

export_ai_organizations.settings JSONB:
  {
    "onboarding_completed": false,
    "onboarding_step": 2,           // step where they left off
    "onboarding_product": "...",     // entered product
    "onboarding_country": "DE"       // selected country
  }

→ On login if onboarding_completed = false → redirect to /onboarding
→ On completion → redirect to /discovery page (Ring 2: /dashboard)
→ No skip option — at least 1 discovery must be performed

​
D4: Post-Onboarding Guidance

After first discovery is complete (on the companies page):

  ┌─── Next Steps (dismissible banner) ────────────────┐
  │                                                     │
  │  ✅ You completed your first discovery!             │
  │                                                     │
  │  Now:                                               │
  │  → Click a company to view its details              │
  │  → Use "Find Contacts" to discover decision makers  │
  │  → "Save as Lead" to add to your tracking list      │
  │                                                     │
  │  [Got it, close]                                    │
  └─────────────────────────────────────────────────────┘

​
Data Model

No additional table needed. Structures used:
  • export_ai_organizations.settings → onboarding state (JSONB)
  • export_ai_activity_log → onboarding.started, onboarding.completed, onboarding.discovery
  • export_ai_ai_job_runs → onboarding discovery cost tracking (endpoint: 'onboarding')
  • export_ai_products → User’s entered product info (optional — future product portfolio)

​
Architecture

​
Page Structure

app/onboarding/
  ├── page.tsx              → Wizard container (4 steps)
  ├── components/
  │   ├── StepOrg.tsx       → Step 1: company name + industry
  │   ├── StepProduct.tsx   → Step 2: product description
  │   ├── StepCountry.tsx   → Step 3: country selection
  │   └── StepDiscovery.tsx → Step 4: discovery + results
  └── hooks/
      └── useOnboarding.ts  → Wizard state + API calls

​
Middleware Integration

// Added to middleware.ts:
// If auth exists + onboarding_completed = false → redirect to /onboarding
// Exceptions: /api/*, /onboarding/*, /logout

​
Current Code Impact

​
New Files

FileContent
app/onboarding/page.tsx4-step wizard
app/onboarding/components/StepOrg.tsxCompany info form
app/onboarding/components/StepProduct.tsxProduct description
app/onboarding/components/StepCountry.tsxCountry selection (flag icons)
app/onboarding/components/StepDiscovery.tsxAuto discovery + result display
app/onboarding/hooks/useOnboarding.tsWizard state management
components/OnboardingBanner.tsx”Next steps” banner (dismissible)

​
Files to Change

FileChange
middleware.tsOnboarding redirect check
app/api/discover/route.tsisOnboarding flag → skip writing to usage_monthly
app/companies/page.tsxOnboardingBanner display (for first time)

​
Future Decisions

​
FD-1: Product Portfolio (Ring 2)

The product entered during onboarding can be saved to the export_ai_products table. Users can define multiple products. Each product can have its own discovery.

​
FD-2: Smart Country Suggestion (Ring 3)

Based on Market Context data: “Best markets for this product: Germany (0.91), Italy (0.84)…” User accepts suggestion instead of choosing a country.

​
FD-3: Onboarding A/B Test (Ring 3+)

Test different onboarding flows with PostHog. Does 3 steps or 4 steps work better? Do product examples improve conversion?

​
FD-4: Re-Onboarding (Ring 2)

“Welcome back” flow for users who haven’t used the product in a while. Resume from where they left off.

​
Atomic Tasks

#TaskRingSize
ONBOARD-1app/onboarding/page.tsx — wizard container + routingR1Medium
ONBOARD-2StepOrg.tsx — company name + industry formR1Small
ONBOARD-3StepProduct.tsx — product description + examplesR1Small
ONBOARD-4StepCountry.tsx — country selection (popular countries + search)R1Small
ONBOARD-5StepDiscovery.tsx — auto discovery + Top 5 displayR1Medium
ONBOARD-6useOnboarding.ts — wizard state + org settings updateR1Medium
ONBOARD-7middleware.ts — onboarding redirectR1Small
ONBOARD-8isOnboarding flag in discovery route (skip writing to usage)R1Small
ONBOARD-9OnboardingBanner.tsx — next steps (dismissible)R1Small