Overview

Relevant source files

• .github/actions/pnpm_install/action.yaml
• Cargo.lock
• Cargo.toml
• apps/desktop/package.json
• apps/desktop/src-tauri/Cargo.toml
• apps/desktop/src-tauri/capabilities/default.json
• apps/desktop/src-tauri/src/lib.rs
• apps/desktop/src-tauri/tauri.conf.json
• package.json
• packages/obsidian/package.json
• packages/tiptap/package.json
• packages/ui/package.json
• packages/utils/package.json
• pnpm-lock.yaml

Hyprnote is a local-first desktop application for audio recording, real-time transcription, and AI-enhanced note-taking. Built with Tauri (Rust backend) and React (TypeScript frontend), it emphasizes privacy and offline capability while maintaining cloud service fallbacks for enhanced functionality.

Local-First Architecture Philosophy

Hyprnote's architecture prioritizes local processing with optional cloud enhancement:

Capability	Local Implementation	Cloud Fallback
Speech-to-Text	whisper-local (Whisper models), hypr-am2 (Argmax models)	Deepgram, AssemblyAI, Azure, AWS via transcribe-proxy
LLM Processing	hypr-llama (llama.cpp integration)	OpenAI, Anthropic, Google via AI SDK providers
Audio Processing	hypr-audio (cpal/WASAPI/CoreAudio)	N/A (always local)
Data Storage	tauri-plugin-db2 (libsql), filesystem JSON/Markdown	Turso remote sync (optional)
Model Management	hypr-am (HuggingFace Hub downloads)	N/A (models cached locally)

This architecture ensures the application remains functional without internet connectivity while allowing users to leverage cloud services for improved accuracy or performance when available.

Sources: Cargo.toml36-109 apps/desktop/src-tauri/Cargo.toml22-76

Page Organization

This overview introduces Hyprnote's structure and capabilities. For subsystem details:

• System architecture and plugin design: Architecture
• Cross-platform audio capture and STT: Audio and Speech Processing
• Local and remote LLM integration: AI and Language Models
• React frontend and state management: User Interface
• Data persistence strategies: Data Persistence
• Third-party integrations: External Integrations
• CI/CD and release management: Development and Deployment

Repository Structure

The Hyprnote monorepo uses dual workspace systems:

