How braden-w/whispering works
Project type and purpose
• Whispering is a cross-platform desktop (macOS, Windows, Linux) and web app for real-time speech-to-text transcription and AI-driven text transformations.
• It uses SvelteKit for UI, Tauri (Rust) for native OS integration, and Dexie (IndexedDB) for local storage. It relies on external transcription (Groq, OpenAI, etc.) and AI transformation (Claude, GPT, etc.) services via user-provided API keys.
File structure
• Top level “apps/app” contains the SvelteKit/Tauri app:
– src-tauri: Rust backend (commands.rs, main.rs, recorder manager threads)
– src/lib/services: pure business logic with platform-agnostic interfaces
– src/lib/query: TanStack Query wrappers for reactivity & DI
– src/lib/components + src/routes: Svelte UI
– IndexedDB via Dexie models under services/db
• packages/shared and packages/ui hold shared TypeScript utilities and reusable UI components.
• .github workflows, pnpm/turbo configs orchestrate CI/CD and monorepo management.
README insights
• Three-layer architecture:
UI Layer (Svelte) → Query Layer (TanStack Query) → Service Layer (pure TS)
• Platform abstraction at build time: JS chooses desktop vs. web implementations.
• Tauri RPC facilitates calls from JS → Rust for clipboard, recording, notifications, etc.
• Local data stored in IndexedDB; audio blobs and transcription records persisted.
• External services accessed directly from the client using user API keys.
Main components & their interactions
a. Components to show:
• UI Layer (SvelteKit app)
• Query Layer (TanStack Query wrappers)
• Service Layer (pure TS business logic)
• Platform Implementations:
– Desktop (Tauri/Rust)
– Web (Browser APIs)
• Local Storage (IndexedDB via Dexie)
• External Services:
– Transcription providers (Groq, OpenAI, ElevenLabs, Speaches)
– AI transformation providers (Claude, GPT, Gemini, Groq LLMs)
b. Relationships/Data Flows:
1. User presses shortcut or clicks UI → UI Layer emits actions.
2. UI calls Query Layer’s queries/mutations.
3. Query Layer injects settings (API keys, selected models) and calls Service Layer.
4. Service Layer routes to platform implementation:
– If desktop: use Tauri RPC → Rust backend performs OS tasks (recording, global shortcuts, notifications).
– If web: use browser APIs.
5. For transcription: audio Blob flows from Service → external API over HTTP → transcript returns.
6. For transformations: text flows from Service → selected AI provider → transformed text.
7. Service Layer writes/reads recordings and runs to IndexedDB.
8. Query Layer updates cache → UI re-renders.
c. Architectural patterns/design principles:
• Three‐layer separation (UI/Query/Service) with clear boundaries.
• Platform‐agnostic service interfaces with build-time resolution to desktop or web impl.
• RPC pattern (Tauri) for Rust–JS integration.
• Dependency injection of settings for runtime service selection.
• Optimistic updates and cache management in Query Layer.
• Pure functions and Result<T,E> error handling (WellCrafted).
d. Technologies/frameworks/libraries to annotate:
• SvelteKit (+ Tailwind) for UI and routing
• TanStack Query for reactivity & data synchronization
• Tauri & Rust for native features (recorder, clipboard, notifications, shortcuts)
• Dexie.js (IndexedDB) for local persistence
• External HTTP clients for transcription/AI APIs
• Turborepo/PNPM for monorepo management
• Shared UI components in packages/ui, utilities in packages/shared
Detailed capture of essential elements
• Related services under the Service Layer.
• 97% code‐sharing advantage by annotating the Service Layer as platform‐agnostic.
• Tauri RPC boundary between JS and Rust.
• Where settings & DI occur (transcription.selectedService → Service invocation).