# noncuro/muesli architecture

> Architecture diagram of the GitHub repository noncuro/muesli, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/noncuro/muesli
- Repository: https://github.com/noncuro/muesli

## Overview

##### What this project is (type + purpose)
From the file tree and README, **Muesli** is currently a **very early-stage (WIP) local desktop/tooling project** (not a web app yet) intended to:
- **Capture the last N seconds/minutes of audio** from microphone and/or system audio
- Keep it **locally in-memory** with an **auto-expiring buffer/queue** (privacy principle)
- On-demand **transcribe** the recent audio snippet
- Use an **LLM (gpt-4o)** to **rewrite/complete meeting notes**
- Eventually provide an **autocomplete UX** (tab-to-accept) or shortcuts / popup insertion

- The **target architecture** (what the tool is aiming to become)
- Plus the **current skeleton** (a single Python entrypoint packaged as a tool)

##### Top-level files
- `main.py`: likely **single entrypoint** that will orchestrate capture → buffer → transcribe → LLM → UI insertion.
- `setup.py`: indicates intent to package/install as a Python tool (CLI and/or desktop entrypoint).
- `.idea`, `.DS_Store`: not architectural.
- No `src/`, no tests, no modules yet: architecture is **conceptual** right now.

##### Hotkey / Trigger Listener
- e.g., “capture last 30s–5m”, “transcribe now”, “insert completion”

##### Ring Buffer / Time-window Queue
- stores PCM/audio frames
- enforces retention policy (auto-delete > ~5m)
##### Buffer Manager / Retention Policy
- periodic cleanup
- exposes “get last X seconds”

##### Transcription Service Adapter
- “transcribe(audio_segment) -> text”
##### Transcript Cache (optional)
- short-lived in memory; may help with repeated prompts

##### Notes Input Source
- Later: “current application text context” (harder; depends on OS accessibility APIs)
##### Prompt Builder
- combines:
- existing notes so far
- transcript snippet
- user prompt templates (customizable principle)
##### LLM Client (gpt-4o)
- external dependency
- receives prompt, returns completion / rewrite
##### Completion Post-Processor
- formatting, trimming, safety checks
- handles partial suggestions vs full rewrite

##### Popup UI / Suggestion Panel
- shows suggestion, allows copy/select
##### Text Insertion Layer
- keyboard simulation / accessibility insertion into whatever app is active
##### Autocomplete UI (future)
- inline ghost text + tab accept (requires deeper integration)

##### Config/Prompt Templates
- local config file (not present yet, but planned)
##### Plugin/Adapter Interfaces
- transcription backend, LLM backend, UI mode, hotkey mappings

##### Local Logging + Debug Diagnostics
- Sensitive audio/text isn’t persisted unintentionally

##### Control / policy flows
- **Retention Policy Timer** → **Ring Buffer**
- **Config/Prompts** → **Prompt Builder / Hotkeys / UI**

##### Privacy-first ephemeral data design
- “in-memory ring buffer” is the core differentiator: show it prominently.
##### Adapter/ports-and-adapters (hexagonal)
- Audio capture, transcription backend, LLM backend, and UI insertion should be swappable.
##### Event-driven triggers
- hotkeys and timers trigger actions; audio capture is a stream.
##### Separation of concerns
- /buffering ≠ transcription ≠ LLM prompting ≠ UI/insertion

##### What technologies to label (given what’s known + what’s planned)
You only *know* it’s Python (via `setup.py`, `main.py`). The README mentions **gpt-4o** explicitly.

