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

File	Content
`app/onboarding/page.tsx`	4-step wizard
`app/onboarding/components/StepOrg.tsx`	Company info form
`app/onboarding/components/StepProduct.tsx`	Product description
`app/onboarding/components/StepCountry.tsx`	Country selection (flag icons)
`app/onboarding/components/StepDiscovery.tsx`	Auto discovery + result display
`app/onboarding/hooks/useOnboarding.ts`	Wizard state management
`components/OnboardingBanner.tsx`	”Next steps” banner (dismissible)

Files to Change

File	Change
`middleware.ts`	Onboarding redirect check
`app/api/discover/route.ts`	`isOnboarding` flag → skip writing to usage_monthly
`app/companies/page.tsx`	OnboardingBanner 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

#	Task	Ring	Size
ONBOARD-1	`app/onboarding/page.tsx` — wizard container + routing	R1	Medium
ONBOARD-2	`StepOrg.tsx` — company name + industry form	R1	Small
ONBOARD-3	`StepProduct.tsx` — product description + examples	R1	Small
ONBOARD-4	`StepCountry.tsx` — country selection (popular countries + search)	R1	Small
ONBOARD-5	`StepDiscovery.tsx` — auto discovery + Top 5 display	R1	Medium
ONBOARD-6	`useOnboarding.ts` — wizard state + org settings update	R1	Medium
ONBOARD-7	`middleware.ts` — onboarding redirect	R1	Small
ONBOARD-8	`isOnboarding` flag in discovery route (skip writing to usage)	R1	Small
ONBOARD-9	`OnboardingBanner.tsx` — next steps (dismissible)	R1	Small

Documentation Index

​08 — Onboarding & Activation

​Problem

​Decisions

​D1: Onboarding Flow (4 Steps)

​D2: Onboarding Discovery = FREE

​D3: Onboarding Completion Check

​D4: Post-Onboarding Guidance

​Data Model

​Architecture

​Page Structure

​Middleware Integration

​Current Code Impact

​New Files

​Files to Change

​Future Decisions

​FD-1: Product Portfolio (Ring 2)

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

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

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

​Atomic Tasks

08 — Onboarding & Activation

Problem

Decisions

D1: Onboarding Flow (4 Steps)

D2: Onboarding Discovery = FREE

D3: Onboarding Completion Check

D4: Post-Onboarding Guidance

Data Model

Architecture

Page Structure

Middleware Integration

Current Code Impact

New Files

Files to Change

Future Decisions

FD-1: Product Portfolio (Ring 2)

FD-2: Smart Country Suggestion (Ring 3)

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

FD-4: Re-Onboarding (Ring 2)

Atomic Tasks