56 lines
3.5 KiB
Markdown
56 lines
3.5 KiB
Markdown
# Toak Project Structure
|
|
|
|
This document outlines the high-level architecture and directory structure of the Toak project to help contributors navigate the codebase.
|
|
|
|
## Overview
|
|
|
|
Toak is designed as a fast, Linux-native dictation application utilizing C# AOT (Ahead-Of-Time compilation) for minimal latency. It operates primarily as a client-daemon architecture where background application state is managed by a daemon process while short-lived CLI commands issue control messages via Unix domain sockets.
|
|
|
|
## Directory Structure
|
|
|
|
```text
|
|
Toak/
|
|
├── Api/
|
|
│ ├── GroqApiClient.cs # Client for external transcription and LLM API calls (Groq/Whisper)
|
|
│ └── Models/ # API payload representations
|
|
├── Assets/ # Sound files or other static resources
|
|
├── Audio/
|
|
│ └── AudioRecorder.cs # Handles audio capture via system utilities (e.g., pw-record from PipeWire)
|
|
├── Commands/
|
|
│ ├── ToggleCommand.cs # Start/stop recording and pass pipe/copy flags
|
|
│ ├── DiscardCommand.cs # Abort the current recording
|
|
│ ├── OnboardCommand.cs # Initial interactive configuration setup
|
|
│ ├── ConfigUpdaterCommand.cs # Direct configuration modifications
|
|
│ ├── ShowCommand.cs # Display current configuration
|
|
│ └── LatencyTestCommand.cs # Benchmark tool for API calls
|
|
├── Configuration/
|
|
│ ├── ConfigManager.cs # Loads and saves JSON configuration from the user's home folder
|
|
│ └── ToakConfig.cs # Data model for user preferences
|
|
├── Core/
|
|
│ ├── DaemonService.cs # The background daemon maintaining the socket server and handling states
|
|
│ ├── Logger.cs # Logging utility (verbose logging)
|
|
│ ├── PromptBuilder.cs # Constructs the system prompts for the LLM based on user settings
|
|
│ ├── StateTracker.cs # Tracks the current application state (e.g. is recording active?)
|
|
│ └── Skills/ # Modular capabilities (e.g., Terminal mode, Language Translation)
|
|
├── IO/
|
|
│ ├── ClipboardManager.cs # Cross-session (Wayland/X11) clipboard manipulation (`wl-copy`, `xclip`)
|
|
│ ├── TextInjector.cs # Native keyboard injection handling (`wtype`, `xdotool`)
|
|
│ └── Notifications.cs # System notifications (`notify-send`) and sound playback (`paplay`)
|
|
├── Serialization/
|
|
│ └── AppJsonSerializerContext.cs # System.Text.Json source generation context for AOT support
|
|
├── docs/ # Documentation
|
|
├── toak.service # systemd user service file to run the daemon automatically
|
|
└── Program.cs # Application entry point using System.CommandLine
|
|
```
|
|
|
|
## Key Architectural Concepts
|
|
|
|
### The Daemon Process
|
|
The `DaemonService` (`toak daemon`) is the heart of Toak. It listens on a Unix domain socket for IPC messages. This allows `toak toggle` to execute almost instantaneously, delegating all heavy lifting and state management to an already-hot background process.
|
|
|
|
### Unix Sockets IPC
|
|
Client commands communicate with the daemon via Unix sockets. For details on the byte payloads used for communication, please refer to [PROTOCOL.md](./PROTOCOL.md).
|
|
|
|
### AOT Compilation
|
|
The project relies on Native AOT compilation (`dotnet publish -c Release -r linux-x64 --aot`) to avoid JIT-startup time on CLI executions, making `toak toggle` fast enough to bind seamlessly to hotkeys.
|