Onboarding Flow
Relevant source files
The following files were used as context for generating this wiki page:
- apps/desktop/src/components/onboarding/OnboardingPage.tsx
- apps/desktop/src/components/onboarding/TutorialForm.tsx
- apps/desktop/src/components/welcome/WelcomePage.tsx
- apps/desktop/src/components/onboarding/UserDetailsForm.tsx
- apps/desktop/src/components/onboarding/ReferralSourceForm.tsx
- apps/desktop/src/components/onboarding/ChooseTranscriptionForm.tsx
- apps/desktop/src/components/onboarding/ChooseLlmForm.tsx
- apps/desktop/src/components/onboarding/PersonalCredentialsForm.tsx
Introduction
The Onboarding Flow in mausVoice is a multi-step guided process designed to configure the application's core transcription and AI capabilities, verify hardware permissions, and introduce users to dictation mechanics. It serves as the bridge between initial installation and active productivity, ensuring that native capabilities like audio capture and keyboard hotkeys are properly authorized and that the user's preferred AI providers (local or cloud-based) are correctly configured.
The flow is managed primarily via a central OnboardingPage component that dynamically renders specific sub-forms based on a currentPage state stored in the application's Zustand store. This process includes data collection for personalization, API key entry for services like Deepgram and Groq, and interactive tutorials that utilize a dictation override to safely practice voice typing within the onboarding environment.
Sources: apps/desktop/src/components/onboarding/OnboardingPage.tsx:1-45, apps/desktop/src/components/onboarding/TutorialForm.tsx:102-127
Architecture and State Management
Centralized Routing
The onboarding process is orchestrated by a state-driven router within the OnboardingPage. It listens to the onboarding.currentPage value from the application store and renders the corresponding form component. The flow also integrates with analytics to track user progression through each step.
The flow begins at the WelcomePage, where users can either "Get started" (resetting and entering onboarding) or log in.
Sources: apps/desktop/src/components/onboarding/OnboardingPage.tsx:24-44, apps/desktop/src/components/welcome/WelcomePage.tsx:16-24
Data Flow and Actions
User inputs across various forms are synchronized with the central store using produceAppState. Navigation between steps is handled by the goToOnboardingPage action, which updates the currentPage state.
| Action | Description | File Reference |
|---|---|---|
goToOnboardingPage | Updates onboarding.currentPage to navigate the user. | onboarding.actions |
submitOnboarding | Persists collected user and configuration data. | onboarding.actions |
finishOnboarding | Marks the onboarding as complete and triggers success UI (confetti). | onboarding.actions |
trackOnboardingStep | Sends analytics events for each page transition. | analytics.utils |
Sources: apps/desktop/src/components/onboarding/OnboardingPage.tsx:20-22, apps/desktop/src/components/onboarding/TutorialForm.tsx:143-152, apps/desktop/src/components/onboarding/UserDetailsForm.tsx:26-30
Core Configuration Steps
AI and Provider Setup
The onboarding process requires users to define their transcription and LLM (Large Language Model) post-processing preferences. Users can choose between "API" mode (requiring keys) or "Local" mode (using sidecar crates like rust_transcription).
Personal Credentials
When configuring cloud providers, users enter API keys for:
- Deepgram: Used for streaming "nova-3" transcription.
- Groq: Used for AI text cleanup and formatting.
These keys are encrypted and stored locally on the machine.
Sources: apps/desktop/src/components/onboarding/PersonalCredentialsForm.tsx:75-125, apps/desktop/src/components/onboarding/ChooseTranscriptionForm.tsx:24-60
User Personalization
The UserDetailsForm and ReferralSourceForm collect metadata to customize the user experience, such as the user's name (used in email templates) and professional title.
Interactive Tutorial
The TutorialForm is the final major stage of onboarding. It provides a two-page interactive environment for users to practice dictation.
Dictation Override Mechanism
During the tutorial, the application enables a "dictation override." This allows the user to trigger the dictation hotkey and see the transcription result land directly into a specific tutorial text field rather than whatever application is globally focused.
Sources: apps/desktop/src/components/onboarding/TutorialForm.tsx:114-116, apps/desktop/src/components/onboarding/TutorialForm.tsx:128-132
Tutorial Steps
- Notes Practice: Uses the
POLISHED_TONE_IDto demonstrate standard text cleanup. - Email Practice: Switches the writing style to
EMAIL_TONE_ID, adding formal greetings and sign-offs automatically based on the name collected inUserDetailsForm.
Conclusion
The onboarding flow is a critical component of mausVoice, transforming a generic tool into a personalized desktop assistant. By combining hardware permission checks, AI provider configuration, and a safe sandbox for dictation practice, it ensures that users are fully equipped to transition from keyboard typing to high-performance voice-to-text workflows.