How Meetily's Onboarding Flow Guides Users Through Initial AI Provider Setup

Meetily's onboarding flow is a four-step React application that automates AI provider configuration by recommending platform-specific models, downloading them via Tauri events, and requesting system permissions without requiring manual file hunting.

Meetily is an open-source meeting assistant that relies on local AI transcription and summarization to maintain privacy. The onboarding flow guides users through initial AI provider setup by orchestrating database initialization, model downloads, and macOS permission requests through a stateful React component hierarchy that ensures a working configuration out-of-the-box.

The Four-Step Onboarding Architecture

The OnboardingFlow component in frontend/src/components/onboarding/OnboardingFlow.tsx renders a step-based wizard controlled by the useOnboarding hook from frontend/src/contexts/OnboardingContext.tsx. The flow progresses through four distinct stages that eliminate manual configuration by automatically selecting and downloading the correct AI models.

Step 1: WelcomeStep

Located in frontend/src/components/onboarding/steps/WelcomeStep.tsx, this initial screen introduces Meetily's privacy-first architecture. It explains that all transcription happens locally using the Parakeet model and that no audio data leaves the machine, preparing users for the technical setup ahead.

Step 2: SetupOverviewStep

The SetupOverviewStep component performs two critical functions. First, it bootstraps the local database for first-time users. Second, it recommends AI provider configurations based on platform detection via @tauri-apps/plugin-os and available system RAM.

• macOS: Recommends the Parakeet transcription model and compatible summary models optimized for Apple Silicon or Intel architectures.
• Windows/Linux: Defaults to CPU-compatible models unless GPU acceleration is detected.

This step references frontend/src/constants/modelDefaults.ts for platform-specific mappings and calls setRecommendedModels() from frontend/src/services/configService.ts to persist the selection.

Step 3: DownloadProgressStep

The DownloadProgressStep manages background downloads of the selected Parakeet transcription model and the summary LLM. It communicates with the Tauri backend via events to report real-time progress, keeping the UI responsive during large file transfers. When both downloads complete, the flow automatically advances to the final step.

Step 4: PermissionsStep

Exclusive to macOS, the PermissionsStep requests microphone and screen-recording permissions required for system-audio capture. It uses @tauri-apps/plugin-os for platform detection with a fallback to user-agent checking. Once granted, the onboarding completes and reveals the main meeting interface.

State Management and Persistence

The OnboardingContext.tsx file exports the useOnboarding hook, which tracks the currentStep index in a React context. This state persists across page reloads, allowing users to resume the onboarding flow if they close the application during model downloads. The context provider wraps the entire flow, ensuring step progression survives component unmounting.

Customizing AI Provider Configuration

Advanced users can override the default recommendations programmatically. The configService.ts module exposes methods to set custom models before advancing the step counter.

// Example: Customising the recommended AI models (advanced usage)
import { useOnboarding } from '@/contexts/OnboardingContext';
import { setRecommendedModels } from '@/services/configService';

function CustomSetupOverview() {
  const { setCurrentStep } = useOnboarding();

  // Override defaults before advancing
  const handleContinue = async () => {
    await setRecommendedModels({
      transcription: 'parakeet-large',
      summary: 'gpt‑4o-mini',
    });
    setCurrentStep(3); // Move to DownloadProgressStep
  };

  return (
    <div>
      <h2>Choose your AI models</h2>
      {/* UI for selecting models … */}
      <button onClick={handleContinue}>Continue</button>
    </div>
  );
}

Summary

• Meetily's onboarding flow is implemented as a four-step React component in OnboardingFlow.tsx that guides users through initial AI provider setup automatically.
• The SetupOverviewStep recommends platform-specific models (Parakeet for transcription, configurable LLM for summarization) based on OS and RAM detection.
• DownloadProgressStep handles background model downloads via Tauri events, ensuring the UI remains responsive during multi-gigabyte transfers.
• macOS-specific PermissionsStep requests microphone and screen-recording access required for system audio capture.
• The useOnboarding hook persists progress in context, allowing the flow to resume after application restarts.

Frequently Asked Questions

How does Meetily detect which AI models to recommend during onboarding?

The SetupOverviewStep component uses @tauri-apps/plugin-os to detect the operating system and checks available RAM to select appropriate models from frontend/src/constants/modelDefaults.ts. macOS systems receive Parakeet models optimized for Apple Silicon, while Windows and Linux default to CPU-compatible variants unless GPU acceleration is present.

Can users resume the onboarding flow if they close Meetily during model downloads?

Yes. The useOnboarding hook in frontend/src/contexts/OnboardingContext.tsx persists the currentStep state in a React context that survives page reloads. When the application restarts, the OnboardingFlow component reads this persisted state and resumes at the appropriate step, particularly useful during lengthy model downloads in the DownloadProgressStep.

What happens if a user skips the permissions step on macOS?

The PermissionsStep is mandatory on macOS because Meetily requires microphone and screen-recording permissions to capture system audio for transcription. The flow cannot complete until these permissions are granted, as the OnboardingFlow component specifically checks for macOS platform detection before allowing progression to the main meeting UI.

Is it possible to change the AI models after completing the initial onboarding?

Yes. While the onboarding flow automatically configures the initial AI provider through configService.ts, users can later modify their transcription and summarization models by calling setRecommendedModels() from frontend/src/services/configService.ts with new model identifiers, though this requires implementing a custom settings interface outside the standard onboarding flow.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}