Overview

Relevant source files

Hyprnote is a privacy-first AI notepad consisting of a desktop application and web ecosystem. The system enables real-time audio transcription, AI-enhanced note-taking, and extensible workflows through a local-first architecture. The desktop application runs on macOS, Windows, and Linux, leveraging on-device AI models for speech-to-text and language model inference. The web ecosystem provides marketing, documentation, and cloud-based workflows via serverless components.

This page provides an architectural overview of the entire system, covering both desktop and web components, their interactions, and the underlying infrastructure. For detailed information about specific subsystems, see Architecture and its child pages.

Scope: This document covers the high-level system composition, technology stack, and how major components interact. It does not cover implementation details of individual features or subsystems—those are documented in their respective sections.

System Composition

Sources: Cargo.toml11-17 package.json1-19 apps/desktop/package.json1-137 apps/web/package.json1-85 apps/api/package.json1-26 apps/restate/package.json1-26

Technology Stack

Component	Technologies	Primary Purpose
Desktop Frontend	React 19, TanStack Router, TinyBase, Zustand	User interface, state management, routing
Desktop Backend	Rust, Tauri 2.9, ~20 custom plugins	Native capabilities, audio I/O, local AI
Web Frontend	React 19, TanStack Start, Netlify	Marketing site, documentation, web app
Web Backend	Hono, Bun, Supabase, Stripe	API endpoints, authentication, payments
Serverless	Cloudflare Workers, Restate	Durable AI workflows, edge computing
Local AI	Whisper (STT), Llama (LLM), llama.cpp	On-device speech recognition, text generation
Cloud AI	Deepgram, OpenRouter, AWS Transcribe	Cloud-based STT/LLM fallbacks
Data Persistence	TinyBase, libsql, Turso, Supabase	Local/cloud data storage, sync
Build Tools	pnpm workspaces, Cargo workspaces, Vite, Tauri CLI	Monorepo management, bundling

Sources: apps/desktop/package.json17-112 apps/web/package.json13-61 Cargo.toml92-221 pnpm-lock.yaml1-10

Desktop Application Architecture

The desktop application is built with Tauri 2.9, combining a React frontend with a Rust backend. The architecture follows a plugin-based pattern where ~20 plugins extend Tauri's core functionality.

Sources: apps/desktop/src/main.tsx1-110 apps/desktop/src/routes/__root.tsx1-53 apps/desktop/src-tauri/src/lib.rs1-218 apps/desktop/src-tauri/Cargo.toml19-81 Cargo.toml22-85

Initialization Flow

The desktop application initializes through the following sequence:

Backend Initialization (apps/desktop/src-tauri/src/lib.rs12-38):
- main() creates tokio runtime
- Spawns root supervisor for actor management
- Initializes Sentry client for error tracking
Plugin Registration (apps/desktop/src-tauri/src/lib.rs45-106):
- ~20 plugins initialized via .plugin() calls
- Plugin order matters: tauri-plugin-single-instance must be first for deep-linking
- Each plugin exposes Tauri commands to frontend
Frontend Bootstrap (apps/desktop/src/main.tsx39-96):
- App component initializes QueryClient for data fetching
- TinyTickProvider manages background tasks
- TinyBaseProvider wraps reactive state management
- RouterProvider handles routing with injected context
Store Initialization (apps/desktop/src/store/tinybase/main.ts79-159):
- StoreComponent creates MergeableStore with schemas
- localPersister handles SQLite persistence
- localPersister2 handles filesystem persistence (markdown export)
- Transaction listeners track changes for sync

Sources: apps/desktop/src-tauri/src/lib.rs12-189 apps/desktop/src/main.tsx1-110 apps/desktop/src/store/tinybase/main.ts1-370

Web Ecosystem Architecture

The web ecosystem consists of three primary applications deployed independently:

Sources: apps/web/package.json1-85 apps/api/package.json1-26 apps/restate/package.json1-26 apps/web/vite.config.ts1-44

Web Application

The web app (apps/web) uses TanStack Start for SSR and static generation:

