Architecture Diagrams¶

The same YazSes subsystem architecture, shipped in three formats so you can read it wherever you are:

Format	File	Best for
Mermaid	`yazses-architecture.mmd`	Rendered on GitHub / Mermaid Live Editor; embedded below
ASCII	`yazses-architecture.txt`	Terminals, code review, and the master reference PDF
HTML	`yazses-architecture.html`	A styled, self-contained page you can open in any browser (no internet needed)

For the narrative explanation of each subsystem, see the Architecture page.

Mermaid¶

flowchart TB
  subgraph UI["User-facing control"]
    CLI["yazses CLI (44 cmds, 6 panels)"]
    TRAY["yazses-tray (macOS/Windows)"]
  end
  UI -->|"JSON-RPC 2.0 · Unix socket / named pipe"| IPC[["IPC server (ipc/)"]]
  IPC --> DAEMON

  subgraph DAEMON["yazses-daemon — orchestrator (core/daemon.py)"]
    direction TB
    HK["1 · Hotkey — keyboard OR EMG (USB serial)"]
    AUD["2 · Audio — recorder → VAD → padding"]
    STT["3 · STT — faster-whisper (int8) · streaming · disfluency"]
    PP["4 · Post-process — cleaner · voice-punct · spacing · LLM cleanup"]
    CMD["5 · Commands — Tier1 grammar · Tier2 SLM router · LSP"]
    DIS{"6 · dispatch()"}
    HK --> AUD --> STT --> PP --> CMD --> DIS
  end

  CFG[("config.toml · config.py")]
  FEAT[("features.py — 135 capabilities")]
  CFG -. reads .-> DAEMON
  FEAT -. drives .-> CLI

  DIS -->|dictate| INJ["Injector — ydotool/xdotool/wtype/clipboard"]
  DIS -->|command| KEYS["Key sequence — ctrl+z, ctrl+s, …"]
  INJ --> APP["Focused app (local)"]
  KEYS --> APP
  INJ -. "SSH tunnel (remote/)" .-> AGENT["yazses-agent (remote host)"]

  subgraph PLAT["Platform abstraction — Protocols (platform/base.py)"]
    direction LR
    LNX["linux"]
    MAC["macos"]
    WIN["windows"]
    EMG["emg"]
  end
  PLAT -. implements .-> DAEMON

  subgraph OPT["Opt-in — OFF by default, deps behind extras"]
    direction LR
    LEARN["Learning loop — crypto · store · tune"]
    V2["v2 cognitive — voiceprint · gaze · personalize · polyglot · cocktail"]
    RECIMP["Recording import — yazses transcribe"]
  end
  DAEMON -. optional .-> LEARN
  DAEMON -. optional .-> V2
  CLI -. optional .-> RECIMP

ASCII¶

YazSes — Subsystem Architecture (ASCII)
=======================================
Same diagram as yazses-architecture.mmd (Mermaid) and .html (browser). Plain
ASCII so it renders in any terminal, code review, or the master reference PDF.

                        ┌───────────────────────────────────────┐
   USER-FACING CONTROL  │   yazses CLI            yazses-tray     │
                        │   (44 cmds, 6 panels)   (macOS/Windows) │
                        └───────────────────┬───────────────────┘
                                            │  JSON-RPC 2.0 (newline-delimited)
                                            │  Unix socket / Windows named pipe
                                            ▼
                                   ┌──────────────────┐
                                   │  IPC server      │  (ipc/)
                                   └────────┬─────────┘
                                            ▼
 ┌──────────────────────────────────────────────────────────────────────────────┐
 │  yazses-daemon — orchestrator (core/daemon.py)                                 │
 │                                                                                │
 │   [1] HOTKEY        keyboard hook  OR  EMG muscle-sensor (USB serial / BLE)    │
 │        │                                                                       │
 │        ▼                                                                       │
 │   [2] AUDIO         recorder ──► VAD gate (calibrated) ──► pre-speech padding  │
 │        │                                                                       │
 │        ▼                                                                       │
 │   [3] STT           faster-whisper (CPU int8) · streaming decode ·             │
 │        │            disfluency filter        ◄── initial_prompt (vocab/LSP)    │
 │        ▼                                                                       │
 │   [4] POST-PROCESS  cleaner · voice-punctuation · continuation spacing ·       │
 │        │            optional offline LLM cleanup                               │
 │        ▼                                                                       │
 │   [5] COMMANDS      Tier-1 regex grammar ─► (low conf) ─► Tier-2 SLM router    │
 │        │            LSP context provider                                       │
 │        ▼                                                                       │
 │   [6] dispatch() ───────────────┬───────────────────────────┐                 │
 │        │ dictate                │ command                                     │
 └────────┼────────────────────────┼──────────────────────────────────────────────┘
          ▼                        ▼
 ┌──────────────────────┐   ┌────────────────────┐
 │ INJECTOR (inject/)   │   │ KEY SEQUENCE       │   ctrl+z · ctrl+s · arrows …
 │ auto → ydotool /     │   └─────────┬──────────┘
 │ xdotool / wtype /    │             │
 │ clipboard            │             ▼
 └───────┬──────────┬───┘   ┌────────────────────────────┐
         │          │       │  Focused application (local)│
         │          └──────►│                            │
         │  SSH reverse      └────────────────────────────┘
         │  tunnel (remote/)
         ▼
 ┌────────────────────────┐
 │ yazses-agent           │   text-only injection on a remote host
 │ (remote host)          │   (audio never leaves the local machine)
 └────────────────────────┘

 ── Cross-cutting ────────────────────────────────────────────────────────────────
 CONFIG        config.toml / config.py  ── every section has defaults ──► daemon
 FEATURES      system/features.py — 135 capabilities (9 categories) ──► CLI
 PLATFORM      platform/base.py Protocols  →  linux · macos · windows · emg
               (HotkeyBackend · InjectorBackend · LifecycleBackend ·
                IpcServer/Client · PermissionsBackend · TrayBackend)

 ── Opt-in subsystems (OFF by default; heavy deps behind install extras) ──────────
 LEARNING      learning/  — crypto · encrypted SQLite corpus · analysis · `yazses tune`
 v2 COGNITIVE  voiceprint · gaze · personalize · polyglot · cocktail
 REC IMPORT    recimport/ — `yazses transcribe <file>` · speaker diarization

The ASCII block above is included verbatim from yazses-architecture.txt.