add read me

README.md

@@ -0,0 +1,56 @@
+# Voice Assistant Bridge (Docker Backend)
+
+This repository contains the backend infrastructure for the local Voice Assistant system. It acts as the middleware between the ESP32 audio stream and Home Assistant.
+
+## 🏗️ Architecture
+
+```mermaid
+graph LR
+    ESP32[ESP32 Hardware] -->|MQTT Audio Stream| Bridge
+    Bridge[Python Bridge] -->|HTTP Request| Whisper[Faster-Whisper Container]
+    Whisper -->|Text| Bridge
+    Bridge -->|MQTT Text Command| HA[Home Assistant]
+    Bridge -->|MQTT Status| ESP32
+```
+
+## 🧩 Components
+
+### 1. `docker-compose.yml`
+Orchestrates two containers:
+*   **`voice-bridge`**: The logic handler. Listens to MQTT audio, buffers it, detects Wake Words via `OpenWakeWord`, and handles routing.
+*   **`whisper-api`**: A lightweight Flask API wrapping `faster-whisper` for Speech-to-Text conversion.
+
+### 2. `mqtt_audio_bridge.py`
+The main Python script running inside the `voice-bridge` container.
+*   **Input:** Listens to raw PCM audio on `voice/audio_stream` (Broker .13).
+*   **Processing:**
+    *   Uses **OpenWakeWord** to detect "Hey Jarvis".
+    *   Buffers audio and sends to Whisper API.
+    *   Safety mechanisms (Memory limits, Log rotation).
+*   **Output:** Publishes transcribed text to `homeassistant/voice/text` (Broker .30).
+
+### 3. `app.py`
+The Whisper API endpoint.
+*   **Model:** `small.en` (Optimized for CPU usage with `int8` quantization).
+*   **Language:** Locked to English to prevent hallucinations on static/silence.
+
+## 🚀 Deployment
+
+1.  **Requirements:** Docker & Docker Compose.
+2.  **Configuration:** Update IP addresses in `mqtt_audio_bridge.py` for your MQTT brokers.
+3.  **Run:**
+    ```bash
+    docker compose up -d
+    ```
+
+## 🔧 Debugging
+
+**View Logs:**
+```bash
+docker compose logs -f voice_bridge
+```
+
+**Restart Stack:**
+```bash
+docker compose restart
+```