Routing: File-based routing in apps/web/src/routes/ with TanStack Router
Content: MDX documentation processed via @content-collections/vite
Styling: Tailwind CSS 4 with @tailwindcss/vite plugin
Deployment: Netlify with @netlify/vite-plugin-tanstack-start
Prerendering: Blog, docs, changelog, legal, product pages (apps/web/vite.config.ts18-32)

API Service

The API service (apps/api) runs on Bun with Hono:

Framework: Hono 4 with Zod validation (@hono/zod-validator)
OpenAPI: hono-openapi generates API documentation
Auth: Supabase client for authentication
Payments: Stripe SDK for subscription management
Documentation: Scalar API reference via @scalar/hono-api-reference

Restate Workers

The Restate service (apps/restate) provides durable execution on Cloudflare Workers:

SDK: @restatedev/restate-sdk-cloudflare-workers for durable workflows
AI Integration: Deepgram SDK for cloud STT, OpenRouter SDK for LLM routing
Validation: @restatedev/restate-sdk-zod for type-safe schemas
Deployment: Wrangler CLI to Cloudflare Workers

Sources: apps/web/vite.config.ts1-44 apps/api/package.json9-19 apps/restate/package.json12-17

AI/ML Infrastructure

Hyprnote's AI capabilities operate in two modes: local (on-device) and cloud (external services).

Sources: Cargo.toml23-82 apps/desktop/package.json17-112 apps/restate/package.json12-17

Local Speech-to-Text

The local STT system supports multiple engines:

