Skip to content

CLAUDE.md

Latest commit

 

History

History
114 lines (79 loc) · 3.75 KB

CLAUDE.md

File metadata and controls

114 lines (79 loc) · 3.75 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Commands

Prerequisites: Rust (latest stable), Bun

# Install dependencies
bun install

# Run in development mode
bun run tauri dev
# If cmake error on macOS:
CMAKE_POLICY_VERSION_MINIMUM=3.5 bun run tauri dev

# Build for production
bun run tauri build

# Linting and formatting (run before committing)
bun run lint              # ESLint for frontend
bun run lint:fix          # ESLint with auto-fix
bun run format            # Prettier + cargo fmt
bun run format:check      # Check formatting without changes

Model Setup (Required for Development):

mkdir -p src-tauri/resources/models
curl -o src-tauri/resources/models/silero_vad_v4.onnx https://blob.handy.computer/silero_vad_v4.onnx

Architecture Overview

Phonara is a cross-platform desktop speech-to-text app built with Tauri 2.x (Rust backend + React/TypeScript frontend).

Backend Structure (src-tauri/src/)

  • lib.rs - Main entry point, Tauri setup, manager initialization
  • managers/ - Core business logic:
    • audio.rs - Audio recording and device management
    • model.rs - Model downloading and management
    • transcription.rs - Speech-to-text processing pipeline
    • history.rs - Transcription history storage
  • audio_toolkit/ - Low-level audio processing:
    • audio/ - Device enumeration, recording, resampling
    • vad/ - Voice Activity Detection (Silero VAD)
  • commands/ - Tauri command handlers for frontend communication
  • shortcut.rs - Global keyboard shortcut handling
  • settings.rs - Application settings management

Frontend Structure (src/)

  • App.tsx - Main component with onboarding flow
  • components/settings/ - Settings UI (35+ files)
  • components/model-selector/ - Model management interface
  • components/onboarding/ - First-run experience
  • hooks/useSettings.ts, useModels.ts - State management hooks
  • stores/settingsStore.ts - Zustand store for settings
  • bindings.ts - Auto-generated Tauri type bindings (via tauri-specta)
  • overlay/ - Recording overlay window code

Key Patterns

Manager Pattern: Core functionality organized into managers (Audio, Model, Transcription) initialized at startup and managed via Tauri state.

Command-Event Architecture: Frontend -> Backend via Tauri commands; Backend -> Frontend via events.

Pipeline Processing: Audio -> VAD -> Whisper/Parakeet -> Text output -> Clipboard/Paste

State Flow: Zustand -> Tauri Command -> Rust State -> Persistence (tauri-plugin-store)

Internationalization (i18n)

All user-facing strings must use i18next translations. ESLint enforces this (no hardcoded strings in JSX).

Adding new text:

  1. Add key to src/i18n/locales/en/translation.json
  2. Use in component: const { t } = useTranslation(); t('key.path')

Code Style

Rust:

  • Run cargo fmt and cargo clippy before committing
  • Handle errors explicitly (avoid unwrap in production)

TypeScript/React:

  • Strict TypeScript, avoid any types
  • Functional components with hooks
  • Tailwind CSS for styling
  • Path aliases: @/ -> ./src/

Debug Mode

Access debug features: Cmd+Shift+D (macOS) or Ctrl+Shift+D (Windows/Linux)

Platform Notes

  • macOS: Metal acceleration, accessibility permissions required
  • Windows: Vulkan acceleration (LLVM 18, Vulkan SDK required for build)
  • Linux: OpenBLAS + Vulkan, limited Wayland support, overlay disabled by default

Windows Build Requirements

  • LLVM 18.1.8 (NOT 22+), set LIBCLANG_PATH="C:/Program Files/LLVM/bin"
  • Vulkan SDK, set VULKAN_SDK env var
  • CMake in PATH
  • Rust/Cargo in PATH
  • transcribe-rs pinned to =0.2.8 (0.2.9 has compatibility issues)