# eintoast/openai_stt_ha architecture

> Architecture diagram of the GitHub repository eintoast/openai_stt_ha, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/eintoast/openai_stt_ha
- Repository: https://github.com/eintoast/openai_stt_ha

## Overview

##### Main Components
- Home Assistant Core: This is the central hub that manages integrations and overall home automation.
- Custom Component (openai_stt): This component is integrated into Home Assistant under its “custom_components” directory. It contains files like __init__.py, stt.py, and the manifest.json which define the integration’s metadata and service behavior.
- External API – OpenAI Speech-to-Text (Whisper) Service: This external service is used by the component to perform the actual speech-to-text conversion.

##### Relationships and Interactions
- Home Assistant loads the custom integration (openai_stt) during startup.
- When a speech-to-text process is triggered in Home Assistant, the custom integration takes the audio input and communicates with the OpenAI API.
- The OpenAI API processes the audio data and returns text data, which the Home Assistant system then uses according to its configured automation or response logic.

##### Important Architectural Patterns and Design Principles
- Modular Integration: The design leverages Home Assistant’s pluggable architecture by placing the custom integration in a dedicated directory. This separation enables easier maintenance and updates.
- API Communication: The component embodies a client-server model where the integration acts as the client and OpenAI’s service is the server.
- Configurability: Through YAML configuration in the user’s Home Assistant configuration, parameters such as API key, model, API URL, prompt, and temperature are specified, allowing dynamic behavior without modifying code.

##### Technologies and Frameworks
- Home Assistant Platform: As the orchestrator of integrations.
- Python: The custom component is written in Python (as evident from __init__.py and stt.py).
- OpenAI API: Specifically, the Whisper STT model is used for converting speech to text.

##### Additional Guidance
- Clarity: Ensure each component is clearly labeled with its role (like “Speech-to-Text Integration”, “OpenAI API”, “Home Assistant Core”).
- Configuration elements if desired (such as a note on how YAML configuration ties into the initialization of the custom integration).

## Diagram (Mermaid)

```mermaid
flowchart TD
    HA["Home Assistant Core"]:::ha
    INT["openai_stt (Custom Integration)"]:::integration
    API["OpenAI Speech-to-Text API"]:::external

    HA -->|"loads integration"| INT
    INT -->|"API_Call:send_audio_data"| API
    API -->|"Response:transcribed_text"| INT

    subgraph "openai_stt Component Files"
        I1["__init__.py"]:::integration
        I2["stt.py - Speech-to-Text Logic"]:::integration
        I3["manifest.json - Metadata"]:::integration
    end

    INT -->|"initializes"| I1
    I1 -->|"configures"| I2
    I2 -->|"references"| I3

    click INT "https://github.com/eintoast/openai_stt_ha/tree/main/custom_components/openai_stt"

    classDef ha fill:#8ecae6,stroke:#023047,stroke-width:2px,color:#ffffff;
    classDef integration fill:#ffb703,stroke:#fb8500,stroke-width:2px,color:#000000;
    classDef external fill:#ffddd2,stroke:#d62828,stroke-width:2px,color:#000000;
```
