User Onboarding & Getting Started

Guided onboarding experiences across both the web and mobile applications, helping new users acclimate to the Grade My Investments platform.

ONBOARDING FLOW

rendering diagram…

sequenceDiagram
    participant U as New User
    participant AG as Account Guard
    participant DB as Database
    participant W as Web Tour<br/>Shepherd.js
    participant M as Mobile Tour<br/>SfPopup
    U->>AG: Sign in via Google OAuth
    AG->>DB: Check account status
    DB-->>AG: No account found
    AG->>U: Redirect to Create Account
    U->>DB: Submit profile
    DB-->>U: Pending approval
    U->>DB: Admin approves
    DB-->>U: Account active
    U->>W: First web login
    W->>U: Getting Started page
    W->>U: 13-step Shepherd.js tour
    W->>DB: PATCH complete-web-onboarding
    U->>M: First mobile login
    M->>U: 7-slide CarouselView
    M->>U: 11-step SfPopup tour
    M->>DB: PATCH complete-mobile-onboarding

Account-status-gated onboarding flow runs independently on web and mobile, each tracked via its own database flag.

Cross-Platform Guided Onboarding

Grade My Investments provides dedicated onboarding experiences on both web and mobile. Each platform has its own onboarding flow with independent completion tracking, so users get a guided tour tailored to whichever app they use first.

Why Guided Onboarding?

Grade My Investments is a feature-rich platform for financial report generation and analysis. Rather than leaving new users to discover features on their own, both the web and mobile apps provide structured, guided walkthroughs that accelerate time-to-value and reduce support burden.

Faster Time-to-Value

Users generate their first report within minutes of signing up, guided by clear step-by-step instructions.

Reduced Support Load

Proactive guidance answers common questions before they're asked, reducing the need for support tickets.

Higher Engagement

Users who understand the platform's capabilities are more likely to explore advanced features and generate more reports.

Better Retention

A smooth first experience on each platform builds confidence and keeps users coming back.

Web App Onboarding

The web client uses a two-part onboarding system: a Getting Started page with detailed guides and a Shepherd.js guided tour that walks users through the dashboard UI with interactive tooltips.

Getting Started Page

A dedicated page presented after account approval, serving as the user's reference hub for platform usage:

Video Walkthrough: Embedded player for visual learners
4-Step Workflow: Create Symbol List → Generate Report → Review → Decide
Pricing Transparency: Per-symbol and per-GB cost breakdowns with example tiers

Billing Explained: Monthly cycle, automatic payment, usage tracking
Feature Discovery: Symbol lists, file browser, position reports, templates, notification setup
Claude AI: File analysis and Claude Console for interactive Q&A
Quick Links: Direct navigation to all major application areas

Shepherd.js Guided Tour

An interactive tooltip-based walkthrough that highlights dashboard and sidebar elements in sequence:

Step	Target	Description
1	Welcome (centered)	Introduction and tour overview
2	Dashboard header	Your personalized home base
3	Quick Stats cards	Key metrics at a glance
4	Quick Actions	Common task shortcuts
5	Generate Report nav	Report generation entry point
6	My Reports nav	Report management
7	Symbol Lists nav	Watchlist management
8	Position Reports nav	Portfolio holdings tracking
9	Symbol List Templates nav	Pre-built symbol list starting points
10	Report Files nav	File browser
11	Claude AI Analysis nav	AI-powered file analysis and console
12	Billing nav	Usage and billing tracking
13	Getting Started nav	Reference guide reminder

Web Technical Stack

Blazor Server with [Authorize] gate
Shepherd.js v11 (UMD build) for guided tour
Syncfusion SfCard / SfButton components

GuidedTourProvider.razor component on Dashboard
JS Interop bridges Blazor ↔ Shepherd.js
ActivityLogService tracks page views and clicks

Mobile App Onboarding

The .NET MAUI mobile app uses a two-part onboarding system: a CarouselView Getting Started page with 7 swipeable slides and a Syncfusion SfPopup guided tour on the dashboard with tooltips anchored to UI elements.

CarouselView Getting Started

A full-screen swipeable carousel presented on first login, walking users through the platform before they reach the dashboard:

📈

Slide 1: Welcome

App intro, key capabilities, pay-as-you-go model

🚀

Slide 2: How It Works

4-step workflow with numbered indicators

💳

Slide 3: Pricing

Per-symbol and storage cost breakdowns

💼

Slide 4: Track & Organize

Position reports, templates, file management

🤖

Slide 5: Claude AI Analysis

File analysis, Claude Console, AI pricing

📅

Slide 6: Billing & Notifications

Monthly cycle, email and SMS notifications

🎉

Slide 7: You're Ready

CTAs to create symbol list or generate report

IndicatorView dots show current position at the bottom
Back / Next buttons with gold/dark theme matching the app
Skip button at top-right for experienced users
"Get Started" on the final slide navigates to the dashboard