• Rust: Cargo.toml10-18 defines workspace members for apps/*, crates/*, and plugins/*
• TypeScript: package.json1-24 root with pnpm workspaces linking frontend packages

Workspace Organization

Workspace Member Counts:

• Apps: 6 deliverable applications
• Crates: 60+ Rust libraries (audio processing, ML inference, utilities)
• Plugins: 40+ Tauri plugins (system integration, business logic)
• Packages: 10+ TypeScript shared packages (UI, state, utilities)

Sources: Cargo.toml10-33 package.json1-24 pnpm-lock.yaml1-50

Desktop Application Architecture

The desktop application (apps/desktop/) is the primary deliverable. The Rust backend compiles to hyprnote_desktop_lib as both staticlib and rlib (apps/desktop/src-tauri/Cargo.toml10-17), providing a plugin-based architecture with 40+ extensibility points.

Binary Structure and Entry Points

Main Application Flow:

Key Code Entities:

• Entry: apps/desktop/src-tauri/src/lib.rs14-277
• CLI handling: apps/desktop/src-tauri/src/lib.rs18-25
• Supervisor spawn: apps/desktop/src-tauri/src/lib.rs29-33
• Plugin chain: apps/desktop/src-tauri/src/lib.rs69-150
• Setup callback: apps/desktop/src-tauri/src/lib.rs169-212
• Event loop: apps/desktop/src-tauri/src/lib.rs256-276

Sources: apps/desktop/src-tauri/src/lib.rs1-310 apps/desktop/src-tauri/Cargo.toml1-103

Technology Stack Layers

Sources: apps/desktop/package.json17-129 apps/desktop/src-tauri/Cargo.toml22-88 Cargo.toml116-273

Frontend-Backend Communication Pattern

The application uses tauri-specta for type-safe IPC:

Type Generation Test:

Command Registration:

Frontend Usage:

Sources: apps/desktop/src-tauri/src/lib.rs311-349 Cargo.toml265-267

Plugin System and Extension Traits

The desktop application organizes functionality into modular plugins. Each plugin follows the Tauri plugin pattern and may expose extension traits for type-safe access.

Plugin Categories:

Category	Plugins	Primary Traits/Types
Core Infrastructure	db2, store2, auth, path2	Database2PluginExt, Store2PluginExt, Path2PluginExt
Audio/AI Processing	listener, listener2, local-stt, network	ListenerState, ModelStatus, session actors
Window Management	windows, overlay, tray	AppWindow enum, WindowsPluginExt
Integrations	apple-calendar, apple-contact, importer	Platform-specific commands
Utilities	notification, dialog, shell, fs-sync	Native OS features
Development	tracing, hooks, detect	Debugging and diagnostics

Plugin Registration Pattern:

Extension Trait Pattern (Store2 Example):

Sources: apps/desktop/src-tauri/Cargo.toml22-76 apps/desktop/src-tauri/src/lib.rs69-150 Cargo.toml136-173

Companion Services

The repository includes three companion services that support the desktop application:

Web Application (Marketing and Documentation)

apps/web/ - TanStack Start site for public-facing content:

Component	Technology	Purpose
Framework	TanStack Start + React 19	SSR and static generation
Routing	@tanstack/react-router file-based	Type-safe navigation
Styling	Tailwind CSS 4 via @tailwindcss/vite	Utility-first CSS
Content	MDX with content-collections	Documentation pages
Authentication	@supabase/ssr + Supabase Auth	User login/signup
Deployment	@netlify/vite-plugin-tanstack-start	Netlify Edge Functions

Sources: apps/web/package.json1-91 pnpm-lock.yaml753-829

API Server (Backend Services)

apps/api/ - Hono server on Bun runtime:

Service Architecture:

Dependencies:

• Framework: [email protected], @hono/[email protected]
• Validation: [email protected], [email protected]
• Database: [email protected], @types/[email protected]
• AI: @posthog/[email protected], [email protected]
• Payments: [email protected], @supabase/[email protected]

Sources: apps/api/package.json45-106 pnpm-lock.yaml45-119

Bot (GitHub Automation)

apps/bot/ - Probot-based GitHub integration for CI/CD automation, issue triage, and release management.

Sources: apps/bot/package.json1-24 pnpm-lock.yaml121-150

Core Dependencies and Technology Choices

Rust Workspace Dependencies

The Cargo.toml35-302 workspace section defines shared dependencies for all crates and plugins:

Framework and Runtime:

• Tauri: tauri = "2.9" - Desktop application framework with IPC layer
• Tauri Plugins: tauri-plugin = "2.5" - Plugin development kit
• Async Runtime: tokio = "1" with multi-threaded runtime and macros
• Actor System: ractor = "0.14.3", ractor-supervisor = "0.1.9" - Fault-tolerant concurrency

Audio Processing Stack:

• Cross-platform I/O: cpal = "0.15.3" (patched from RustAudio/cpal#51c3b43)
• Playback: rodio = "0.21" - Audio playback library
• DSP: dasp = "0.11.0" with interpolate and interpolate-linear features
• Platform-specific: cidre = "0.11.4" (macOS CoreAudio FFI)

ML Inference:

• Speech-to-Text: Custom Whisper implementation via candle-core
• LLM: llama.cpp integration via FFI wrapper in hypr-llama
• VAD: silero-rs (git: emotechlab/silero-rs@26a6460)

HTTP and Networking:

• Client: reqwest = "0.12" with middleware and streaming support
• Middleware: reqwest-middleware = "0.4", reqwest-tracing = "0.5"
• Streams: reqwest-streams = "0.10.0" for SSE support
• WebSocket: tokio-tungstenite = "0.26.0"

Data Management:

• Database: libsql = "0.9.24" - Turso/SQLite client
• Serialization: serde = "1", serde_json = "1", serde_yaml = "0.9"
• Validation: jsonschema = "0.29", schemars = "0.8.21"

Type Safety and Code Generation:

• IPC Types: specta = "2.0.0-rc.22", tauri-specta = "2.0.0-rc.21"
• TypeScript: specta-typescript = "0.0.9" for .ts generation

Platform Integration (macOS):

• Objective-C: objc2 = "0.6", block2 = "0.6"
• Frameworks: objc2-app-kit = "0.3", objc2-foundation = "0.3", objc2-event-kit = "0.3"
• Swift: swift-rs (git: yujonglee/swift-rs@41a1605)

Sources: Cargo.toml116-302 Cargo.lock1-100

TypeScript Workspace Dependencies

The pnpm workspace pnpm-lock.yaml1-50 manages shared frontend dependencies:

Core Framework:

• React: [email protected], [email protected] - Latest stable release
• Routing: @tanstack/[email protected] - File-based, type-safe routing
• Build: [email protected] - Fast development server and bundler

State Management:

• Global State: [email protected] - Minimal store for UI state
• Reactive State: [email protected] - Reactive database for sessions/transcripts/chats
• XState: [email protected], @xstate/[email protected] - FSM for complex workflows

Data Fetching:

• Query: @tanstack/[email protected] - Server state management
• Forms: @tanstack/[email protected] - Type-safe form handling

AI Integration:

• Vercel AI SDK: [email protected] - Unified AI provider interface
• Providers: @ai-sdk/[email protected], @ai-sdk/[email protected], @ai-sdk/[email protected]
• React Hooks: @ai-sdk/[email protected] - useChat, useCompletion

UI Components:

• Design System: @hypr/ui (workspace package) - Radix UI + Tailwind
• Icons: [email protected], @iconify-icon/[email protected]
• Animation: [email protected] - Motion One for web

Rich Text Editing:

• Editor: @hypr/tiptap (workspace package) - TipTap + CodeMirror extensions
• Code Editor: @uiw/[email protected] - CodeMirror 6 wrapper

Tauri Integration:

• API: @tauri-apps/[email protected] - Core Tauri functions
• Plugins: @tauri-apps/plugin-* - Native capabilities (fs, http, shell, etc.)
• Type Gen: Generated bindings in apps/desktop/src/types/tauri.gen.ts

Utilities:

• Date: [email protected] - Date formatting and manipulation
• Validation: [email protected] - TypeScript-first schema validation
• Effect: [email protected] - Functional programming utilities

Sources: pnpm-lock.yaml195-533 apps/desktop/package.json17-129 packages/ui/package.json19-51

Core Capabilities

Real-Time Audio Capture and Transcription

The application captures system audio and microphone input simultaneously using platform-specific APIs, processes the streams through AGC/AEC/VAD, and dispatches to STT engines:

Audio Flow:

Platform-Specific Audio Implementations:

• macOS: cidre bindings for CoreAudio tap with lock-free ring buffer
• Windows: WASAPI loopback with AudioCaptureClient event-driven capture
• Linux: PulseAudio monitor sources with threaded mainloop

For detailed audio system architecture, see Audio System.

Sources: Cargo.toml44-280 [crates/audio/]

Local-First AI Processing

The application supports running AI models entirely on-device for privacy and offline capability:

Local Model Integration:

GPU Acceleration:

• Metal (macOS): Candle Metal backend for Whisper inference
• CUDA (Windows/Linux): Optional CUDA support for llama.cpp
• CPU Fallback: Automatic degradation to CPU inference when GPU unavailable

For AI model details, see Local LLM System and Local STT Plugin.

Sources: Cargo.toml36-109 [crates/whisper-local/], [crates/llama/], [crates/am/]

Reactive Data Layer with Multi-Table Persistence

The frontend uses TinyBase as a reactive in-memory database with custom persisters that sync to filesystem:

State Architecture:

Persistence Patterns:

• Session Data: Directory structure with _session.json, _transcript.json, note.md
• Chat Data: Directory structure with _chat.json, _messages.json
• Settings: Key-value store via StoreKey enum in tauri-plugin-store2

For data persistence details, see TinyBase and Persisters.

Sources: [packages/store/], apps/desktop/package.json121

Development Workflow

Build System Integration

The monorepo coordinates TypeScript and Rust builds through workspace-level scripts and per-app build configurations:

Desktop Application Build Flow:

Build Scripts:

Tauri Configuration:

Sources: apps/desktop/package.json6-15 apps/desktop/src-tauri/tauri.conf.json6-11 .github/actions/pnpm_install/action.yaml1-14

CI/CD Pipeline Organization

The repository uses GitHub Actions workflows with Graphite optimizer for efficient CI:

Workflow	Trigger	Purpose
desktop_ci.yaml	PR, push to main	Rust tests, TypeScript tests, multi-platform checks
desktop_cd.yaml	Manual, tags	Multi-platform builds, CrabNebula upload, GitHub releases
web_ci.yaml	PR, push to main	Playwright tests, build verification
web_cd.yaml	Push to main	Deploy to Netlify Edge
api_ci.yaml	PR, push to main	Bun tests, API contract validation
api_cd.yaml	Push to main	Deploy to production

CI Optimization: Graphite CI optimizer skips redundant jobs on stacked PRs, reducing CI time by up to 70%.

For detailed CI/CD, see CI Pipeline and Desktop CD and Release.

Sources: [.github/workflows/], documentation from Diagram 5

Platform-Specific Builds

The desktop application compiles for three platforms with distinct toolchains and dependencies:

Platform	Targets	Audio Backend	Build Requirements
macOS	aarch64-apple-darwin x86_64-apple-darwin	CoreAudio via cidre	Xcode, Apple Developer signing
Windows	x86_64-pc-windows-msvc	WASAPI via windows	Visual Studio 2022, Windows SDK
Linux	x86_64-unknown-linux-gnu	PulseAudio via libpulse-binding	ALSA/PulseAudio dev packages

Sidecar Binaries: Local STT and LLM models run as sidecar processes, built separately for each platform and bundled with the main application. Sidecar processes are managed by hypr-host::kill_processes_by_matcher(ProcessMatcher::Sidecar) on app exit.

Sources: Cargo.toml269-305 apps/desktop/src-tauri/src/lib.rs273

Type Safety Enforcement

The codebase enforces end-to-end type safety from Rust backend to TypeScript frontend:

Type Generation Workflow:

Implementation:

Sources: apps/desktop/src-tauri/src/lib.rs329-349 Cargo.toml265-267

Application Configuration

Desktop Application Settings

The desktop app configuration is defined in apps/desktop/src-tauri/tauri.conf.json1-70:

Key Settings:

• Product Name: "Hyprnote Dev" (dev build), "Hyprnote" (production)
• Identifier: com.hyprnote.dev for dev, com.hyprnote.app for production
• macOS Private API: Enabled for enhanced macOS integration
• Deep Link: Custom URL scheme hyprnote:// for external integrations
• Minimum macOS: 14.2 (Sonoma) required for modern APIs

Sources: apps/desktop/src-tauri/tauri.conf.json1-70

Capabilities and Permissions

Fine-grained permissions are defined in apps/desktop/src-tauri/capabilities/default.json1-290:

File System Permissions:

• Read/write access to $DATA/hyprnote/**/* (user data directory)
• Read/write access to $APPDATA/**/* (application data)
• Read access to /Applications/* (macOS app detection)

Network Permissions:

• HTTP/HTTPS to any domain via http:default
• Localhost connections for local AI servers

Shell Permissions:

• Command execution via shell:allow-execute with validator regex
• Script execution: sh -c {command} with argument validation

Plugin Permissions: Each plugin exposes a {plugin}:default permission set that grants access to its commands and events.

Sources: apps/desktop/src-tauri/capabilities/default.json1-290

Configuration

Desktop Application

The desktop app is configured via apps/desktop/src-tauri/tauri.conf.json1-89:

Capabilities and Permissions

The application defines granular permissions in apps/desktop/src-tauri/capabilities/default.json1-184:

• Core window management permissions
• File system access to $DATA/hyprnote/**/*
• HTTP requests to localhost and HTTPS domains
• Shell command execution with validation
• Plugin-specific permissions for all registered plugins

Sources: apps/desktop/src-tauri/tauri.conf.json1-89 apps/desktop/src-tauri/capabilities/default.json1-184