Toak/DAEMON_PLAN.md

Toak: Client-Server & PipeWire Architecture Specification

This document outlines the transition of Toak from a monolithic, ephemeral CLI application to a persistent, low-latency background daemon utilizing Linux Inter-Process Communication (IPC) and PipeWire.

1. System Architecture Overview

The system is divided into two distinct binaries to separate the heavy runtime environment from the instant-trigger mechanism.

• Toak Daemon (toakd): A persistent C# background service. It holds the API connections, memory buffers, and audio routing open.
• Toak Client (toak): A lightweight, ephemeral trigger executed by the window manager that simply sends signals to the daemon.

2. The Toak Daemon (Server)

Built as a C# .NET Hosted Service, this component runs continuously in the background and manages three primary responsibilities:

A. Unix Domain Socket Listener

• Listens on a secure, user-space socket (e.g., /run/user/1000/toak.sock).
• Awaits basic byte-sized instructions from the client (e.g., START_RECORDING, STOP_RECORDING, ABORT).
• Ensures single-instance execution and rejects unauthorized cross-user connections.

B. PipeWire Audio Node

• Connects to the PipeWire graph as a native audio sink.
• Dynamically links to the default system microphone only upon receiving the START_RECORDING signal.
• Reads the audio stream directly into a pre-allocated C# MemoryStream via memory-mapped buffers (zero-copy), requesting the exact format required by the Groq Whisper API (e.g., 16kHz, mono).
• Unlinks from the microphone instantly upon receiving the STOP_RECORDING signal, freeing the hardware device.

C. State & API Management

• Maintains a persistent HttpClient connection pool to Groq, eliminating TLS handshake overhead for each dictation.
• Triggers the Wayland (wtype) or X11 (xdotool) typing backend as a child process once the refined transcription is returned.

3. The Toak Client (Trigger)

A minimal executable designed to be fired by global window manager hotkeys (e.g., Sway, Hyprland, KDE).

• Stateless: Contains no audio logic, API keys, or large library dependencies.
• Execution: Connects to the daemon's Unix socket, writes a specific control byte, and exits immediately.
• Latency: Execution time is measured in microseconds, preventing any blocking of the desktop compositor's input thread.

4. Deployment & Lifecycle Management

The daemon is managed by the host's native init system to ensure uptime and clean restarts.

• Systemd User Service: Installed as ~/.config/systemd/user/toak.service.
• Lifecycle: Starts automatically on user login (default.target), restarts automatically on failure, and manages its own logging via journalctl.
• Environment: Inherits the active Wayland/X11 display variables necessary for the typing backends to inject keystrokes into the active window.

5. Execution Flow (The PTT Lifecycle)

1. Init: User logs in. Systemd starts toakd. It allocates memory, opens API connections, and begins listening on the Unix socket.
2. KeyDown: User holds the Push-to-Talk hotkey. Window manager executes toak --start.
3. Link: toakd receives the signal over the socket and tells PipeWire to link the microphone to its internal buffer.
4. Dictation: User speaks. Audio fills the C# MemoryStream.
5. KeyUp: User releases the hotkey. Window manager executes toak --stop.
6. Unlink & Send: toakd unlinks the microphone, flushes the memory buffer directly to the Groq API, receives the transcription, and executes the typing backend.