Whisper Local (crates/whisper-local): GGML-based Whisper models running in-process
Argmax STT (crates/am): Newer Moonshine models via external sidecar process
owhisper Framework (owhisper/*): Unified interface abstracting multiple backends

The tauri-plugin-local-stt (plugins/local-stt) orchestrates these engines, managing model downloads, health checks, and supervisor patterns for robust operation.

Local Language Models

The local LLM system uses llama.cpp for efficient inference:

Llama Engine (crates/llama): Rust bindings to llama.cpp with GPU acceleration
Model Manager: Downloads and caches GGUF models in ~/.cache/hyprnote/
HTTP Server: OpenAI-compatible API via Axum for /chat/completions endpoint
Grammar Constraints: GBNF support for structured output (crates/gbnf)

The tauri-plugin-local-llm (plugins/local-llm) exposes an HTTP server that desktop app and external tools can use.

Cloud AI Services

Cloud services provide fallback and specialized capabilities:

Deepgram: Cloud speech-to-text via @deepgram/sdk
OpenRouter: LLM routing to multiple providers via @openrouter/sdk
AWS Transcribe: Enterprise STT via aws-sdk-transcribestreaming
AI SDK: Unified interface to 10+ providers via @ai-sdk/* packages

Sources: Cargo.toml22-82 apps/desktop/package.json18-112 apps/restate/package.json12-17

Data Persistence

Hyprnote uses different persistence strategies for desktop and web:

Sources: apps/desktop/src/store/tinybase/main.ts1-370 apps/web/package.json41-65 Cargo.toml38-39

Desktop Data Architecture

TinyBase Store (apps/desktop/src/store/tinybase/main.ts):

Reactive state management with mergeable stores
Dual persistence: SQLite for structured data, filesystem for markdown
BroadcastChannel sync across multiple windows
iframe sync for extension isolation
Schemas defined in @hypr/store package

User Database (crates/db-user):

libsql-based SQLite database
Modular operations: sessions, events, humans, calendars, config
Exposed via tauri-plugin-db2 with generated TypeScript bindings
Separate from TinyBase for persistent user data

Configuration Storage:

Tauri Store for JSON config files (auth.json, etc.)
TinyBase values for runtime config
Environment variables via @t3-oss/env-core

Web Data Architecture

Drizzle ORM (apps/web/package.json41):

Type-safe SQL queries with TypeScript
Supports both Turso and Supabase backends

Turso (crates/turso):

Distributed SQLite for user data
Token caching for authentication
Connection string formatting utilities

Supabase:

PostgreSQL for shared data and auth
Storage for file uploads
Real-time subscriptions

Sources: apps/desktop/src/store/tinybase/main.ts1-370 apps/web/package.json41-65 Cargo.toml38-77

Development Tooling

The monorepo uses coordinated tooling for JavaScript/TypeScript and Rust:

Tool	Purpose	Configuration
pnpm	JavaScript package manager	pnpm-lock.yaml workspaces in package.json14-18
Cargo	Rust package manager	Cargo.toml10-17 workspace members
Taskfile	Task runner	Taskfile.yaml tasks for supabase, stripe, etc.
Vite	Frontend bundler	apps/desktop/vite.config.ts apps/web/vite.config.ts
Tauri CLI	Desktop app builder	apps/desktop/package.json10-14
TypeScript	Type checking	Multiple `tsconfig.json` files per app
dotenvx	Environment variables	.env.sample Taskfile.yaml83-132
Specta	Type generation	Cargo.toml219-221 generates TypeScript bindings

Monorepo Structure

hyprnote/
├── apps/
│   ├── desktop/          # Tauri desktop app
│   ├── web/              # TanStack Start web app
│   ├── api/              # Hono API service
│   ├── restate/          # Cloudflare Workers
│   └── pro/              # MCP server
├── packages/
│   ├── ui/               # Shared UI components
│   ├── tiptap/           # Rich text editor
│   ├── utils/            # Shared utilities
│   ├── store/            # TinyBase schemas
│   └── db/               # Database types
├── plugins/              # ~20 Tauri plugins
├── crates/               # ~50 Rust crates
├── extensions/           # Extension examples
└── owhisper/             # STT framework

Sources: Cargo.toml10-17 pnpm-lock.yaml10-769 package.json1-19 Taskfile.yaml1-282

Build and Deployment

Desktop CI/CD:

Type checking and tests on push/PR
Manual deployment workflow with channel selection (staging/nightly/stable)
Multi-platform builds: macOS (DMG), Linux (AppImage)
Distribution via Crabnebula Cloud, Cloudflare R2, GitHub Releases

Web CI/CD:

Visual regression testing with Playwright/Argos
Automatic deployment to Netlify on merge to main
SSR and static prerendering for docs/blog

API Deployment:

Bun runtime on Fly.io
Webhook handling for Stripe events

Restate Deployment:

Wrangler deployment to Cloudflare Workers
Environment variables from dotenvx

Sources: Taskfile.yaml1-282 apps/web/vite.config.ts1-44 apps/desktop/package.json10-14

Extension System

Hyprnote supports a sandboxed extension system for custom panels:

Sources: apps/desktop/src/extension-globals.ts1-95 apps/desktop/src/store/tinybase/iframe-sync.ts1-175 apps/desktop/src/routes/app/ext-host.tsx1-214 extensions/calendar/extension.json1-18

Extension Architecture

Manifest (extensions/calendar/extension.json):

Defines extension metadata, panels, permissions
Specifies entry points for runtime (main.js) and UI (dist/ui.js)

Runtime Script (extensions/calendar/main.js):

Runs in Deno sandbox with limited permissions
Implements __hypr_extension.activate() and __hypr_extension.deactivate()
Access to hypr.log API for logging

Panel UI (extensions/calendar/ui.tsx):

React component with ExtensionViewProps interface
Rendered in sandboxed iframe at /app/ext-host
Access to window.__hyprnote runtime with React, UI components, TinyBase store

Synchronization:

createIframeSynchronizer() syncs TinyBase state between parent and iframe
createParentSynchronizer() provides iframe-side sync implementation
postMessage protocol with origin validation

Security:

Iframe sandbox attribute: allow-scripts allow-same-origin
Tauri APIs blocked via __TAURI_INTERNALS__ polyfill (apps/desktop/index.html18-35)
Extensions cannot access filesystem or native APIs directly

Sources: apps/desktop/src/extension-globals.ts65-94 apps/desktop/src/store/tinybase/iframe-sync.ts31-175 apps/desktop/src/routes/app/ext-host.tsx1-214 apps/desktop/index.html18-35 extensions/calendar/extension.json1-18 extensions/calendar/main.js1-19 extensions/calendar/ui.tsx1-208