- **Language/runtime**: Python (local tool)
- **LLM**: OpenAI GPT-4o (external)
- **Hotkeys/UI**: “Hotkey Listener (TBD)”, “Popup UI (TBD)”, “Text insertion (OS accessibility / keyboard events) (TBD)”
This is still accurate: it shows intentional boundaries even if library choices aren’t made.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% Diagram A — Target Architecture (next 3 milestones)
    %% =========================
    subgraph "Diagram A — Target Architecture (Privacy-preserving local pipeline)"
        direction TB

        subgraph "Local Machine (Python tool; no persistence by design)"
            direction TB

            NoteA["Note: Audio stored only in-memory; auto-evicted after ~5m unless user triggers transcription."]:::note

            subgraph "Input / Capture Layer"
                direction TB
                Mic["Audio Capture (Mic)\n(Audio Capture Lib — TBD)"]:::capture
                Sys["Audio Capture (System Audio)\n(Optional; OS-dependent)"]:::capture
                Hotkey["Hotkey / Trigger Listener\n(TBD)"]:::control
            end

            subgraph "Privacy Core — In-memory Buffer"
                direction TB
                Ring[("Ring Buffer / Time-window Queue\n(PCM frames; in-memory only)")]:::datastore
                Retention["Buffer Manager / Retention Policy\n(TTL ~5m; exposes 'get last X seconds')"]:::core
                Timer["Retention Policy Timer"]:::control
            end

            subgraph "Transcription (replaceable adapter)"
                direction TB
                Transcribe["Transcription Service Adapter\ntranscribe(audio)->text\n(Local Whisper or Remote API)"]:::adapter
                TCache[("Transcript Cache (optional; short-lived)")]:::datastore
            end

            subgraph "Notes Context + LLM Completion"
                direction TB
                Notes["Notes Input Source\n(Text box now; app context later)"]:::ui
                Prompt["Prompt Builder\n(notes + transcript + templates)"]:::core
                Config["Config / Prompt Templates\n(local file planned)"]:::config
                LLMClient["LLM Client\n(OpenAI adapter)"]:::adapter
                Post["Completion Post-Processor\n(format/trim/safety)"]:::core
                Plugins["Plugin / Adapter Interfaces\n(transcription/LLM/UI/hotkeys)"]:::config
            end

            subgraph "Output / UX Surface"
                direction TB
                Popup["Popup UI / Suggestion Panel\n(TBD)"]:::ui
                Auto["Autocomplete UI (future)\n(ghost text + tab accept)"]:::ui
                Insert["Text Insertion Layer\n(OS accessibility / keyboard events — TBD)"]:::adapter
                Active["Active Application\n(whatever app is focused)"]:::external
            end

            subgraph "Observability (local-only)"
                direction TB
                Logs["Local Logging + Debug Diagnostics\n(avoid persisting sensitive data)"]:::obs
            end
        end

        subgraph "External Services (Cloud)"
            direction TB
            GPT["OpenAI GPT-4o API"]:::cloud
        end

        %% Primary dataflow (solid)
        Mic -->|"audio_frames (streaming)"| Ring
        Sys -->|"audio_frames (streaming)"| Ring

        Retention -->|"get_last_Xs()"| Ring
        Retention -->|"audio_segment"| Transcribe
        Transcribe -->|"transcript_text"| Prompt
        Transcribe -->|"transcript_text"| TCache
        Notes -->|"notes_so_far / cursor_context"| Prompt
        Prompt -->|"prompt"| LLMClient
        LLMClient -->|"completion"| Post
        Post -->|"suggestion"| Popup
        Post -->|"suggestion"| Auto
        Popup -->|"accepted_text"| Insert
        Auto -->|"accepted_text"| Insert
        Insert -->|"keystrokes / accessibility_insert"| Active

        %% External call
        LLMClient -->|"API_call"| GPT

        %% Control/policy/config flows (dashed)
        Hotkey -.->|"request_last_30s-5m / transcribe_now"| Retention
        Timer -.->|"evict_>5m"| Ring
        Config -.->|"templates + settings"| Prompt
        Config -.->|"hotkeys"| Hotkey
        Config -.->|"UI_settings"| Popup
        Config -.->|"UI_settings"| Auto
        Plugins -.->|"defines_ports"| Transcribe
        Plugins -.->|"defines_ports"| LLMClient
        Plugins -.->|"defines_ports"| Insert

        %% Observability (dashed)
        Hotkey -.->|"diagnostics"| Logs
        Retention -.->|"metrics/debug"| Logs
        Transcribe -.->|"timing/errors"| Logs
        LLMClient -.->|"timing/errors"| Logs
        Post -.->|"debug"| Logs
        Popup -.->|"UI_events"| Logs
        Insert -.->|"insertion_events"| Logs
    end

    %% =========================
    %% Diagram B — Current Implementation (as-is)
    %% =========================
    subgraph "Diagram B — Current Implementation (as-is in repo)"
        direction TB

        subgraph "Repository (very early-stage)"
            direction TB
            Setup["Packaging / Distribution\n(Python tool/CLI setup)"]:::packaging
            Main["main.py\nOrchestrator (currently monolithic)"]:::code
            Readme["README.md\nProject Overview / Intended Architecture"]:::doc
        end

        subgraph "Conceptual components currently collapsed into main.py"
            direction TB
            C1["Capture (mic/system) — TBD"]:::ghost
            C2["In-memory ring buffer + retention — TBD"]:::ghost
            C3["Transcription adapter — TBD"]:::ghost
            C4["Prompt builder + templates — TBD"]:::ghost
            C5["LLM client (gpt-4o) — TBD"]:::ghost
            C6["Post-processing — TBD"]:::ghost
            C7["Popup/autocomplete + insertion — TBD"]:::ghost
        end

        Setup -.->|"installs/entrypoint"| Main
        Readme -.->|"describes_target_architecture"| Main

        Main -->|"will_own"| C1
        Main -->|"will_own"| C2
        Main -->|"will_own"| C3
        Main -->|"will_own"| C4
        Main -->|"will_own"| C5
        Main -->|"will_own"| C6
        Main -->|"will_own"| C7
    end

    %% Click Events (from component_mapping)
    click Main "https://github.com/noncuro/muesli/blob/main/main.py"
    click Setup "https://github.com/noncuro/muesli/blob/main/setup.py"
    click Readme "https://github.com/noncuro/muesli/blob/main/README.md"

    %% Styles
    classDef capture fill:#D6F0FF,stroke:#1D4ED8,stroke-width:1px,color:#0B1B3A
    classDef core fill:#DCFCE7,stroke:#166534,stroke-width:1px,color:#052E16
    classDef datastore fill:#FFE4E6,stroke:#9F1239,stroke-width:1px,color:#3B0A12
    classDef adapter fill:#FEF9C3,stroke:#A16207,stroke-width:1px,color:#422006
    classDef ui fill:#EDE9FE,stroke:#5B21B6,stroke-width:1px,color:#1F1147
    classDef control fill:#E5E7EB,stroke:#374151,stroke-dasharray:4 3,color:#111827
    classDef cloud fill:#E0F2FE,stroke:#0369A1,stroke-width:2px,color:#0B2A3A
    classDef external fill:#F3F4F6,stroke:#6B7280,color:#111827
    classDef obs fill:#FAE8FF,stroke:#A21CAF,color:#3B0764
    classDef config fill:#FFF7ED,stroke:#C2410C,color:#431407
    classDef packaging fill:#FEE2E2,stroke:#B91C1C,color:#450A0A
    classDef code fill:#DBEAFE,stroke:#1E40AF,stroke-width:2px,color:#0B1B3A
    classDef doc fill:#ECFCCB,stroke:#3F6212,color:#1A2E05
    classDef ghost fill:#FFFFFF,stroke:#9CA3AF,stroke-dasharray:3 3,color:#374151
    classDef note fill:#FFFBEB,stroke:#D97706,stroke-width:1px,color:#451A03
```
