# royalcities/rc-home-assistant-low-vram architecture

> Architecture diagram of the GitHub repository royalcities/rc-home-assistant-low-vram, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/royalcities/rc-home-assistant-low-vram
- Repository: https://github.com/royalcities/rc-home-assistant-low-vram

## Overview

##### Project type and purpose
- This is a full-stack, self-hosted AI voice assistant “stack” built on Docker Compose.
- Purpose: provide local, GPU-accelerated voice interaction using open-source AI services (wake-word detection, speech-to-text, text-to-speech) plus Home Assistant for device control and automation.

##### File structure
Top-level files:
- docker-compose.yml – orchestrates all containers
- README.md – project overview, architecture hints
- AI-Persistent-Memory.md, Vocal-Command-Daisy-Chaining.md, Ollama-Model-Recommendations.md – advanced feature guides
Indirectly referenced folders (auto-created volumes):
- homeassistant_config/ – HA config volume
- whisper-data/ – Whisper model files
- piper-data/ – Piper voice data
- wakeword-data/ – custom wake-word models

##### Key insights from README
- Four main services: homeassistant (no GPU), whisper (CUDA STT), piper (CUDA TTS), openwakeword (CUDA wake-word).
- External dependency: Ollama AI daemon running on host at port 11434.
- GPU acceleration via nvidia-container-toolkit in each AI service.
- Host networking for mDNS/SSDP device discovery.
- Optional Bluetooth device passthrough to Home Assistant.
- Volumes auto-provisioned for persistence.

##### Main components
A. Input layer
- Microphone (host OS device)
- Wake-word detection container (openwakeword)
B. Processing layer
- Speech-to-Text container (Whisper)
- Conversation agent (Ollama, external)
C. Orchestration & control
- Home Assistant container
- Automations & device integrations (Zigbee, Matter, BLE, LAN)
D. Output layer
- Text-to-Speech container (Piper)
- Speaker (host OS audio output)
E. Persistent storage & config
- Volumes: homeassistant_config, whisper-data, piper-data, wakeword-data
F. External services & devices
- Ollama daemon (host)
- Smart home devices (lights, plugs, sensors)
- User’s browser/UI (http://localhost:8123)

##### Relationships & data flows
1. Microphone captures audio → forwarded to openwakeword
2. openwakeword detects wake-word → streams raw audio to Whisper
3. Whisper decodes → text transcript → sent to Home Assistant
4. Home Assistant routes text to Ollama agent (HTTP API)
5. Ollama generates response → returned to HA
6. HA forwards response text to Piper
7. Piper synthesizes audio → plays via speaker
8. HA triggers automations or device API calls (Zigbee, BLE, local LAN)

##### Architectural patterns & design principles
- Microservices: each AI function is a separate container
- Containerization with Docker Compose for easy orchestration
- Layered architecture (input → processing → orchestration → output)
- GPU offload for compute-heavy tasks
- Host network mode for zero-config device discovery
- Persistent volumes for upgrade-safe data/config

##### Technologies & frameworks to call out
- Docker & Docker Compose
- NVIDIA Container Toolkit (nvidia-docker)
- Home Assistant (Python, YAML-based config)
- Whisper (PyTorch/CUDA)
- Piper (Rust or Python + CUDA)
- OpenWakeWord (TensorFlow Lite + CUDA)
- Ollama API (HTTP REST)
- mDNS/SSDP, Bluetooth (Linux host)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Host System
    subgraph "Host System"
        direction TB
        Mic["Microphone"]:::io
        Spk["Speaker"]:::io
        Ollama["Ollama Daemon<br/>(port 11434)"]:::external
        SmartDev["Smart Devices<br/>(Zigbee, BLE, LAN)"]:::external
    end

    %% Containers
    subgraph "Containers"
        direction TB

        subgraph "Input Layer"
            OW["Wake-word Detection<br/>(openwakeword) GPU"]:::gpu
        end

        subgraph "Processing & Orchestration"
            WH["Speech-to-Text<br/>(Whisper) GPU"]:::gpu
            HA["Home Assistant<br/>(UI: HTTP 8123)<br/>host network"]:::service
        end

        subgraph "Output Layer"
            PP["Text-to-Speech<br/>(Piper) GPU"]:::gpu
        end
    end

    %% Volumes
    subgraph "Persistent Volumes"
        direction TB
        VAC["homeassistant_config"]:::volume
        VWH["whisper-data"]:::volume
        VPP["piper-data"]:::volume
        VOW["wakeword-data"]:::volume
    end

    %% Documentation
    subgraph "Documentation & Guides"
        direction TB
        DC["Docker Compose Orchestration"]:::doc
        RO["Project Overview & Architecture"]:::doc
        PM["Persistent Memory Guide"]:::doc
        VC["Vocal Command Chaining Guide"]:::doc
        OR["Ollama Model Recommendations"]:::doc
    end

    %% Data Flows
    Mic -->|"audio stream"| OW
    OW -->|"raw audio"| WH
    WH -->|"text transcript"| HA
    HA -->|"HTTP request"| Ollama
    Ollama -->|"response text"| HA
    HA -->|"text for TTS"| PP
    PP -->|"audio output"| Spk
    HA -->|"device commands"| SmartDev

    %% Volume Mounts
    VAC --> HA
    VWH --> WH
    VPP --> PP
    VOW --> OW

    %% Click Events
    click DC "https://github.com/royalcities/rc-home-assistant-low-vram/blob/main/docker-compose.yml"
    click RO "https://github.com/royalcities/rc-home-assistant-low-vram/blob/main/README.md"
    click PM "https://github.com/royalcities/rc-home-assistant-low-vram/blob/main/AI-Persistent-Memory.md"
    click VC "https://github.com/royalcities/rc-home-assistant-low-vram/blob/main/Vocal-Command-Daisy-Chaining.md"
    click OR "https://github.com/royalcities/rc-home-assistant-low-vram/blob/main/Ollama-Model-Recommendations.md"

    %% Styles
    classDef gpu fill:#ffe6f7,stroke:#ff00ff,stroke-width:2px
    classDef service fill:#e6ffe6,stroke:#00cc00,stroke-width:2px
    classDef io fill:#fff5cc,stroke:#ff9900,stroke-width:2px
    classDef external fill:#e6e6ff,stroke:#3333ff,stroke-width:2px
    classDef volume fill:#ffdede,stroke:#ff0000,stroke-width:2px,stroke-dasharray: 5 5
    classDef doc fill:#dddddd,stroke:#888888,stroke-width:1px,stroke-dasharray: 2 2
```
