# saqlainnnnn/tinyvox architecture

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

- Interactive diagram: https://gitdiagram.com/saqlainnnnn/tinyvox
- Repository: https://github.com/saqlainnnnn/tinyvox

## Overview

#### Purpose and entry points
A Rust workspace for a desktop voice-dictation system: capture audio, transcribe it, optionally clean/validate text, and inject resulting text into the active application. The primary executable is `apps/desktop/src/main.rs`; `apps/desktop/src/bin/tinyvox-dict.rs` is a separate dictionary-oriented CLI/binary.

#### Application orchestration
`crates/engine/src/controller.rs` is the likely central coordinator for dictation lifecycle and processing decisions. Engine state and observable events are separated into `crates/engine/src/state.rs` and `crates/engine/src/event.rs`, with public composition exposed by `crates/engine/src/lib.rs`.

#### Port-and-adapter boundary
The engine defines technology-neutral interfaces for its dependencies under `crates/engine/src/ports/`: audio capture (`audio.rs`), speech-to-text (`stt.rs`), cleanup (`cleanup.rs`), and text injection (`injection.rs`). This boundary lets the desktop application bind platform/service implementations without coupling controller logic to Windows APIs or particular transcription providers.

#### Audio and transcription pipeline
Audio acquisition is implemented as a dedicated crate at `crates/audio/src/lib.rs`. Speech-to-text is supplied by `crates/stt-pulse/src/lib.rs`, with a standalone transcription example at `crates/stt-pulse/examples/transcribe.rs`. The primary flow is audio samples/recording → STT transcript → engine-controlled downstream handling.

#### Transcript cleanup and validation
`crates/cleanup/src/pipeline.rs` composes transcript transformation stages, while `crates/cleanup/src/validation.rs` provides a validation boundary. Multiple cleanup backends are present: local/basic behavior in `crates/cleanup/src/basic.rs`, plus integrations named for Electron, Groq, and Llama in `crates/cleanup/src/electron.rs`, `crates/cleanup/src/groq.rs`, and `crates/cleanup/src/llama.rs`. These represent an important external-service/runtime boundary after transcription and before injection.

#### Commands, dictionaries, and text output
Voice-command interpretation is isolated in `crates/voice-command/src/lib.rs`, enabling recognized phrases to become actions rather than emitted prose. Dictionary domain and persistence are separated in `crates/engine/src/dictionary.rs` and `crates/engine/src/dictionary_store.rs`; the desktop dictionary binary likely manages this data. Final text delivery is performed through the engine injection port and Windows implementation at `crates/win/src/injection.rs`.

#### Platform runtime and infrastructure
The target desktop/platform layer is Windows-focused: `crates/win/src/lib.rs` groups active-window discovery, credential handling, text injection, and overlay support in `foreground.rs`, `credentials.rs`, and `overlay.rs`. Hotkey and injection examples under `crates/win/examples/` indicate OS-level input integration. Rust/Cargo is the material runtime and workspace infrastructure (`Cargo.toml`); prototypes under `prototypes/` are exploratory and outside the primary application path.

