# fastrepl/hyprnote architecture

> Architecture diagram of the GitHub repository fastrepl/hyprnote, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fastrepl/hyprnote
- Repository: https://github.com/fastrepl/hyprnote

## Overview

##### Project Type and Purpose
- Hyprnote is a local‐first, full‐stack meeting AI notepad with both a web app and a desktop Tauri client.
- It comprises:
– A browser‐based frontend (apps/app) written in Solid/TypeScript/Vite.
– A desktop client (apps/desktop) built with React/TypeScript + Tauri (Rust) for native integrations.
– A Rust backend/server (apps/app/server) offering REST/OpenAPI endpoints.
– A suite of Rust “crates” providing core functionality (audio I/O, AEC, STT, LLM inference, data models, database access).
– A plugin system (plugins/…) enabling extensibility at runtime.
– A collection of UI extensions (extensions/…) rendered in the frontend.
– A client SDK (packages/client), utility libraries (packages/utils, packages/ui), and documentation site (apps/docs).

##### File Structure for Architectural Patterns
- Top‐level “apps”: separates Web, Desktop, Docs, CLI, demo scripts.
- “crates/”: modular Rust libraries—audio pipelines (audio‐utils, aec, stt, whisper), ML inference (llama, pyannote), data storage (db‐core, db‐user), plugins (nango, slack, stripe, listener, etc.).
- “plugins/”: Tauri plugin crates plus JS bindings—each exposes commands/events to the desktop host.
- “extensions/”: React widget packages that the user can install in Hyprnote.
- “packages/”: shared TypeScript libraries (client SDK, TipTap editor wrapper, UI primitives).

##### README for Architectural Insights
- Emphasizes offline AI (Whisper & Llama) and plugin/extension framework.
- Mentions listener plugin providing SessionEvent streams via a Channel abstraction.
- References OpenAPI spec (openapi.gen.json) under apps/app/server/openapi.gen.json.

