Voice-to-text dictation app with local (Nvidia Parakeet/Whisper) and cloud models (BYOK). Privacy-first and available cross-platform.
JavaScript aianthropiccross-platformgeminigroqlinuxmacosnvidiaopen-sourceopenaiparakeetspeech-to-texttranscribewhisperwindows
chore: docs cleanup
Gabriel Stein4666f9ded487
diff --git a/plan.md b/plan.mddeleted file mode 100644index 56f26cc67..000000000--- a/plan.md+++ /dev/null@@ -1,927 +0,0 @@-# Cloud Transcription & Usage Paywall--## Overview--Transform OpenWhispr into a "just works" experience for signed-in users. The app sends audio to an OpenWhispr API (Vercel), which handles both transcription and reasoning server-side — no user configuration needed. Free tier: 2000 words/day. Pro subscription via Stripe for unlimited. Power users can switch to BYOK (bring your own key) for unlimited free usage. Local mode unchanged.--The server-side API is **provider-agnostic** — transcription and reasoning are routed through a unified provider interface. Initial providers: Groq (transcription + fast reasoning), OpenRouter (model variety). Future providers (Baseten, Deepgram, OpenAI Whisper, etc.) slot in without API changes.--## Architecture--```-Electron App → IPC (main process) → openwhispr-api (Vercel) → Provider (transcription)- (attaches session cookies) ↕ → Provider (reasoning)- Neon Postgres ↕- ↕ Stripe Webhooks-```--All API calls route through Electron's main process via IPC — same proven pattern as the existing Anthropic handler. This eliminates CORS entirely and keeps auth simple (session cookies forwarded by main process).--**Three transcription modes:**-| Mode | Who | Limit | Transcription | Reasoning |-|------|-----|-------|---------------|-----------|-| OpenWhispr Cloud (default) | Signed-in users | 2000 words/day free, unlimited Pro | Vercel API → provider | Vercel API → provider |-| BYOK | Advanced users with own keys | Unlimited | Direct to provider (existing) | Direct to provider (existing) |-| Local | Privacy users / offline | Unlimited | whisper.cpp / Parakeet | Own keys or local LLM |-------## Step 0: Dead Code Cleanup (Prerequisite PR)--Merge before starting feature work:-- `preload.js:171` — Remove dead `onOAuthCallback` handler-- `src/components/AuthenticationStep.tsx:64` — Remove stale oauth-callback comment-------## Step 1: Create `openwhispr-api` Repo--Location: `~/Projects/OpenWhispr/openwhispr-api/`--```-openwhispr-api/- package.json # @neondatabase/serverless, stripe, openai (provider-compatible), typescript- tsconfig.json- vercel.json # maxDuration: 30s for transcribe, 60s for reason- .env.local # Local dev secrets- lib/- db.ts # Neon serverless Postgres client- auth.ts # Validate Neon Auth session → userId- stripe.ts # Stripe client init- usage.ts # countWords(), checkLimit(), getTodayUsage()- providers.ts # Provider registry — unified interface for transcription + reasoning- api/- transcribe.ts # POST — receive audio, route to provider, return text + usage- reason.ts # POST — receive text, route to provider, return result- usage.ts # GET — current day's word count + limit info- stripe/- checkout.ts # POST — create Stripe Checkout session- portal.ts # POST — create Stripe Customer Portal session- webhook.ts # POST — handle Stripe events- checkout/- success.ts # GET — static "Payment successful, close this tab" page- cancel.ts # GET — static "Payment cancelled" page-```--### Provider Registry (`lib/providers.ts`)--Unified interface — providers are swappable without changing API endpoints or client code:--```typescript-interface TranscriptionProvider {- id: string; // 'groq' | 'deepgram' | 'openai' | 'baseten' | ...- transcribe(audio: Blob, opts: TranscribeOpts): Promise<TranscribeResult>;-}--interface ReasoningProvider {- id: string; // 'groq' | 'openrouter' | 'baseten' | ...- complete(messages: Message[], opts: ReasonOpts): Promise<ReasonResult>;- models: ModelDefinition[]; // available models for this provider-}--interface TranscribeOpts {- language?: string;- prompt?: string; // custom dictionary hints- model?: string; // provider-specific model ID-}--interface ReasonOpts {- model: string;- maxTokens?: number;- temperature?: number;-}--// Provider implementations are simple adapters — most use OpenAI-compatible API format-// Adding a new provider = one new file implementing the interface + register it-```--Initial providers:-- **Groq**: transcription (`whisper-large-v3-turbo`) + fast reasoning (`llama-3.3-70b-versatile`)-- **OpenRouter**: reasoning model variety (Claude, Gemini, GPT via OpenAI-compatible API)--Future providers slot in by implementing the interface:-- **Baseten**: custom deployed models (transcription + reasoning)-- **Deepgram**: alternative transcription-- **OpenAI**: Whisper API transcription--The active provider is configured via environment variables — no code changes needed to switch:-```-TRANSCRIPTION_PROVIDER=groq # or 'deepgram', 'openai', 'baseten'-TRANSCRIPTION_MODEL=whisper-large-v3-turbo-REASONING_PROVIDERS=groq,openrouter # comma-separated, first is default-```--### Environment Variables (Vercel)-```-DATABASE_URL=<neon-postgres-connection-string>-NEON_AUTH_URL=<same as VITE_NEON_AUTH_URL>--# Provider keys (only configure what you use)-GROQ_API_KEY=<for transcription + fast reasoning>-OPENROUTER_API_KEY=<for model variety>-# Future: DEEPGRAM_API_KEY, BASETEN_API_KEY, OPENAI_API_KEY--# Provider routing-TRANSCRIPTION_PROVIDER=groq-TRANSCRIPTION_MODEL=whisper-large-v3-turbo-REASONING_PROVIDERS=groq,openrouter--# Stripe-STRIPE_SECRET_KEY=sk_...-STRIPE_WEBHOOK_SECRET=whsec_...-STRIPE_PRICE_ID=price_...-```-------## Step 2: Neon Postgres Schema--Run in Neon console. Neon Auth already has a `user` table.--```sql--- Transcription history (extensible for future metadata)-CREATE TABLE transcriptions (- id UUID DEFAULT gen_random_uuid() PRIMARY KEY,- user_id TEXT NOT NULL,- text TEXT NOT NULL,- word_count INTEGER NOT NULL,- source TEXT NOT NULL DEFAULT 'cloud', -- 'cloud' | 'byok' | 'local'- provider TEXT, -- 'groq' | 'deepgram' | 'openai' | 'baseten' | null- model TEXT, -- provider-specific model ID- language TEXT, -- ISO 639-1 code- audio_duration_ms INTEGER, -- original audio length (for analytics)- processing_ms INTEGER, -- server-side processing time- metadata JSONB DEFAULT '{}', -- extensible: { prompt, confidence, segments, ... }- created_at TIMESTAMPTZ DEFAULT now()-);-CREATE INDEX idx_tx_user ON transcriptions(user_id, created_at DESC);-CREATE INDEX idx_tx_source ON transcriptions(source);-CREATE INDEX idx_tx_user_date ON transcriptions(user_id, created_at)- WHERE source = 'cloud'; -- optimizes daily usage aggregation---- Subscription state (Stripe-managed)-CREATE TABLE subscriptions (- user_id TEXT PRIMARY KEY,- stripe_customer_id TEXT UNIQUE,- stripe_subscription_id TEXT UNIQUE,- plan TEXT NOT NULL DEFAULT 'free', -- 'free' | 'pro' | future tiers- status TEXT NOT NULL DEFAULT 'active', -- 'active' | 'past_due' | 'canceled' | 'trialing'- current_period_start TIMESTAMPTZ,- current_period_end TIMESTAMPTZ,- cancel_at_period_end BOOLEAN DEFAULT false, -- user requested cancellation- metadata JSONB DEFAULT '{}', -- extensible: { referral, coupon, ... }- created_at TIMESTAMPTZ DEFAULT now(),- updated_at TIMESTAMPTZ DEFAULT now()-);-```--**Schema design notes:**-- `metadata JSONB` columns on `transcriptions` and `subscriptions` provide extensibility without schema migrations-- `provider` + `model` on transcriptions enable per-provider analytics and cost tracking-- `audio_duration_ms` + `processing_ms` enable performance monitoring-- Daily usage is derived from `transcriptions` via `SUM(word_count) WHERE created_at >= CURRENT_DATE` — no separate usage table needed-- `idx_tx_user_date` partial index (filtered to `source = 'cloud'`) keeps the aggregate query fast-- `cancel_at_period_end` tracks pending cancellations (Stripe pattern)-- `current_period_start` needed for usage reset alignment-------## Step 3: API Endpoints--### `POST /api/transcribe` — Server-side transcription-- **Auth**: Session cookie (forwarded by Electron main process)-- **Request**: `multipart/form-data` — `file` (audio blob), `language`, `prompt` (dictionary)-- **Flow**:- 1. Validate session → get userId- 2. Route audio to active transcription provider (via provider registry)- 3. Count words from result: `text.trim().split(/\s+/).length`- 4. In one transaction:- - INSERT `transcriptions` row (with word_count)- - Aggregate today's usage: `SELECT COALESCE(SUM(word_count), 0) FROM transcriptions WHERE user_id = $1 AND created_at >= CURRENT_DATE AND source = 'cloud'`- - If aggregate > plan limit: return text + `limitReached: true`- 5. Return `{ text, wordsUsed, wordsRemaining, plan, limitReached }`-- **Limit logic**: Post-transcription check. The audio is already transcribed (API cost incurred) — don't waste it. `limitReached: true` tells the client the *next* request will be blocked. Pre-flight check via `GET /api/usage` handles UI state.-- **No separate usage table**: Daily usage is derived from the `transcriptions` table via aggregate query. The `idx_tx_user_date` partial index keeps this fast.--### `POST /api/reason` — Server-side reasoning-- **Auth**: Session cookie-- **Request**: `{ text, model?, agentName?, customDictionary? }`-- **Flow**:- 1. Validate session → get userId- 2. Resolve model → provider via provider registry- 3. Build system prompt (reuse `getSystemPrompt()` logic from Electron app)- 4. Call provider- 5. Return `{ text, model, provider }`-- **No usage counting** for reasoning (only transcription counts toward word limit)--### `GET /api/usage`-- Returns `{ wordsUsed, wordsRemaining, limit, plan, isSubscribed, resetAt }`-- `wordsUsed` derived from: `SELECT COALESCE(SUM(word_count), 0) FROM transcriptions WHERE user_id = $1 AND created_at >= CURRENT_DATE AND source = 'cloud'`-- `resetAt`: midnight UTC of current day (so client can show countdown)--### `POST /api/stripe/checkout`-- Creates Stripe Checkout session-- Success/cancel URLs point to `/checkout/success` and `/checkout/cancel` on the Vercel API-- Returns `{ url }`--### `POST /api/stripe/portal`-- Creates Customer Portal session, returns `{ url }`--### `POST /api/stripe/webhook`-- Events: `checkout.session.completed`, `customer.subscription.updated`, `customer.subscription.deleted`, `invoice.payment_failed`-- Updates `subscriptions` table (plan, status, period dates, cancel_at_period_end)--### `GET /checkout/success` + `GET /checkout/cancel`-- Simple static HTML pages: "Payment successful, you can close this tab" / "Payment cancelled"-- Electron app polls `/api/usage` after opening checkout URL and detects plan change--### Auth Validation (`lib/auth.ts`)-```typescript-// Session cookies forwarded from Electron main process-async function validateSession(cookieHeader: string): Promise<{ userId: string } | null> {- const res = await fetch(`${NEON_AUTH_URL}/api/auth/get-session`, {- headers: { Cookie: cookieHeader }- });- if (!res.ok) return null;- const data = await res.json();- return data?.session ? { userId: data.session.userId } : null;-}-```-------## Step 4: Electron App Changes--### Key Decision: IPC-First Architecture--All cloud API calls go through the main process via IPC. This:-- Eliminates CORS (main process is not subject to browser CORS)-- Reuses session cookies naturally (main process has access to session storage)-- Follows existing Anthropic handler pattern (`ipcHandlers.js:688`)-- Keeps renderer process thin and secure--### New IPC Handlers (in `ipcHandlers.js`)--```-cloud-transcribe — forwards audio + metadata to Vercel /api/transcribe-cloud-reason — forwards text + config to Vercel /api/reason-cloud-usage — fetches /api/usage-cloud-checkout — creates Stripe checkout session, returns URL-cloud-portal — creates Stripe portal session, returns URL-```--Each handler:-1. Gets session cookies from Electron's session store-2. Makes fetch request to Vercel API with cookies attached-3. Returns `{ success, data }` or `{ success: false, error, code }` (existing IPC pattern)--### New IPC Channels (in `preload.js`)--```javascript-cloudTranscribe: (audioBuffer, opts) => ipcRenderer.invoke('cloud-transcribe', audioBuffer, opts),-cloudReason: (text, opts) => ipcRenderer.invoke('cloud-reason', text, opts),-cloudUsage: () => ipcRenderer.invoke('cloud-usage'),-cloudCheckout: () => ipcRenderer.invoke('cloud-checkout'),-cloudPortal: () => ipcRenderer.invoke('cloud-portal'),-```--### New Setting: `cloudTranscriptionMode`--Add to `src/hooks/useSettings.ts`:-- `cloudTranscriptionMode`: `"openwhispr"` | `"byok"` (default: `"openwhispr"`)-- When signed in + `useLocalWhisper === false`: determines cloud routing-- When not signed in: ignored, falls through to BYOK--### New Files--**`src/hooks/useUsage.ts`** — Usage tracking hook-- Depends on `useAuth()` — only fetches when `isSignedIn`-- Calls `window.electronAPI.cloudUsage()` on mount-- Returns `{ plan, wordsUsed, wordsRemaining, limit, isSubscribed, isOverLimit, refetch }`-- Exposes `openCheckout()` and `openPortal()` (calls IPC → gets URL → `shell.openExternal()`)-- Returns `null` when not signed in (BYOK/local users see nothing)-- Caches result with TTL from existing `CACHE_CONFIG`--**`src/components/UsageDisplay.tsx`** — Usage meter-- Progress bar showing `wordsUsed / limit`-- "Unlimited" for Pro users-- "Upgrade" button when approaching/at limit--**`src/components/UpgradePrompt.tsx`** — Limit hit dialog-- Shown when transcription returns `limitReached: true`-- Three options: "Upgrade to Pro", "Use your own API key", "Switch to local"--### Modified Files--**`src/helpers/audioManager.js`** — Core routing change-- Add `processWithOpenWhisprCloud(audioBlob, metadata)` method:- - Calls `window.electronAPI.cloudTranscribe(audioArrayBuffer, { language, prompt })`- - Handles `limitReached` flag (emits event for UI to show UpgradePrompt)- - Returns same `{ success, text, source: "openwhispr", timings }` shape as other methods- - ~10 lines — all heavy lifting in the IPC handler-- Modify `processAudio()` routing (~line 219):- ```- if (useLocalWhisper) → processWithLocalWhisper/Parakeet (unchanged)- else if (cloudTranscriptionMode === "openwhispr" && isSignedIn) → processWithOpenWhisprCloud (NEW)- else → processWithOpenAIAPI (existing BYOK flow, unchanged)- ```--**`src/services/ReasoningService.ts`** — Add `"openwhispr"` provider-- Add `processWithOpenWhispr()` method alongside existing `processWithOpenAI()`, `processWithAnthropic()`, etc.-- Calls `window.electronAPI.cloudReason(text, { model, agentName, customDictionary })`-- When `cloudTranscriptionMode === "openwhispr"` && signed in, `reasoningProvider` is `"openwhispr"`-- Single routing point — no changes needed in `audioManager.js` for reasoning--**`src/hooks/useSettings.ts`**-- Add `cloudTranscriptionMode` setting with `useLocalStorage` hook--**`src/components/OnboardingFlow.tsx`** — Simplified step 1-- When signed in: default to OpenWhispr Cloud — show language picker + reasoning model selector (curated list from `modelRegistryData.json`, smart default pre-selected)-- Collapsible "Advanced: Use your own API key" section reveals existing TranscriptionModelPicker + ReasoningModelSelector-- When not signed in: show existing local/cloud picker (unchanged)--**`src/components/SettingsPage.tsx`**-- **Transcription section**: Mode toggle — "OpenWhispr Cloud" (simple) vs "Use your own API key" (shows existing provider/model/key pickers)-- **AI Models section**: When cloud mode, show curated model picker (from `modelRegistryData.json` cloud models section). When BYOK, show existing ReasoningModelSelector (unchanged)-- **Account section**: Add usage display (words today / limit), plan badge, upgrade/manage button--**`src/models/modelRegistryData.json`** — Add cloud model tiers-- Add `"openwhisprCloudModels"` section with curated tiers:- - **Fast** (Groq): `llama-3.3-70b-versatile`, `llama-3.1-8b-instant`- - **Balanced** (OpenRouter): `anthropic/claude-sonnet-4`, `google/gemini-2.5-flash`- - **Quality** (OpenRouter): `anthropic/claude-opus-4`, `openai/gpt-4.1`-- Ships with the app — works offline for model selection UI-- Future: `/api/models` endpoint can refresh this list periodically (cached in localStorage, daily check)--**`src/config/constants.ts`**-- Add `OPENWHISPR_API_URL` constant (from `VITE_API_URL` env var, used by main process IPC handlers)--**`.env.example`**-- Add `VITE_API_URL=`--### Error Handling Strategy--All cloud errors handled in IPC handlers with consistent `{ success, data, error, code }` shape:--| Scenario | Client behavior |-|----------|----------------|-| Network failure | If BYOK keys exist, offer fallback. Otherwise show "No connection" with retry |-| 401 Unauthorized | Session expired — trigger re-auth flow |-| 429 Rate limited | Show "Too many requests, try again shortly" |-| 500 Server error | Show generic error, log details for debugging |-| Timeout (>30s) | Show "Server busy" with retry option |-| Offline (`!navigator.onLine`) | Before attempting: toast "You're offline. Switch to local or reconnect." |--Use existing `RETRY_CONFIG` from `constants.ts` for automatic retries in the main process API client.-------## Step 5: UI/UX Design--### Design Principles-- **Minimal by default, powerful on demand** — signed-in users see 2 dropdowns, not 15 config fields-- **Never block, always guide** — limits hit? Text still pastes. Then a polished dialog offers paths forward-- **Upgrade prompts are helpful, not nagging** — surface Pro at natural friction points, never interrupt flow-- **Consistent visual language** — reuse existing shadcn/ui components, color scales, spacing, card patterns-- **Motion = meaning** — subtle transitions on state changes (progress bar color, badge swaps), no gratuitous animation--### Components to Reuse-| Existing Component | Used For |-|-------------------|----------|-| `Badge` (success/warning/destructive) | Plan pill ("Free", "Pro"), status indicators |-| `Progress` | Usage meter bar |-| `Dialog` | UpgradePrompt modal, limit hit |-| `Toast` (useToast) | Offline, errors, upgrade confirmation |-| `Card` / `CardHeader` / `CardContent` | Usage card, mode selector, option cards |-| `Button` (primary/outline/ghost) | Upgrade, manage, mode switches |-| `SettingsSection` / `SettingsGroup` | New settings areas match existing sections |-| `ProcessingModeSelector` | Adapt pattern for Cloud/BYOK toggle |-| `ProviderTabs` | Cloud model tier tabs (Fast/Balanced/Quality) |-| `Alert` (warning) | Approaching limit inline warning |-| `Select` | Cloud model dropdown |-| `LanguageSelector` | Reuse in simplified onboarding |-| `StepProgress` | Onboarding progress (unchanged, but step count may change) |-------### 5a. User Journeys--#### Journey 1: New User — "Just Works" (primary path, optimized for)--```-Launch app- → Onboarding Step 0: Account- ┌─────────────────────────────────────────┐- │ Create your account │- │ [Continue with Google] ← primary CTA │- │ ── or continue with email ── │- │ [email/password form] │- │ │- │ Benefits card (indigo-purple gradient): │- │ "Cloud transcription — just works" │- │ "2,000 words/day free" │- │ "AI text processing included" │- │ "No API keys needed" │- └─────────────────────────────────────────┘-- → Onboarding Step 1: Setup (SIMPLIFIED — see 5d)- Just 2 dropdowns: Language + AI Model- canProceed() = true immediately (smart defaults pre-selected)- User can literally just click "Next" without touching anything-- → Steps 2-4: Permissions → Hotkey → Agent Name (unchanged)-- → Complete → Start dictating- First transcription: audio → IPC → Vercel → text pasted- Zero configuration. Magic.-```--**Key insight**: A signed-in user can go from app launch to first dictation by clicking: Google sign-in → Next → Grant mic → Next → Set hotkey → Next → Name agent → Complete. The Setup step requires zero thought.--#### Journey 2: Power User — BYOK--```-Either during onboarding (clicks "Advanced" in Step 1)- or later in Settings → Transcription → "Use your own API key"-- → Existing TranscriptionModelPicker + ReasoningModelSelector appear- → Enter API key, select model, configure endpoint- → Audio routes direct to provider — no word limit, no usage tracking- → Everything works exactly as it does today-```--#### Journey 3: Privacy User — Local Only--```-Onboarding Step 0: "Continue without an account"- → Step 1: ProcessingModeSelector shows (unchanged)- Select "Local" → download whisper model- → Rest of onboarding unchanged- → All processing on-device, no network calls-```--#### Journey 4: Free → Pro Conversion (upgrade touchpoints)--Users encounter Pro naturally at friction points — never as a nag:--| Touchpoint | Trigger | What They See |-|------------|---------|---------------|-| **Settings account section** | Always visible when signed in | Usage meter + "Upgrade to Pro" button. Subtle, always there. |-| **80% usage toast** | First transcription after 1,600 words | One-time toast: "370 words remaining today". Not blocking. |-| **Limit reached dialog** | Transcription returns `limitReached` | UpgradePrompt dialog (see 5e). Text already pasted — not punitive. |-| **Next-day return** | User returns after hitting limit yesterday | Usage reset, but Settings shows "Yesterday you hit your limit" hint with Pro CTA |--**Anti-patterns we avoid:**-- No upgrade popups on app launch-- No upgrade banners in the dictation overlay-- No "you're on the free plan" warnings during active work-- No feature-gating of existing functionality (BYOK/local always available)-- No countdown timers or urgency tactics--#### Journey 5: Returning User — Already Signed In--```-App launches → onboarding already complete- → Control Panel shows transcription history- → Dictation overlay ready- → If cloud mode: first transcription fetches /api/usage in background- → Usage state cached, updates after each transcription- → If limit was hit yesterday: usage reset at midnight UTC, no friction-```--#### Journey 6: Pro User — Day-to-Day--```-Same as Journey 5, but:- → Settings account shows "Pro" badge (emerald) + "Unlimited" + "Manage" button- → No usage meter (no limit to track)- → No upgrade prompts ever surface- → "Manage" opens Stripe Customer Portal in browser-```-------### 5b. Onboarding Flow Changes--Current onboarding: 5 steps (Account → Setup → Permissions → Hotkey → Agent Name)--**Steps 0, 2, 3, 4 are unchanged.** Only Step 1 (Setup) changes based on auth state.--#### Step 0: Account — Minor Enhancement--Update the benefits card content to emphasize the "zero config" value prop:--```-┌─────────────────────────────────────────────────────┐-│ Why create an account? (indigo→purple bg) │-│ │-│ ● Instant transcription — no API keys needed │-│ ● 2,000 words/day free, unlimited with Pro │-│ ● AI text processing with world-class models │-│ ● Your settings sync across devices (future) │-└─────────────────────────────────────────────────────┘-```--"Continue without an account" link stays — no pressure.--#### Step 1: Setup — Two Completely Different Experiences--**Path A: Signed in** (simplified cloud-first experience)--```-┌─────────────────────────────────────────────────────┐-│ │-│ ┌──────┐ │-│ │ ✓ │ ← emerald circle (w-14 h-14) │-│ └──────┘ │-│ You're ready to go │ ← text-2xl font-semibold-│ │-│ OpenWhispr handles transcription and AI │ ← text-neutral-600-│ processing for you. No setup needed. │-│ │-│ ┌───────────────────────────────────────────────┐ │-│ │ Language │ │ ← neutral-50 card-│ │ [ Auto-detect ▾ ] │ │ ← LanguageSelector (existing)-│ │ │ │-│ │ AI Model │ │-│ │ [ Llama 3.3 70B · Fast ▾ ] │ │ ← Select, pre-selected default-│ │ ↑ smart default │ │-│ └───────────────────────────────────────────────┘ │-│ │-│ ┌───────────────────────────────────────────────┐ │-│ │ Advanced options ▸ │ │ ← ghost button, neutral-500-│ └───────────────────────────────────────────────┘ │-│ (collapsed by default — expands to show existing │-│ ProcessingModeSelector + TranscriptionModelPicker │-│ + ReasoningModelSelector for BYOK/local) │-│ │-│ ┌───────────────────────────────────────────────┐ │-│ │ Included with your account: │ │ ← blue-50 card, text-sm-│ │ ✓ 2,000 words/day ✓ AI processing │ │-│ │ ✓ Multiple AI models ✓ Custom dictionary │ │-│ └───────────────────────────────────────────────┘ │-│ │-└─────────────────────────────────────────────────────┘-```--**canProceed()**: Always `true` — defaults are pre-selected. User can literally click Next immediately.--**"Advanced options" behavior:**-- Click → section expands with smooth height transition-- Shows existing `ProcessingModeSelector` + full `TranscriptionModelPicker` + `ReasoningModelSelector`-- Selecting any BYOK/local option sets `cloudTranscriptionMode` accordingly-- Collapsing the section reverts to cloud defaults (with confirmation if they entered a key)--**Path B: Not signed in** (unchanged)--Shows existing `ProcessingModeSelector` (Local vs Cloud cards) + `TranscriptionModelPicker` + `LanguageSelector`. No simplification — they need to configure everything manually because they're not using cloud mode.-------### 5c. Settings Page — Account Section Enhancement--Current: gradient card with avatar + name + email + sign-out.--**Add `UsageDisplay` component below the existing signed-in card:**--#### Free Plan — Normal Usage (<80%)-```-┌─────────────────────────────────────────────────┐-│ │-│ Today's Usage Free ← Badge outline │ ← text-sm font-medium-│ │-│ ██████████░░░░░░░░░░░░░░░░░░ 847 / 2,000 │ ← Progress (indigo-600), text-sm tabular-nums-│ │-│ Resets at midnight UTC │ ← text-xs text-neutral-400-│ │-│ ┌───────────────────────────────────────────┐ │-│ │ Upgrade to Pro — unlimited transcriptions │ │ ← subtle CTA: text link, not button-│ └───────────────────────────────────────────┘ │-│ │-└─────────────────────────────────────────────────┘-```--- Card: `bg-white border border-neutral-200 rounded-xl` (clean, not gradient — gradient is for the profile card above)-- "Upgrade to Pro" is a `text-indigo-600 hover:text-indigo-700 text-sm` link, not a loud button. Subtle.-- Progress bar: `h-2 rounded-full`, indigo-600 fill, neutral-100 track--#### Free Plan — Approaching Limit (>80%)-```-┌─────────────────────────────────────────────────┐-│ │-│ Today's Usage Free ← Badge outline │-│ │-│ ██████████████████████████░░░ 1,847 / 2,000 │ ← Progress (amber-500)-│ │-│ 153 words remaining │ ← text-xs text-amber-600 (replaces "resets at")-│ │-│ [ Upgrade to Pro ] │ ← Button primary (indigo), appears at >80%-│ │-└─────────────────────────────────────────────────┘-```--- Progress bar color transitions: indigo-600 → amber-500 at 80% → red-500 at 100%-- CTA elevates from text link to primary button when approaching limit--#### Free Plan — At Limit-```-┌─────────────────────────────────────────────────┐-│ │-│ Today's Usage Limit reached ← Badge warn │-│ │-│ ██████████████████████████████ 2,000 / 2,000 │ ← Progress (red-500, full)-│ │-│ Resets at midnight UTC │-│ │-│ [ Upgrade to Pro ] [ Use Your Own Key ] │ ← Button primary + Button outline-│ │-└─────────────────────────────────────────────────┘-```--#### Pro Plan-```-┌─────────────────────────────────────────────────┐-│ │-│ Your Plan Pro ← Badge success │-│ │-│ Unlimited transcriptions │ ← text-sm text-neutral-600-│ │-│ [ Manage Subscription ] │ ← Button outline (opens Stripe Portal)-│ │-└─────────────────────────────────────────────────┘-```--- Clean, minimal. No progress bar (nothing to track). Badge is emerald/success.-- "Manage Subscription" → IPC → Stripe Customer Portal URL → `shell.openExternal()`--#### Not Signed In-- `UsageDisplay` component not rendered at all. Existing sign-in prompt shown.-------### 5d. Settings Page — Transcription Mode Toggle--**Only shown when signed in.** Appears at top of Transcription Mode settings section.--```-┌─────────────────────────────────────────────────┐-│ ☁ OpenWhispr Cloud ● ──┐ │ ← selected: border-indigo-500/30, bg-indigo-50/30-│ Just works. No configuration needed. │ │ │-│ │ │ │ ← radio-style, only one active-│ 🔑 Bring Your Own Key ○ ──┘ │ ← unselected: border-neutral-200, bg-white-│ Use your own API key. No usage limits. │-└─────────────────────────────────────────────────┘-```--- Same card-selection pattern as `ProcessingModeSelector` (indigo border + tinted bg for active)-- **Cloud selected**: Everything below is hidden. Clean empty state — maybe a single line: "Transcription is handled by OpenWhispr's servers. Change your language in General settings."-- **BYOK selected**: Existing `TranscriptionModelPicker` appears below (unchanged)-- Smooth height transition when switching (existing CSS pattern: `transition-all duration-200`)--**When not signed in:** This toggle is not rendered. User sees existing `TranscriptionModelPicker` directly.-------### 5e. Settings Page — AI Models Section (Cloud Mode)--When `cloudTranscriptionMode === "openwhispr"`, replace `ReasoningModelSelector` with a simplified cloud model picker:--```-┌─────────────────────────────────────────────────┐-│ AI Model │-│ │-│ ┌──────┐ ┌──────────┐ ┌─────────┐ │-│ │ Fast │ │ Balanced │ │ Quality │ │ ← ProviderTabs (3 tiers)-│ └──────┘ └──────────┘ └─────────┘ │-│ │-│ ┌───────────────────────────────────────────┐ │-│ │ Llama 3.3 70B │ │ ← Select dropdown-│ │ ───────────────────── │ │-│ │ Llama 3.3 70B Recommended │ │-│ │ Llama 3.1 8B Fastest │ │-│ └───────────────────────────────────────────┘ │-│ │-│ No API key needed. Powered by OpenWhispr. │ ← text-xs text-neutral-400-│ │-└─────────────────────────────────────────────────┘-```--- `ProviderTabs` reused with tier labels: "Fast" (Groq), "Balanced" (OpenRouter), "Quality" (OpenRouter)-- Each tier has a simple `Select` dropdown (not full ModelCardList — keep it minimal)-- "Recommended" badge on the default model per tier-- Model data from `modelRegistryData.json` `openwhisprCloudModels` section (ships with app, works offline)--**When BYOK mode:** Show existing `ReasoningModelSelector` unchanged.-------### 5f. UpgradePrompt Dialog--Shown when transcription returns `limitReached: true`. Text is already pasted — this is not blocking work.--```-┌─────────────────────────────────────────────────────┐-│ ╳ │-│ │-│ You've reached today's limit │ ← text-xl font-semibold, centered-│ │-│ 2,000 of 2,000 words used. │ ← text-sm text-neutral-500-│ Your transcription was saved and pasted. │-│ │-│ ┌─────────────────────────────────────────────┐ │-│ │ │ │-│ │ Upgrade to Pro → │ │ ← Card, from-indigo-50 to-purple-50/50-│ │ Unlimited transcriptions. $X/month. │ │ border-indigo-200-│ │ │ │ hover: shadow-md transition-│ └─────────────────────────────────────────────┘ │-│ ┌─────────────────────────────────────────────┐ │-│ │ Use your own API key → │ │ ← Card, bg-neutral-50, border-neutral-200-│ │ Bring your own key for unlimited use. │ │ hover: border-neutral-300-│ └─────────────────────────────────────────────┘ │-│ ┌─────────────────────────────────────────────┐ │-│ │ Switch to local → │ │ ← Card, bg-neutral-50, border-neutral-200-│ │ Offline transcription. No limits. │ │-│ └─────────────────────────────────────────────┘ │-│ │-│ Resets at midnight UTC │ ← text-xs text-neutral-400 centered-│ │-└─────────────────────────────────────────────────────┘-```--**Behavior:**-- "Upgrade to Pro" → IPC → checkout URL → `shell.openExternal()` → dialog stays open (user returns after checkout)-- "Use your own API key" → sets `cloudTranscriptionMode = "byok"`, closes dialog, opens Settings to Transcription section-- "Switch to local" → sets `useLocalWhisper = true`, closes dialog (if model downloaded) or opens Settings to download model-- Dialog is dismissible (X button or click outside) — user can just close it and continue working until midnight reset-- Shown max once per limit-hit session (don't re-show on every subsequent failed attempt — just show a toast after the first dialog)-------### 5g. Toast Notifications--All using existing `useToast` hook. Concise, actionable, never annoying.--| Event | Variant | Message | Frequency |-|-------|---------|---------|-----------|-| Offline + cloud mode attempt | `destructive` | "You're offline. Switch to local transcription or reconnect." | Every attempt |-| Cloud transcription network error | `destructive` | "Transcription failed. Retrying..." / "Transcription failed." | Per error |-| Session expired (401) | `destructive` | "Session expired. Sign in again in Settings." | Once per session |-| Approaching limit (>80%) | `default` | "{n} words remaining today." | Once per session |-| Limit hit (after first dialog dismissed) | `default` | "Daily limit reached. Resets at midnight UTC." | Per attempt |-| Post-upgrade (usage refetch detects Pro) | `success` | "Pro activated. Unlimited transcriptions." | Once |-| Provider switch (BYOK/local) | `success` | "Switched to [mode]. No usage limits." | Once per switch |-------### 5h. Main Dictation Overlay (App.jsx)--**No changes to the overlay UI.** The floating button stays minimal:-- No usage meter (too distracting during active work)-- No plan badges (irrelevant during dictation)-- No upgrade prompts in the overlay--**Behavioral changes only:**-- When `limitReached` returns: paste text normally → after paste completes, show `UpgradePrompt` dialog in the Control Panel window (not the overlay)-- When offline + cloud mode: show toast in Control Panel before recording starts. If user is in overlay-only mode, the toast appears there.-- When session expired: transcription fails → toast → user opens Control Panel to re-auth-------### 5i. Control Panel — Transcription History Enhancement--Minor addition to `ControlPanel.tsx`:--- **Cloud transcriptions**: Show a subtle cloud icon (Cloud, size-3, text-neutral-400) next to timestamp for cloud-transcribed items-- **Source indicator**: `source` field from transcription result → tiny pill: "cloud" | "local" | "byok" in text-xs text-neutral-400-- No other changes to the history UI-------### 5j. Micro-Interactions & Polish--| Element | Detail |-|---------|--------|-| Usage progress bar | Color transitions smoothly (CSS `transition-colors duration-500`) between indigo → amber → red as usage increases |-| Mode toggle cards | Selected card has subtle `shadow-sm` + `ring-1 ring-indigo-500/20` — feels "pressed in" |-| UpgradePrompt option cards | `hover:shadow-md transition-shadow duration-150` — cards lift slightly on hover |-| Plan badge | `Badge` component with `transition-colors` — swaps from outline to success variant when Pro activates |-| Onboarding Step 1 (signed in) | Content fades in with `animate-in fade-in-0 duration-300` when step loads |-| Advanced section expand | `transition-[max-height] duration-200 ease-out` — smooth expand/collapse |-| Toast notifications | Existing slide-in animation from bottom-right (already implemented) |-| Model tier tabs | Existing `ProviderTabs` sliding indicator animation (already implemented) |-------## Step 6: UX Flows--### New User — Signed In (primary path)-1. Open app → Onboarding Step 0: Create account (Google or email)-2. Step 1: "You're ready to go" — defaults pre-selected, click Next-3. Steps 2-4: Permissions → Hotkey → Agent Name (unchanged)-4. Complete → Start dictating. Zero config. Audio → IPC → Vercel → text pasted.--### New User — No Account-1. Open app → Onboarding Step 0: "Continue without an account"-2. Step 1: Full setup — ProcessingModeSelector (Local/Cloud) + model config + API key-3. Steps 2-4: unchanged-4. Complete → dictating works via BYOK or local--### Power User — Switch to BYOK-1. Settings → Transcription → "Bring Your Own Key"-2. Existing TranscriptionModelPicker appears → enter key, pick model-3. Audio goes direct to provider — no word limit, no usage tracking--### Free → Pro Conversion-1. User hits 80% usage → one-time toast: "370 words remaining"-2. User hits limit → text pastes normally → UpgradePrompt dialog-3. User clicks "Upgrade to Pro" → Stripe Checkout in browser-4. After payment → webhook updates DB → app polls /api/usage → Pro detected-5. Toast: "Pro activated. Unlimited transcriptions."-6. Settings shows Pro badge, "Manage Subscription" button. No more usage meter.--### Stripe Checkout-1. Upgrade CTA (settings or dialog) → IPC → Vercel creates Stripe Checkout session-2. `shell.openExternal(url)` → browser opens Stripe-hosted checkout-3. After payment → static "Payment successful, close this tab" page on Vercel-4. Electron app polls `/api/usage` every 3s for up to 60s after opening checkout-5. Detects plan change → success toast → UI updates--### Offline-1. `navigator.onLine` check before cloud transcription-2. Toast: "You're offline. Switch to local transcription or reconnect."-3. Local mode always works. BYOK may work depending on provider accessibility.-------## Implementation Order--### Phase 1: Dead Code Cleanup (prerequisite PR) ✅ COMPLETE-1. ✅ Remove dead `onOAuthCallback` in `preload.js:171`-2. ✅ Remove stale comment in `AuthenticationStep.tsx:64`-3. ✅ Merge to main--### Phase 2: API Foundation ✅ COMPLETE-4. ✅ `git init` new repo at `~/Projects/OpenWhispr/openwhispr-api/`-5. ✅ Set up Vercel project, TypeScript, dependencies-6. ✅ Create Neon Postgres schema (run SQL in console)-7. ✅ Implement `lib/auth.ts`, `lib/db.ts`, `lib/usage.ts`, `lib/providers.ts`-8. ✅ Implement Groq transcription provider + OpenRouter reasoning provider-9. ✅ Implement `POST /api/transcribe` + `GET /api/usage`-10. ✅ Implement `POST /api/reason`-11. ✅ Test with curl--### Phase 3: Electron → API Integration ✅ COMPLETE-12. ✅ Add IPC handlers for `cloud-transcribe`, `cloud-reason`, `cloud-usage` to `ipcHandlers.js`-13. ✅ Add IPC channels to `preload.js`-14. ✅ Add `cloudTranscriptionMode` to `useSettings.ts`-15. ✅ Add `processWithOpenWhisprCloud()` to `audioManager.js`-16. ✅ Wire transcription routing in `processAudio()`-17. ✅ Add `"openwhispr"` provider to `ReasoningService.ts`-18. ⏳ Test: sign in → dictate → transcription + reasoning via API--### Phase 4: Usage Tracking & UI ✅ COMPLETE-19. ✅ Create `useUsage.ts` hook-20. ✅ Create `UsageDisplay.tsx` + `UpgradePrompt.tsx`-21. ✅ Update `SettingsPage.tsx` — mode toggle + usage display-22. ✅ Update `OnboardingFlow.tsx` — simplified step 1 for signed-in users-23. ✅ Add cloud model tiers to `modelRegistryData.json`-24. ✅ Integrate UpgradePrompt into ControlPanel for limit-reached events-25. ✅ Add IPC channels for limit-reached cross-window communication-26. ✅ Add TypeScript types for cloud API methods--### Phase 5: Stripe ❌ NOT STARTED-27. ❌ Set up Stripe product/price in dashboard-28. ❌ Implement checkout, portal, webhook endpoints-29. ❌ Add `/checkout/success` and `/checkout/cancel` pages-30. ❌ Add IPC handlers for `cloud-checkout`, `cloud-portal`-31. ❌ Wire upgrade/manage buttons to Stripe in UsageDisplay + UpgradePrompt-32. ❌ Test full payment flow with Stripe CLI-------## Risks & Mitigations--| Risk | Mitigation |-|------|-----------|-| Session cookies not forwardable from main process | Electron's `session.cookies.get()` API provides access. Already used for `authClearSession`. |-| Vercel 4.5MB body limit | Dictation audio is typically 50-200KB. Client already optimizes. |-| Vercel function timeout (10s free) | Transcription takes 1-5s. Use Vercel Pro plan (60s) if needed. |-| Stripe can't redirect back to Electron | Static success/cancel pages on Vercel. App polls `/api/usage`. |-| Provider outage | Provider registry makes switching providers a config change. No code deploy needed. |-| Offline users on cloud mode | `navigator.onLine` check + clear toast with actionable options. |-------## Verification--1. **API auth**: `curl` with session cookie → `/api/usage` returns usage-2. **Default transcription**: Sign in → dictate → text appears (no API key configured)-3. **Default reasoning**: Enable reasoning → dictate "Hey Agent, ..." → AI-processed text returned-4. **Model selection**: Change reasoning model in settings → verify different model used-5. **BYOK mode**: Switch to BYOK → enter key → dictate → works with no word limit-6. **Local mode**: Switch to local → dictate → works offline, no API calls-7. **Usage limit**: Transcribe >2000 words → text still pastes → `UpgradePrompt` appears-8. **Stripe**: `stripe listen --forward-to localhost:3000/api/stripe/webhook` → checkout → plan updates-9. **Offline**: Disconnect network → cloud mode → offline toast → switch to local → works-10. **Sign-out**: Cloud features disabled, local data preserved, BYOK keys retained-11. **Provider swap**: Change `TRANSCRIPTION_PROVIDER` env var → verify new provider used (no code change)