Main entry points: [`crates/engine/src/controller.rs`](https://github.com/saqlainnnnn/tinyvox/blob/main/crates/engine/src/controller.rs) (Dictation controller), [`apps/desktop/src/main.rs`](https://github.com/saqlainnnnn/tinyvox/blob/main/apps/desktop/src/main.rs) (Desktop application), [`crates/cleanup/src/pipeline.rs`](https://github.com/saqlainnnnn/tinyvox/blob/main/crates/cleanup/src/pipeline.rs) (Cleanup pipeline), [`crates/stt-pulse/src/lib.rs`](https://github.com/saqlainnnnn/tinyvox/blob/main/crates/stt-pulse/src/lib.rs) (Pulse STT)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop entry points"]
  node_desktop_app["Desktop application<br/>executable<br/>[main.rs]"]
  node_dictionary_cli["Dictionary CLI<br/>executable<br/>[tinyvox-dict.rs]"]
end

subgraph group_engine["Engine"]
  node_engine_api["Engine public API<br/>crate facade<br/>[lib.rs]"]
  node_controller{{"Dictation controller<br/>orchestrator<br/>[controller.rs]"}}
  node_engine_state["Engine state<br/>state model<br/>[state.rs]"]
  node_engine_events["Engine events<br/>event model<br/>[event.rs]"]
  node_audio_port["Audio capture port<br/>engine port<br/>[audio.rs]"]
  node_stt_port["Speech-to-text port<br/>engine port<br/>[stt.rs]"]
  node_cleanup_port["Cleanup port<br/>engine port<br/>[cleanup.rs]"]
  node_injection_port["Text injection port<br/>engine port<br/>[injection.rs]"]
  node_dictionary_domain["Dictionary domain<br/>domain model<br/>[dictionary.rs]"]
  node_dictionary_store[("Dictionary store<br/>persistence")]
end

subgraph group_adapters["Audio, STT &amp; cleanup"]
  node_audio_adapter["Audio capture<br/>adapter crate<br/>[lib.rs]"]
  node_stt_pulse["Pulse STT<br/>transcription adapter<br/>[lib.rs]"]
  node_cleanup_pipeline["Cleanup pipeline<br/>transcript pipeline<br/>[pipeline.rs]"]
  node_cleanup_backends["Cleanup backends<br/>service integrations<br/>[groq.rs]"]
end

subgraph group_windows["Windows platform"]
  node_windows_runtime["Windows runtime<br/>platform crate<br/>[lib.rs]"]
  node_windows_injection["Windows text injection<br/>platform adapter<br/>[injection.rs]"]
end

node_workspace["Cargo workspace<br/>Rust workspace<br/>[Cargo.toml]"]
node_voice_commands["Voice commands<br/>command interpreter<br/>[lib.rs]"]

node_workspace -->|"builds"| node_desktop_app
node_workspace -->|"builds"| node_dictionary_cli
node_desktop_app -->|"uses"| node_engine_api
node_engine_api -->|"exposes"| node_controller
node_controller -->|"updates"| node_engine_state
node_controller -->|"emits"| node_engine_events
node_controller -->|"captures through"| node_audio_port
node_controller -->|"transcribes through"| node_stt_port
node_controller -->|"cleans through"| node_cleanup_port
node_controller -->|"delivers through"| node_injection_port
node_audio_adapter -->|"implements"| node_audio_port
node_stt_pulse -->|"implements"| node_stt_port
node_cleanup_pipeline -->|"implements"| node_cleanup_port
node_cleanup_backends -->|"stages"| node_cleanup_pipeline
node_windows_injection -->|"implements"| node_injection_port
node_windows_runtime -->|"contains"| node_windows_injection
node_stt_pulse -->|"transcript"| node_cleanup_pipeline
node_controller -->|"interprets commands"| node_voice_commands
node_dictionary_cli -->|"manages"| node_dictionary_domain
node_dictionary_domain -->|"persists via"| node_dictionary_store
node_desktop_app -->|"binds platform services"| node_windows_runtime

click node_workspace "https://github.com/saqlainnnnn/tinyvox/blob/main/Cargo.toml"
click node_desktop_app "https://github.com/saqlainnnnn/tinyvox/blob/main/apps/desktop/src/main.rs"
click node_dictionary_cli "https://github.com/saqlainnnnn/tinyvox/blob/main/apps/desktop/src/bin/tinyvox-dict.rs"
click node_engine_api "https://github.com/saqlainnnnn/tinyvox/blob/main/crates/engine/src/lib.rs"
click node_controller "https://github.com/saqlainnnnn/tinyvox/blob/main/crates/engine/src/controller.rs"
click node_engine_state "https://github.com/saqlainnnnn/tinyvox/blob/main/crates/engine/src/state.rs"
click node_engine_events "https://github.com/saqlainnnnn/tinyvox/blob/main/crates/engine/src/event.rs"
click node_audio_port "https://github.com/saqlainnnnn/tinyvox/blob/main/crates/engine/src/ports/audio.rs"
click node_stt_port "https://github.com/saqlainnnnn/tinyvox/blob/main/crates/engine/src/ports/stt.rs"
click node_cleanup_port "https://github.com/saqlainnnnn/tinyvox/blob/main/crates/engine/src/ports/cleanup.rs"
click node_injection_port "https://github.com/saqlainnnnn/tinyvox/blob/main/crates/engine/src/ports/injection.rs"
click node_dictionary_domain "https://github.com/saqlainnnnn/tinyvox/blob/main/crates/engine/src/dictionary.rs"
click node_dictionary_store "https://github.com/saqlainnnnn/tinyvox/blob/main/crates/engine/src/dictionary_store.rs"
click node_voice_commands "https://github.com/saqlainnnnn/tinyvox/blob/main/crates/voice-command/src/lib.rs"
click node_audio_adapter "https://github.com/saqlainnnnn/tinyvox/blob/main/crates/audio/src/lib.rs"
click node_stt_pulse "https://github.com/saqlainnnnn/tinyvox/blob/main/crates/stt-pulse/src/lib.rs"
click node_cleanup_pipeline "https://github.com/saqlainnnnn/tinyvox/blob/main/crates/cleanup/src/pipeline.rs"
click node_cleanup_backends "https://github.com/saqlainnnnn/tinyvox/blob/main/crates/cleanup/src/groq.rs"
click node_windows_runtime "https://github.com/saqlainnnnn/tinyvox/blob/main/crates/win/src/lib.rs"
click node_windows_injection "https://github.com/saqlainnnnn/tinyvox/blob/main/crates/win/src/injection.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_desktop_app,node_dictionary_cli toneBlue
class node_engine_api,node_controller,node_engine_state,node_engine_events,node_audio_port,node_stt_port,node_cleanup_port,node_injection_port,node_dictionary_domain,node_dictionary_store toneAmber
class node_audio_adapter,node_stt_pulse,node_cleanup_pipeline,node_cleanup_backends toneMint
class node_windows_runtime,node_windows_injection toneRose
class node_workspace,node_voice_commands toneNeutral
```

## Components

### Desktop entry points

- [Desktop application](https://github.com/saqlainnnnn/tinyvox/blob/main/apps/desktop/src/main.rs): executable · `apps/desktop/src/main.rs`
- [Dictionary CLI](https://github.com/saqlainnnnn/tinyvox/blob/main/apps/desktop/src/bin/tinyvox-dict.rs): executable · Manages dictionary-oriented workflows. · `apps/desktop/src/bin/tinyvox-dict.rs`

### Engine

- [Engine public API](https://github.com/saqlainnnnn/tinyvox/blob/main/crates/engine/src/lib.rs): crate facade · `crates/engine/src/lib.rs`
- [Dictation controller](https://github.com/saqlainnnnn/tinyvox/blob/main/crates/engine/src/controller.rs): orchestrator · Coordinates dictation lifecycle and processing decisions. · `crates/engine/src/controller.rs`
- [Engine state](https://github.com/saqlainnnnn/tinyvox/blob/main/crates/engine/src/state.rs): state model · `crates/engine/src/state.rs`
- [Engine events](https://github.com/saqlainnnnn/tinyvox/blob/main/crates/engine/src/event.rs): event model · `crates/engine/src/event.rs`
- [Audio capture port](https://github.com/saqlainnnnn/tinyvox/blob/main/crates/engine/src/ports/audio.rs): engine port · `crates/engine/src/ports/audio.rs`
- [Speech-to-text port](https://github.com/saqlainnnnn/tinyvox/blob/main/crates/engine/src/ports/stt.rs): engine port · `crates/engine/src/ports/stt.rs`
- [Cleanup port](https://github.com/saqlainnnnn/tinyvox/blob/main/crates/engine/src/ports/cleanup.rs): engine port · `crates/engine/src/ports/cleanup.rs`
- [Text injection port](https://github.com/saqlainnnnn/tinyvox/blob/main/crates/engine/src/ports/injection.rs): engine port · `crates/engine/src/ports/injection.rs`
- [Dictionary domain](https://github.com/saqlainnnnn/tinyvox/blob/main/crates/engine/src/dictionary.rs): domain model · `crates/engine/src/dictionary.rs`
- [Dictionary store](https://github.com/saqlainnnnn/tinyvox/blob/main/crates/engine/src/dictionary_store.rs): persistence · `crates/engine/src/dictionary_store.rs`

### Audio, STT & cleanup

- [Audio capture](https://github.com/saqlainnnnn/tinyvox/blob/main/crates/audio/src/lib.rs): adapter crate · `crates/audio/src/lib.rs`
- [Pulse STT](https://github.com/saqlainnnnn/tinyvox/blob/main/crates/stt-pulse/src/lib.rs): transcription adapter · `crates/stt-pulse/src/lib.rs`
- [Cleanup pipeline](https://github.com/saqlainnnnn/tinyvox/blob/main/crates/cleanup/src/pipeline.rs): transcript pipeline · Composes local and external cleanup stages with validation. · `crates/cleanup/src/pipeline.rs`
- [Cleanup backends](https://github.com/saqlainnnnn/tinyvox/blob/main/crates/cleanup/src/groq.rs): service integrations · Basic, Electron, Groq, and Llama cleanup implementations. · `crates/cleanup/src/groq.rs`

### Windows platform

- [Windows runtime](https://github.com/saqlainnnnn/tinyvox/blob/main/crates/win/src/lib.rs): platform crate · Provides foreground, credentials, overlay, and OS integration. · `crates/win/src/lib.rs`
- [Windows text injection](https://github.com/saqlainnnnn/tinyvox/blob/main/crates/win/src/injection.rs): platform adapter · `crates/win/src/injection.rs`

### Other components

- [Cargo workspace](https://github.com/saqlainnnnn/tinyvox/blob/main/Cargo.toml): Rust workspace · `Cargo.toml`
- [Voice commands](https://github.com/saqlainnnnn/tinyvox/blob/main/crates/voice-command/src/lib.rs): command interpreter · Converts recognized phrases into actions. · `crates/voice-command/src/lib.rs`

## Connections

- Cargo workspace → Desktop application: builds
- Cargo workspace → Dictionary CLI: builds
- Desktop application → Engine public API: uses
- Engine public API → Dictation controller: exposes
- Dictation controller → Engine state: updates
- Dictation controller → Engine events: emits
- Dictation controller → Audio capture port: captures through
- Dictation controller → Speech-to-text port: transcribes through
- Dictation controller → Cleanup port: cleans through
- Dictation controller → Text injection port: delivers through
- Audio capture → Audio capture port: implements
- Pulse STT → Speech-to-text port: implements
- Cleanup pipeline → Cleanup port: implements
- Cleanup backends → Cleanup pipeline: stages
- Windows text injection → Text injection port: implements
- Windows runtime → Windows text injection: contains
- Pulse STT → Cleanup pipeline: transcript
- Dictation controller → Voice commands: interprets commands
- Dictionary CLI → Dictionary domain: manages
- Dictionary domain → Dictionary store: persists via
- Desktop application → Windows runtime: binds platform services