# braden-w/whispering architecture

> Architecture diagram of the GitHub repository braden-w/whispering, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/braden-w/whispering
- Repository: https://github.com/braden-w/whispering

## Overview

##### 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).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User
    User["User"]:::user
    User -->|"interacts"| UIComponents

    %% Frontend Layer
    subgraph "Frontend (SvelteKit)" 
        UIComponents["UI Components"]:::frontend
        UIRoutes["UI Routes"]:::frontend
        UIComponents -->|"renders/routes"| UIRoutes
        UIRoutes -->|"triggers"| Query
        Query["Query Layer"]:::query
        Service["Service Layer"]:::service
        UIRoutes -->|"calls queries"| Query
        Query -->|"invokes services"| Service
    end

    %% Platform Implementations
    Service -->|"calls platform API"| DesktopAdapters
    Service -->|"calls platform API"| WebAdapters

    subgraph "Desktop Implementations (JS)" 
        DesktopAdapters["Desktop Adapters"]:::platform
        cbDesktop["clipboard/desktop.ts"]:::platform
        httpDesktop["http/desktop.ts"]:::platform
        downloadDesktop["download/desktop.ts"]:::platform
        notificationsDesktop["notifications/desktop.ts"]:::platform
        osDesktop["os/desktop.ts"]:::platform
        soundDesktop["sound/desktop.ts"]:::platform
        DesktopAdapters --> cbDesktop
        DesktopAdapters --> httpDesktop
        DesktopAdapters --> downloadDesktop
        DesktopAdapters --> notificationsDesktop
        DesktopAdapters --> osDesktop
        DesktopAdapters --> soundDesktop
    end

    subgraph "Web Implementations (Browser APIs)" 
        WebAdapters["Web Adapters"]:::platform
        cbWeb["clipboard/web.ts"]:::platform
        httpWeb["http/web.ts"]:::platform
        downloadWeb["download/web.ts"]:::platform
        notificationsWeb["notifications/web.ts"]:::platform
        osWeb["os/web.ts"]:::platform
        soundWeb["sound/web.ts"]:::platform
        WebAdapters --> cbWeb
        WebAdapters --> httpWeb
        WebAdapters --> downloadWeb
        WebAdapters --> notificationsWeb
        WebAdapters --> osWeb
        WebAdapters --> soundWeb
    end

    %% Tauri RPC & Rust Backend
    DesktopAdapters -->|"RPC via Tauri"| RustMain
    subgraph "Tauri RPC & Rust Backend"
        RustMain["main.rs & lib.rs"]:::rust
        RecorderCommands["commands.rs"]:::rust
        Manager["recorder/manager.rs"]:::rust
        Threads["recorder/thread.rs"]:::rust
        RustMain --> RecorderCommands
        RecorderCommands --> Manager
        Manager --> Threads
    end

    %% Local Storage
    Service --> DB["IndexedDB via Dexie"]:::storage
    subgraph "IndexedDB via Dexie"
        dexie["dexie.ts"]:::storage
        recModel["recordings.ts"]:::storage
        runModel["transformation-runs.ts"]:::storage
        transModel["transformations.ts"]:::storage
        DB --> dexie
        DB --> recModel
        DB --> runModel
        DB --> transModel
    end

    %% External Services
    subgraph "External Services"
        Transcription["Transcription Providers"]:::external
        Completion["AI Transformation Providers"]:::external
        Service -->|"HTTP"| Transcription
        Service -->|"HTTP"| Completion

        subgraph "Transcription Providers"
            groq["groq.ts"]:::external
            openaiT["openai.ts"]:::external
            elevenlabs["elevenlabs.ts"]:::external
            speaches["speaches.ts"]:::external
            Transcription --> groq
            Transcription --> openaiT
            Transcription --> elevenlabs
            Transcription --> speaches
        end

        subgraph "Completion Providers"
            anthropic["anthropic.ts"]:::external
            google["google.ts"]:::external
            groqLLM["groq.ts"]:::external
            openaiC["openai.ts"]:::external
            Completion --> anthropic
            Completion --> google
            Completion --> groqLLM
            Completion --> openaiC
        end
    end

    %% Shared Packages
    subgraph "Monorepo Shared"
        SharedUtils["Shared Utilities"]:::shared
        SharedUI["Shared UI Components"]:::shared
        RPCJS["Tauri RPC JS Wrappers"]:::shared
        SharedUtils --> RPCJS
        SharedUI --> RPCJS
    end

    Service --> RPCJS

    %% Click Events
    click UIComponents "https://github.com/braden-w/whispering/tree/main/apps/app/src/lib/components"
    click UIRoutes "https://github.com/braden-w/whispering/tree/main/apps/app/src/routes"
    click Query "https://github.com/braden-w/whispering/tree/main/apps/app/src/lib/query"
    click Service "https://github.com/braden-w/whispering/blob/main/apps/app/src/lib/services/index.ts"
    click RustMain "https://github.com/braden-w/whispering/blob/main/apps/app/src-tauri/src/main.rs"
    click RustMain "https://github.com/braden-w/whispering/blob/main/apps/app/src-tauri/src/lib.rs"
    click RecorderCommands "https://github.com/braden-w/whispering/blob/main/apps/app/src-tauri/src/recorder/commands.rs"
    click Manager "https://github.com/braden-w/whispering/blob/main/apps/app/src-tauri/src/recorder/manager.rs"
    click Threads "https://github.com/braden-w/whispering/blob/main/apps/app/src-tauri/src/recorder/thread.rs"
    click cbWeb "https://github.com/braden-w/whispering/blob/main/apps/app/src/lib/services/clipboard/web.ts"
    click httpWeb "https://github.com/braden-w/whispering/blob/main/apps/app/src/lib/services/http/web.ts"
    click downloadWeb "https://github.com/braden-w/whispering/blob/main/apps/app/src/lib/services/download/web.ts"
    click notificationsWeb "https://github.com/braden-w/whispering/blob/main/apps/app/src/lib/services/notifications/web.ts"
    click osWeb "https://github.com/braden-w/whispering/blob/main/apps/app/src/lib/services/os/web.ts"
    click soundWeb "https://github.com/braden-w/whispering/blob/main/apps/app/src/lib/services/sound/web.ts"
    click cbDesktop "https://github.com/braden-w/whispering/blob/main/apps/app/src/lib/services/clipboard/desktop.ts"
    click httpDesktop "https://github.com/braden-w/whispering/blob/main/apps/app/src/lib/services/http/desktop.ts"
    click downloadDesktop "https://github.com/braden-w/whispering/blob/main/apps/app/src/lib/services/download/desktop.ts"
    click notificationsDesktop "https://github.com/braden-w/whispering/blob/main/apps/app/src/lib/services/notifications/desktop.ts"
    click osDesktop "https://github.com/braden-w/whispering/blob/main/apps/app/src/lib/services/os/desktop.ts"
    click soundDesktop "https://github.com/braden-w/whispering/blob/main/apps/app/src/lib/services/sound/desktop.ts"
    click dexie "https://github.com/braden-w/whispering/blob/main/apps/app/src/lib/services/db/dexie.ts"
    click recModel "https://github.com/braden-w/whispering/blob/main/apps/app/src/lib/services/db/models/recordings.ts"
    click runModel "https://github.com/braden-w/whispering/blob/main/apps/app/src/lib/services/db/models/transformation-runs.ts"
    click transModel "https://github.com/braden-w/whispering/blob/main/apps/app/src/lib/services/db/models/transformations.ts"
    click groq "https://github.com/braden-w/whispering/blob/main/apps/app/src/lib/services/transcription/groq.ts"
    click openaiT "https://github.com/braden-w/whispering/blob/main/apps/app/src/lib/services/transcription/openai.ts"
    click elevenlabs "https://github.com/braden-w/whispering/blob/main/apps/app/src/lib/services/transcription/elevenlabs.ts"
    click speaches "https://github.com/braden-w/whispering/blob/main/apps/app/src/lib/services/transcription/speaches.ts"
    click anthropic "https://github.com/braden-w/whispering/blob/main/apps/app/src/lib/services/completion/anthropic.ts"
    click google "https://github.com/braden-w/whispering/blob/main/apps/app/src/lib/services/completion/google.ts"
    click groqLLM "https://github.com/braden-w/whispering/blob/main/apps/app/src/lib/services/completion/groq.ts"
    click openaiC "https://github.com/braden-w/whispering/blob/main/apps/app/src/lib/services/completion/openai.ts"
    click RPCJS "https://github.com/braden-w/whispering/blob/main/apps/app/src/lib/commands.ts"
    click SharedUtils "https://github.com/braden-w/whispering/blob/main/packages/shared/src/index.ts"
    click SharedUI "https://github.com/braden-w/whispering/tree/main/packages/ui/src"

    %% Styles
    classDef frontend fill:#E3F2FD,stroke:#42A5F5,stroke-width:1px
    classDef query fill:#E8F5E9,stroke:#66BB6A,stroke-width:1px
    classDef service fill:#FFF3E0,stroke:#FFA726,stroke-width:1px
    classDef platform fill:#F3E5F5,stroke:#AB47BC,stroke-width:1px
    classDef rust fill:#ECEFF1,stroke:#78909C,stroke-width:1px
    classDef storage fill:#EFEBE9,stroke:#8D6E63,stroke-width:1px
    classDef external fill:#F1F8E9,stroke:#8BC34A,stroke-width:1px
    classDef shared fill:#EDE7F6,stroke:#5E35B1,stroke-width:1px
    classDef user fill:#FFEBEE,stroke:#E53935,stroke-width:1px
```
