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

> Master Meetily's onboarding flow for seamless AI provider setup. Automate configuration, download models, and secure permissions with this four-step React process.

- Repository: [Zackriya Solutions/meetily](https://github.com/Zackriya-Solutions/meetily)
- Tags: how-to-guide
- Published: 2026-07-13

---

**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`](https://github.com/Zackriya-Solutions/meetily/blob/main/frontend/src/components/onboarding/OnboardingFlow.tsx) renders a step-based wizard controlled by the `useOnboarding` hook from [`frontend/src/contexts/OnboardingContext.tsx`](https://github.com/Zackriya-Solutions/meetily/blob/main/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`](https://github.com/Zackriya-Solutions/meetily/blob/main/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`](https://github.com/Zackriya-Solutions/meetily/blob/main/frontend/src/constants/modelDefaults.ts) for platform-specific mappings and calls `setRecommendedModels()` from [`frontend/src/services/configService.ts`](https://github.com/Zackriya-Solutions/meetily/blob/main/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`](https://github.com/Zackriya-Solutions/meetily/blob/main/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`](https://github.com/Zackriya-Solutions/meetily/blob/main/configService.ts) module exposes methods to set custom models before advancing the step counter.

```tsx
// 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`](https://github.com/Zackriya-Solutions/meetily/blob/main/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`](https://github.com/Zackriya-Solutions/meetily/blob/main/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`](https://github.com/Zackriya-Solutions/meetily/blob/main/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`](https://github.com/Zackriya-Solutions/meetily/blob/main/configService.ts), users can later modify their transcription and summarization models by calling `setRecommendedModels()` from [`frontend/src/services/configService.ts`](https://github.com/Zackriya-Solutions/meetily/blob/main/frontend/src/services/configService.ts) with new model identifiers, though this requires implementing a custom settings interface outside the standard onboarding flow.