Documentation Index

Fetch the complete documentation index at: https://grantmaster.dev/llms.txt

Use this file to discover all available pages before exploring further.

Engineering reference: For service contracts, EventBus events, and data-layer details see src/features/onboarding/onboarding.md.

​

last_updated: 2026-02-22

​

Onboarding System

​

Overview

1. Interactive Tour — @onboardjs/react modal overlays that walk users through key UI areas
2. Dashboard Checklist — Persistent UserOnboardingProgress card on the dashboard showing step completion

​

Architecture

┌─────────────────────────────────────────────────────┐
│  OnboardingProvider                                  │
│  3-tier enable check: platform → org → user         │
│  Wraps @onboardjs/react BaseProvider                │
├─────────────────────────────────────────────────────┤
│  onboardingConfig.ts (single source of truth)       │
│  5 role configs × variable step counts              │
├──────────────────────┬──────────────────────────────┤
│  Interactive Tour    │  Dashboard Checklist          │
│  @onboardjs/react    │  UserOnboardingProgress      │
│  tourEnabled steps   │  All steps (persistent)      │
│  Modal overlay       │  Embedded card widget        │
└──────────────────────┴──────────────────────────────┘

​

Role Configurations (5)

Tour vs. Checklist: Steps with tourEnabled: true appear in the interactive modal tour. All steps appear in the dashboard checklist regardless of tourEnabled.

​

Step Structure

interface OnboardingStepConfig {
  id: string;
  title: string;
  description: string;
  whyItMatters: string;
  icon: LucideIcon;
  isRequired: boolean;
  estimatedMinutes: number;
  category: string;
  action?: { label: string; path: string };   // navigation CTA
  tourEnabled: boolean;                        // show in modal tour?
}

​

Example Steps by Role

• Complete organization profile, Configure branding, Set up roles & permissions, Create first project, Configure budgets, Set up compliance rules, Invite team members, Review integrations, Explore AI features

• Complete your profile, Submit first journal entry, Review assigned projects, Upload a document, Explore the dashboard

​

3-Tier Enable Check

​

Dashboard Checklist

• Role-specific header with accent color gradient
• Progress bar (completed / total steps)
• Step list with status indicators (done/pending)
• “Go” buttons linking to relevant pages
• “Required” badges on mandatory steps
• Auto-hides when all steps complete

​

Accent Color Theming

​

Dismiss Behavior

• Users can dismiss the checklist via the X button
• Dismiss state persists in localStorage keyed by user ID
• Checklist auto-hides when all steps are completed
• Super Admins skip the user checklist (they have AdminOnboardingChecklist)

​

Persistence

​

Components

​

Accessor Functions

​

Tenant Provisioning Wizard

1. BasicInfoStep — org name, type
2. LegalEntityStep — legal registration details
3. BrandingStep — logo and colors
4. LocaleTimezoneStep — currency, timezone, language
5. SecurityStep — MFA policy, password rules
6. IntegrationsStep — optional third-party connections
7. TeamInvitationsStep — invite initial team members
8. SubscriptionStep — select plan
9. ReviewLaunchStep — confirm and activate

​

Authentication Flows

​

MFA Setup

​

Firestore Data Model

​

Dependencies

• @onboardjs/react — interactive tour modal engine
• contexts/AuthContext — current user and role
• features/users — user document updates for progress tracking
• features/settings — settings routes referenced in step actions
• features/billing — subscription step in tenant wizard

• App shell — OnboardingProvider wraps the root layout
• AdminOnboardingChecklist is rendered in the admin area

​

Key Files Reference