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
| Package | Responsibility |
|---|---|
internal/audio | PortAudio capture and WAV encoding |
internal/hotkey | macOS, Windows, and Linux X11 key handling; platform labels |
internal/models | Catalog, config, download lifecycle, model-file validation, usage statistics |
internal/paths | Platform data directory and development override |
internal/transcribe | Local persistent Whisper worker, CLI fallback, OpenAI, process lifecycle |
internal/overlay | Native macOS/Windows recording overlays and other-platform fallback |
internal/system | Clipboard, paste, permissions, file reveal, Windows console handling |
internal/sounds | Recording feedback, including Windows WAV playback |
internal/tray | Menu bar/system tray integration |
internal/logger | Dated logs and redaction |
internal/crashlog | Panic/stderr capture and session-lifecycle diagnostics |
internal/proctest | Helpers 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
- A global key or frontend action calls the Go application.
- Readiness checks gate recording, then PortAudio captures audio.
- Stop sends the recording to the chosen local or OpenAI engine.
- The backend stores the result and audio reference, updates stats, and copies/optionally pastes the text.
- If enabled, the backend writes an independent transcription text file. Write failures populate
transcriptionOutputErrorwithout failing the transcription. - 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.