##### Main Components & Their Interactions
a. Frontends:
– Web UI (apps/app/src)—connects via HTTP/WebSocket to the Rust server.
– Desktop UI (apps/desktop/src)—runs in Tauri, communicates with Rust backend (src-tauri) via Tauri commands and event channels.
b. Backend/API:
– Rust server (apps/app/server/src) implements OpenAPI endpoints, orchestrates crates for audio capture, transcription, summarization.
– Plugins loaded via Tauri’s plugin system (plugins/*), each exposing commands (e.g., listener.subscribe).
c. Core Services/Libraries:
– Audio ingestion & processing (crates/listener, crates/audio, crates/aec, crates/diart).
– STT & ML inference (crates/stt, crates/whisper, crates/llama, crates/pyannote).
– Data persistence (crates/db-core + crates/db-user), backed by a local SQLite or Turso.
– Business logic (session summarization, template rendering via crates/template).
d. External Services (optional):
– Nango connector for third‑party integrations.
– Stripe/Lago for billing.
– Slack, calendar APIs.

##### Architectural Patterns & Design Principles
- Modular plugin architecture (microkernel): host (Tauri) loads plugins at runtime.
- Shared core logic in reusable Rust crates.
- Clear separation of concerns: UI ↔ API ↔ domain libraries ↔ storage.
- Local‐first data (embedded DB) with optional sync connectors.

##### Relationships & Flows
- Frontend → HTTP/WebSocket → Rust Server → Crates → DB/Models
- Desktop UI ↔ Tauri API ↔ Plugins → Native OS / Audio I/O / File System
- Plugins ↔ Core Crates (for STT, storage, network)
- Extensions loaded in UI ↔ SDK ↔ Commands channel to plugins

##### Detail Without Overthinking
- Break out each major crate group (audio, inference, db, template).
- Similar plugins visually, but list a few representative names (listener, auth, s3).
- That frontends share the same API and core crates via SDK / OpenAPI.
- Local model dependencies separately from external integrations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layer 1: User Devices
    subgraph "Layer 1: User Devices"
        direction TB
        WebUI["Web UI (Solid TS)"]:::ui
        DesktopUI["Desktop UI (React + Tauri)"]:::ui
    end

    %% Layer 2: API & Plugin Host
    subgraph "Layer 2: API & Plugin Host"
        direction TB
        HTTPServer["Rust HTTP Server (OpenAPI/REST)"]:::api
        TauriHost["Tauri Plugin Host"]:::api
    end

    %% Layer 3: Core Libraries
    subgraph "Layer 3: Core Libraries"
        direction TB
        subgraph "Audio Pipeline Crates"
            direction TB
            Audio["audio"]:::core
            AudioUtils["audio-utils"]:::core
            AEC["aec"]:::core
            AEC2["aec2"]:::core
            Chunker["chunker"]:::core
            Detect["detect"]:::core
        end
        subgraph "STT & ML Inference Crates"
            direction TB
            STT["stt"]:::core
            Whisper["whisper"]:::core
            Llama["llama"]:::core
            Pyannote["pyannote"]:::core
            ONNX["onnx"]:::core
            GGUF["gguf"]:::core
        end
        subgraph "Data Persistence Crates"
            direction TB
            DBCore["db-core"]:::core
            DBUser["db-user"]:::core
            Turso["turso"]:::core
        end
        Template["template"]:::core
    end

    %% Layer 4: Data Stores & Models
    subgraph "Layer 4: Data Stores & Models"
        direction TB
        SQLite["SQLite Database"]:::data
        ModelFiles["ONNX/Whisper/Llama Models"]:::data
    end

    %% Layer 5: Extensions & SDK
    subgraph "Layer 5: Extensions & SDK"
        direction TB
        UIExtensions["UI Extensions"]:::ext
        ClientSDK["Client SDK"]:::ext
        UIPrimitives["UI Primitives"]:::ext
        UtilsLib["Utility Libraries"]:::ext
        DocsSite["Documentation Site"]:::ext
    end

    %% External Services
    subgraph "External Integrations"
        direction TB
        Nango["Nango Connector"]:::ext
        Stripe["Stripe/Billing"]:::ext
        SlackCal["Slack/Calendar APIs"]:::ext
    end

    %% Connections
    WebUI -->|"HTTP/WebSocket"| HTTPServer
    DesktopUI -->|"Tauri RPC"| TauriHost
    HTTPServer -->|"calls"| Audio & STT & Template & DBCore
    TauriHost -->|"loads"| Audio & STT & Template & DBCore
    Audio --> Detect --> Chunker --> AEC --> AEC2 --> AudioUtils
    STT --> Whisper --> Llama --> Pyannote
    DBCore --> DBUser --> SQLite
    Template --> ModelFiles
    UIExtensions --> WebUI
    ClientSDK --> WebUI
    UIPrimitives --> WebUI
    UtilsLib --> WebUI
    DocsSite --> WebUI
    Nango --> HTTPServer
    Stripe --> HTTPServer
    SlackCal --> HTTPServer

    %% Click Events
    click WebUI "https://github.com/fastrepl/hyprnote/tree/main/apps/app/src"
    click DesktopUI "https://github.com/fastrepl/hyprnote/tree/main/apps/desktop/src"
    click TauriHost "https://github.com/fastrepl/hyprnote/tree/main/apps/desktop/src-tauri"
    click HTTPServer "https://github.com/fastrepl/hyprnote/tree/main/apps/app/server/src"
    click Audio "https://github.com/fastrepl/hyprnote/tree/main/crates/audio"
    click AudioUtils "https://github.com/fastrepl/hyprnote/tree/main/crates/audio-utils"
    click AEC "https://github.com/fastrepl/hyprnote/tree/main/crates/aec"
    click AEC2 "https://github.com/fastrepl/hyprnote/tree/main/crates/aec2"
    click Chunker "https://github.com/fastrepl/hyprnote/tree/main/crates/chunker"
    click Detect "https://github.com/fastrepl/hyprnote/tree/main/crates/detect"
    click STT "https://github.com/fastrepl/hyprnote/tree/main/crates/stt"
    click Whisper "https://github.com/fastrepl/hyprnote/tree/main/crates/whisper"
    click Llama "https://github.com/fastrepl/hyprnote/tree/main/crates/llama"
    click Pyannote "https://github.com/fastrepl/hyprnote/tree/main/crates/pyannote"
    click ONNX "https://github.com/fastrepl/hyprnote/tree/main/crates/onnx"
    click GGUF "https://github.com/fastrepl/hyprnote/tree/main/crates/gguf"
    click DBCore "https://github.com/fastrepl/hyprnote/tree/main/crates/db-core"
    click DBUser "https://github.com/fastrepl/hyprnote/tree/main/crates/db-user"
    click Turso "https://github.com/fastrepl/hyprnote/tree/main/crates/turso"
    click Template "https://github.com/fastrepl/hyprnote/tree/main/crates/template"
    click UIExtensions "https://github.com/fastrepl/hyprnote/tree/main/extensions/"
    click ClientSDK "https://github.com/fastrepl/hyprnote/tree/main/packages/client"
    click UIPrimitives "https://github.com/fastrepl/hyprnote/tree/main/packages/ui"
    click UtilsLib "https://github.com/fastrepl/hyprnote/tree/main/packages/utils"
    click DocsSite "https://github.com/fastrepl/hyprnote/tree/main/apps/docs"

    %% Styles
    classDef ui fill:#D0E6FA,stroke:#0366D6,color:#0366D6
    classDef api fill:#E6F4EA,stroke:#1A7F37,color:#1A7F37
    classDef core fill:#FFE5B4,stroke:#E69138,color:#E69138
    classDef data fill:#F0F0F0,stroke:#909090,color:#909090
    classDef ext fill:#F4E1FF,stroke:#8A2BE2,color:#8A2BE2
```