Syncfusion SfPopup Guided Tour

After the carousel, the dashboard launches an interactive popup tour that highlights key UI elements:

Step	Target	Description
1	Welcome (centered)	Introduction and tour overview
2	Welcome header	Your personalized dashboard home base
3	Stats grid	Key metrics — reports, symbol lists, folders, active jobs
4	Generate Report button	Primary action entry point
5	Symbol Lists button	Watchlist management
6	Browse Folders button	Report file browser
7	Position Reports button	Portfolio holdings tracking
8	Symbol List Templates button	Pre-built symbol list starting points
9	Claude AI Analysis button	AI-powered file analysis
10	Billing button	Usage and billing tracking
11	Finish (centered)	Tour complete with Getting Started reminder

ShowRelativeToView: Popups anchor to the target element using PopupRelativePosition.AlignBottom
Blur overlay: Modal overlay with blur effect focuses attention on the highlighted element
Next / Back / Skip: Two-button footer with dynamic labels per step

Mobile Technical Stack

.NET MAUI 10 with Shell navigation
CarouselView with model-driven slides
Syncfusion.Maui.Popup for guided tour overlay

GuidedTourService defines step data
DI-injected into DashboardPage
Dark theme with gold accent (#C4975F)

Shared Onboarding Flow

Both platforms share the same account-status-based routing to ensure users complete all prerequisite steps:

Sign Up

Google OAuth (mobile) or Azure AD (web)

Create Account

Profile creation with auto-redirect if missing

Approval

Admin approval with pending status page

Guided Onboarding

Platform-specific tour and Getting Started guide

Smart Routing: The system automatically checks account status on each page load. Users without an account are redirected to creation; unapproved users see a pending page. Only approved users reach the onboarding flow.

Independent Onboarding Tracking

Web and mobile onboarding completion is tracked independently in the database, so users get the full guided experience on each platform regardless of which they use first.

Web Column

HasCompletedWebOnboarding

Set to false on account creation
Set to true when Shepherd.js tour completes or is skipped
Reset via "Replay Guided Tour" button on web dashboard
API: PATCH /accounts/{id}/complete-web-onboarding
API: PATCH /accounts/{id}/reset-web-onboarding

Mobile Column

HasCompletedMobileOnboarding

Set to false on account creation
Set to true when SfPopup tour completes or is skipped
Reset via "Replay" button on mobile dashboard
API: PATCH /accounts/{id}/complete-mobile-onboarding
API: PATCH /accounts/{id}/reset-mobile-onboarding

Database Schema (MariaDB)

ALTER TABLE `accounts`
  DROP COLUMN `HasCompletedOnboarding`;

ALTER TABLE `accounts`
  ADD COLUMN `HasCompletedWebOnboarding` tinyint(1) NOT NULL DEFAULT 0
  AFTER `StripeCustomerId`;

ALTER TABLE `accounts`
  ADD COLUMN `HasCompletedMobileOnboarding` tinyint(1) NOT NULL DEFAULT 0
  AFTER `HasCompletedWebOnboarding`;

Platform Comparison

Feature	Web (Blazor)	Mobile (MAUI)
Getting Started	Razor page with Syncfusion cards	CarouselView with 7 swipeable slides
Guided Tour	Shepherd.js tooltip overlay	Syncfusion SfPopup with blur overlay
Tour Positioning	`attachTo: { element, on }`	`ShowRelativeToView()`
Tour Steps	13 steps (sidebar nav items)	11 steps (dashboard buttons)
Completion Flag	`HasCompletedWebOnboarding`	`HasCompletedMobileOnboarding`
Replay	"Replay Guided Tour" button	"Replay" button
First Login Routing	Dashboard → auto-start tour	Getting Started carousel → Dashboard → auto-start tour
Theme	Light Bootstrap 5	Dark theme with gold accent

Onboarding Goals

First report within minutes
Understand pricing model
Discover all features
Configure notifications
Set up payment method

Web Components

GettingStarted.razor
GuidedTourProvider.razor
guided-tour.js
shepherd.css (v11)

Mobile Components

GettingStartedPage.xaml
GuidedTourService.cs
Syncfusion.Maui.Popup
CarouselView + IndicatorView

Account Status Guards

No account → Create Account
Not approved → Pending Page
Approved → Onboarding Flow

Automatic redirects on both platforms ensure users complete each prerequisite step before proceeding.

API Endpoints

PATCH complete-web-onboarding
PATCH reset-web-onboarding
PATCH complete-mobile-onboarding
PATCH reset-mobile-onboarding

All endpoints are IDOR-protected via account ownership validation.

Activity Tracking

Page view logging (web)
CTA click tracking (web)
Onboarding completion (both)

Web interactions are logged via ActivityLogService. Both platforms track completion state via the API.