> ## Documentation Index
> Fetch the complete documentation index at: https://docs.highailabs.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Onboarding Flow
> The complete first-time user experience — from app download through authentication to first value moment, with every screen, decision point, and edge case.
## Overview
The onboarding flow is the most critical user journey in High IQ. It determines whether a new user becomes an active user or abandons the app. The goal is simple: get the user to their first **"aha" moment** — seeing their cannabis data organized, analyzed, and actionable — as fast as possible.
## Onboarding Funnel
```mermaid theme={null}
graph TD
A[App Store Download] --> B[First Launch]
B --> C[Preview Dashboard]
C --> D{User Intent}
D -->|Explore First| E[Browse Preview]
E --> E1[View Locked Features]
E1 --> E2[Tap Locked Card]
E2 --> F[Auth Prompt]
D -->|Sign Up Now| F
F --> G{Auth Method}
G -->|Apple| H[Apple Sign-In]
G -->|Google| I[Google OAuth]
G -->|Email| J[Email + Password]
H --> K[Account Created]
I --> K
J --> K
K --> L[Personalized Dashboard]
L --> M{First Action Path}
M -->|Quick Win| N[Add Strain Manually]
M -->|Medium Effort| O[Upload Receipt Photo]
M -->|High Effort + High Reward| P[Gmail Import]
M -->|Explore| Q[Browse Strain Database]
M -->|Scan| R[Label Scanner]
N --> S[First Value Moment]
O --> S
P --> S
Q --> Q1[Favorite a Strain]
Q1 --> S
R --> R1[View Terpene Results]
R1 --> S
S --> T[Activated User]
style S fill:#22c55e,color:#fff
style T fill:#22c55e,color:#fff
```
## Authentication Flow
```mermaid theme={null}
sequenceDiagram
participant U as User
participant App as High IQ
participant Clerk as Clerk Auth
participant Convex as Convex DB
U->>App: Tap Sign Up
App->>U: Show auth options (Apple, Google, Email)
alt Apple Sign-In
U->>Clerk: Apple authentication
Clerk-->>App: Token + user info
Note over U,Clerk: Name may be hidden by Apple
else Google OAuth
U->>Clerk: Google authentication
Clerk-->>App: Token + user info + email
Note over U,Clerk: Gmail access can be added later
else Email
U->>App: Enter email + password
App->>Clerk: Create account
Clerk-->>App: Verification email sent
U->>Clerk: Verify email
Clerk-->>App: Account verified
end
App->>Convex: Create user record
Convex-->>App: User created
App->>U: Show personalized dashboard
```
### Authentication Edge Cases
| Edge Case | Behavior |
| --------------------------------- | ------------------------------------------------ |
| User already has account (Google) | Silently signs in, redirects to dashboard |
| User already has account (email) | "Account exists" message with sign-in option |
| Apple hides email | Account created with relay email, works normally |
| Network failure during auth | Error toast with retry button, no partial state |
| Force quit during auth | Resumes at auth screen on next launch |
| OAuth popup blocked | Fallback instructions displayed |
| Email verification timeout | Resend button after 60 seconds |
## First Action Paths
This page summarizes several activation choices. For the source-of-truth implementation status and recovery paths for text entry, Gmail import, shops, and unknown-strain research, see [Order Activation: Import, Review, and Research](/help/user-flows/order-upload).
### Path A: Manual Strain Entry (Fastest — 30 seconds)
```mermaid theme={null}
graph TD
A[Tap + on Stash] --> B[Strain Search Modal]
B --> C[Type Strain Name]
C --> D[Search Results Appear]
D --> E[Tap Strain to Select]
E --> F[Configure Details]
F --> F1[Set Quantity]
F --> F2[Set Product Type]
F --> F3[Set Dispensary]
F --> F4[Add Notes]
F1 --> G[Tap Save]
F2 --> G
F3 --> G
F4 --> G
G --> H[Strain in Stash]
H --> I[Dashboard Updates]
style H fill:#22c55e,color:#fff
```
**Edge cases:**
| Scenario | Handling |
| ---------------------------- | -------------------------------------- |
| Strain not found in database | Option to add custom strain name |
| Duplicate strain in stash | Warning with option to update existing |
| No quantity entered | Saves with "unknown" quantity |
| Network offline | Queued locally, syncs when online |
### Path B: Receipt Photo Upload (2 minutes)
```mermaid theme={null}
graph TD
A[Tap Upload Receipt] --> B{Image Source}
B -->|Camera| C[Take Photo]
B -->|Photo Library| D[Select Image]
C --> E[Image Captured]
D --> E
E --> F[AI Processing]
F --> F1[Extracting Text]
F1 --> F2[Identifying Items]
F2 --> F3[Matching Strains]
F3 --> F4[Extracting Prices]
F4 --> G[Review Extracted Data]
G --> G1{All Items Correct?}
G1 -->|Yes| H[Confirm Import]
G1 -->|Edit Needed| I[Edit Items]
I --> I1[Change Strain Name]
I --> I2[Adjust Price]
I --> I3[Remove Item]
I --> I4[Add Missing Item]
I1 --> H
I2 --> H
I3 --> H
I4 --> H
H --> J[Order Created]
J --> K[Items Added to Stash]
K --> L[Dispensary Auto-Created]
style K fill:#22c55e,color:#fff
```
**Edge cases:**
| Scenario | Handling |
| -------------------------------------- | ------------------------------------------ |
| Blurry photo | "Image too blurry" with retake prompt |
| Not a receipt | "This doesn't look like a receipt" message |
| Handwritten receipt | AI attempts extraction, lower confidence |
| Digital screenshot receipt | Works well, high confidence |
| Receipt in non-English | Currently English only, error message |
| Very long receipt (20+ items) | Scrollable review, batch processing |
| Duplicate receipt upload | Duplicate warning with option to proceed |
| Partial extraction (some items missed) | Review screen allows manual additions |
### Path C: Gmail Import (3 minutes, highest value)
```mermaid theme={null}
graph TD
A[Tap Gmail Import] --> B{Gmail Connected?}
B -->|No| C[Connect Google Account]
C --> C1[Google OAuth Consent]
C1 --> C2{Read-only Gmail permission granted?}
C2 -->|Yes| D[Connection Confirmed]
C2 -->|No| E[Keep Gmail disconnected and offer text entry]
B -->|Yes| D
D --> F[Choose Date Range]
F --> F1[Last 30 Days]
F --> F2[Last 3 Months]
F --> F3[Last 6 Months]
F --> F4[Last 12 Months - Default]
F1 --> G[Start Scan]
F2 --> G
F3 --> G
F4 --> G
G --> H[Durable background discovery job]
H --> H1[Known personal shop domains]
H1 --> H2[Known community domains]
H2 --> H3[Receipt keyword patterns]
H3 --> H4[Server classification and deduplication]
H4 --> I{Results Found?}
I -->|Yes| J[Review candidate senders]
I -->|No| K[No Receipts Found]
K --> K1[Offer text entry or shop setup]
J --> L[Review candidate receipts]
L --> L1[Select or deselect each receipt]
L --> L2[Inspect sender, subject, date, and confidence]
L1 --> M[Confirm selected receipts]
L2 --> M
M --> N[Durable background import]
N --> O[Parse, match, and stage orders]
O --> R[Edit dates, shop, totals, line items, and unknown-strain answers]
R --> P[Save or skip each receipt]
P --> Q[View imported orders]
```
**Edge cases:**
| Scenario | Handling |
| ------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Google declines permissions | Clear message explaining read-only scope, retry option |
| No saved shop domain | Create or update a shop inline, or explicitly choose a broad historical scan |
| Zero receipts found | Empty state offers text entry, another range, or improved shop setup |
| Mixed confidence results | Candidate review lets the user exclude false positives before import |
| Import interrupted | Durable scan and import jobs retain resumable progress |
| Duplicate Gmail message IDs | Existing imports are skipped idempotently |
| Non-dispensary emails matched | Server classification plus candidate review reduces false positives |
| Parsed receipt needs correction | Every successful Gmail parse opens the same editable Review & Confirm screen as text input before commit |
| Gmail disconnected during work | The connection generation is invalidated so stale work cannot keep importing |
### Path D: Label Scanner (15 seconds, discovery-oriented)
```mermaid theme={null}
graph TD
A[Open Label Scanner] --> B{Camera Permission?}
B -->|Not Granted| C[Permission Request]
C --> C1{Granted?}
C1 -->|Yes| D[Camera View]
C1 -->|No| E[Photo Library Fallback]
B -->|Already Granted| D
D --> F[Capture Label Image]
E --> F
F --> G{Batch Mode?}
G -->|Single| H[Process Single Image]
G -->|Batch| I[Add More Images - Up to 4]
I --> I1[Label Each Image]
I1 --> J[Process Batch]
H --> K[AI Analysis]
J --> K
K --> L[Results Display]
L --> L1[Strain Name]
L --> L2[THC/CBD %]
L --> L3[Terpene Profile]
L --> L4[High Family Classification]
L --> L5[Confidence Score]
L --> M{Strain in Database?}
M -->|Yes| N[Link to Full Profile]
M -->|No| O[Submit for Research]
N --> P[Add to Stash Option]
O --> P
style L fill:#22c55e,color:#fff
```
## First Value Moment Map
The "aha" moment differs by user type and first action:
```mermaid theme={null}
graph TD
A[First Value Moment] --> B{Path Taken}
B -->|Manual Add| C["My strain is in here with full data!"]
B -->|Receipt Upload| D["It extracted everything from my receipt!"]
B -->|Gmail Import| E["Months of purchases organized instantly!"]
B -->|Label Scan| F["Now I know what High Family this is!"]
B -->|Browse DB| G["This has every strain I've ever heard of"]
C --> H[Dashboard Comes Alive]
D --> H
E --> H
F --> H
G --> G1[Favorite a strain]
G1 --> H
H --> I[User Sees Personalized Content]
I --> I1[Stash Preview Card]
I --> I2[Stats Snapshot]
I --> I3[Achievement Nudge]
I --> I4[Trending Strains]
```
## Post-Onboarding Guidance
After the first value moment, the app surfaces contextual next-step prompts:
| User Has | Next Step Prompt | Where Shown |
| ------------------------- | ------------------------------------------------- | ----------------- |
| 1 strain in stash | "Generate your first AI notebook" | Dashboard card |
| 1 order but no dispensary | "Save your dispensary for menu scanning" | Dashboard card |
| Strains but no favorites | "Heart your favorites for better recommendations" | Strain profile |
| 3+ strains, no rankings | "Start ranking your strains" | Collection screen |
| Data but hasn't asked AI | "Ask Professor High about your stash" | Dashboard tools |
## Related Flows
Where onboarding fits in the complete journey.
Deep dive into all order import methods.
How different personas experience onboarding.
Authentication states and edge cases.