Skip to content

Project Structure

Navigate Yap's Go backend, React frontend, platform integrations, model download manager, diagnostics, and release packaging.

This map was reviewed against v0.5.0, including the Models Library, transcription-file saving, and macOS distribution improvements; see release status.

Entry points

main.go starts Wails, logging, crash handling, and the system tray. app.go coordinates configuration, model downloads, recording, transcription, history, and the public methods bound to the frontend. app_diagnostics.go exposes diagnostics paths.

app_transcription_output.go owns the output-folder picker, write-access validation, automatic text-file creation, and the separate transcriptionOutputError state field.

Backend packages

PackageResponsibility
internal/audioPortAudio capture and WAV encoding
internal/hotkeymacOS, Windows, and Linux X11 key handling; platform labels
internal/modelsCatalog, config, download lifecycle, model-file validation, usage statistics
internal/pathsPlatform data directory and development override
internal/transcribeLocal persistent Whisper worker, CLI fallback, OpenAI, process lifecycle
internal/overlayNative macOS/Windows recording overlays and other-platform fallback
internal/systemClipboard, paste, permissions, file reveal, Windows console handling
internal/soundsRecording feedback, including Windows WAV playback
internal/trayMenu bar/system tray integration
internal/loggerDated logs and redaction
internal/crashlogPanic/stderr capture and session-lifecycle diagnostics
internal/proctestHelpers for subprocess tests

The model catalog lives in internal/models/catalog.go; do not maintain a second list in the UI. downloads.go owns one cancellable download at a time, while manager.go handles files and validation.

Frontend

frontend/
  src/
    main.tsx                 React entry
    StartupGate.tsx          Wait for backend startup before mounting App
    App.tsx                  Navigation, Home, Settings, History
    Onboarding.tsx           Permissions and first model setup
    ModelsLibrary.tsx        Search, filters, model details and actions
    modelTypes.ts            Shared model/download types and labels
    useModelDownload.ts      Initial state plus download event subscription
    hotkeyLabels.ts          Platform-specific key text
    RecordingOverlay.tsx    Web fallback overlay
  wailsjs/                   Generated Go bindings and runtime helpers

Bindings are under frontend/wailsjs, not frontend/src/wailsjs. React 18, TypeScript, and Vite power the frontend; Vitest and Testing Library cover the browser-side behavior.

Recording flow

  1. A global key or frontend action calls the Go application.
  2. Readiness checks gate recording, then PortAudio captures audio.
  3. Stop sends the recording to the chosen local or OpenAI engine.
  4. The backend stores the result and audio reference, updates stats, and copies/optionally pastes the text.
  5. If enabled, the backend writes an independent transcription text file. Write failures populate transcriptionOutputError without failing the transcription.
  6. Wails events refresh frontend state and history.

Clipboard/paste work belongs to the backend, not React. Model downloads have a separate lifecycle exposed by GetModelDownloadState and modelDownloadState.

Builds and tests

build/ contains platform assets, installer definitions, and generated bin/ output. .github/workflows/release.yml defines actual package contents and runtime smoke checks. scripts/ci/ contains macOS runtime build/bundle scripts; scripts/windows-startup-smoke.ps1 checks Windows startup.

Use the build guide for pinned versions and API reference for frontend integration.