# TTS-Groq: Module and Function Reference
This document provides a detailed breakdown of the main modules, key structs, traits, and design patterns in TTS-Groq.
---
## 1. `main.rs`
- **Purpose:** Entry point. Initializes logging, parses arguments, creates and runs the main `App`.
- **Key Functions:**
- `main()`: Bootstraps the application.
- `parse_args()`: Parses CLI/config.
---
## 2. `app.rs`
- **Purpose:** Orchestrates application lifecycle, background tasks, and state.
- **Key Structs:**
- `App`: Holds config, audio manager, provider, shutdown manager, etc.
- **Key Methods:**
- `new()`: Constructs the app, initializes providers and state.
- `run()`: Main event loop: initializes audio, starts streams, spawns tasks, manages shutdown.
- `start_tasks()`: Spawns audio processing and hotkey tasks.
- `wait_for_shutdown()`: Handles graceful shutdown.
---
## 3. `audio/`
- **Purpose:** Audio device management, buffering, streaming, and chunking.
- **Key Modules:**
- `device.rs`: Device selection, listing, and abstraction.
- `device_manager.rs`: Higher-level device orchestration.
- `buffer.rs`: Thread-safe audio buffering and chunking logic.
- `stream.rs`: Audio stream abstraction.
- `stream_manager.rs`: Orchestrates streaming, chunking, and exposes channels for audio data.
- `constants.rs`: Audio-related constants.
---
## 4. `audio_state.rs`
- **Purpose:** Manages recording state (active/inactive), shared across components.
- **Key Structs:**
- `RecordingState`: Atomic flag for recording state.
---
## 5. `transcription/`
- **Purpose:** Audio chunk processing, provider interaction, and result handling.
- **Key Modules:**
- `mod.rs`: Implements `process_audio_chunks`, orchestrates chunking, provider calls, and result handler dispatch.
- `result_handler.rs`: Defines `TranscriptionResultHandler` trait for handling transcription results.
---
## 6. `providers/`
- **Purpose:** Abstraction over external transcription APIs.
- **Key Traits:**
- `TranscriptionProvider`: Trait for all providers (Groq, OpenAI, Mock, etc.).
- **Key Structs:**
- `GroqProvider`, `OpenAIProvider`, `MockProvider`: Implement the provider trait.
- **Key Functions:**
- `create_provider()`: Factory for provider selection.
---
## 7. `platform/`
- **Purpose:** Platform-specific text insertion and user interaction.
- **Key Traits:**
- `TextInserter`: Trait for inserting text into the user's workflow.
- **Key Structs:**
- `PlatformTextInserterHandler`: Implements `TranscriptionResultHandler` by wrapping a `TextInserter`.
- `StubTextInserter`: Dummy for testing/development.
- `InsertOptions`: Configurable options for insertion.
---
## 8. `hotkey_service.rs`
- **Purpose:** Registers, listens for, and handles hotkey events to trigger recording/transcription.
- **Key Structs:**
- `HotkeyService`: Manages hotkey registration and event loop.
---
## 9. `shutdown_handler.rs`
- **Purpose:** Coordinates graceful shutdown across components.
- **Key Structs:**
- `ShutdownManager`: Registers handlers, broadcasts shutdown events.
---
## 10. `config.rs`
- **Purpose:** Defines configuration structs, CLI parsing, and config loading.
- **Key Structs:**
- `AppConfig`: Main application config, supports CLI and file-based config.
---
## 11. `my_tracing.rs`
- **Purpose:** Logging and tracing setup for diagnostics.
- **Key Functions:**
- `initialize()`: Configures tracing/logging.
---
## Design Patterns and Notable Choices
- **Hexagonal Architecture:** Core business logic is decoupled from platform and provider details via traits.
- **Async/Actor Model:** Tokio tasks and channels for concurrency and decoupling.
- **Trait Objects:** For runtime polymorphism across providers and platform handlers.
- **Graceful Shutdown:** Uses broadcast channels and handler registration for robust shutdown.
- **Extensibility:** New providers, platforms, or features can be added with minimal changes to core logic.
---
## Extending and Testing
- **To add a provider:** Implement `TranscriptionProvider` and register it in `create_provider()`.
- **To add a platform handler:** Implement `TextInserter` and wrap with `PlatformTextInserterHandler`.
- **Testing:** Modular design enables unit and integration testing of most components in isolation.
---
For an executive summary, see [README.md](README.md). For architectural context, see [architecture.md](architecture.md).