infrastructure/
├── home-assistant/          # Home Assistant configuration files
│   ├── configuration.yaml
│   ├── automations.yaml
│   ├── scripts.yaml
│   ├── switches.yaml
│   └── secrets.yaml (gitignored)
│
├── esphome/                 # ESPHome device configurations
│   ├── garage-controller.yaml
│   └── README.md
│
├── voice-assistant/         # Local voice assistant system
│   ├── gaming-pc-setup/          # Docker services (GPU-accelerated AI)
│   ├── surface-go-setup/         # Wyoming satellite installation
│   ├── home-assistant-config/    # Voice pipeline HA config (merge with main)
│   ├── docs/                     # Voice system documentation
│   ├── README.md                 # Voice system overview
│   └── QUICK_START.md           # 30-minute voice setup guide
│
├── docs/                    # Infrastructure documentation
│   ├── FURNACE-PROJECT.md            # Furnace control integration project
│   ├── HOME-ASSISTANT-CONFIG-MERGE.md # Guide to merge voice HA config
│   ├── MQTT-SETUP.md                 # MQTT broker configuration
│   ├── DNS-OVER-TLS-SETUP.md         # DNS security setup
│   ├── MONITORING.md                 # System monitoring setup
│   ├── SERVICES.md                   # Services inventory
│   ├── DISASTER-RECOVERY.md          # Backup and recovery procedures
│   ├── RUNBOOK.md                    # Operational procedures
│   └── IMPROVEMENTS.md               # Future improvements tracking
│
├── scripts/                 # Automation and utility scripts
│
└── claude-shared/          # Shared resources with Claude Code assistant

Quick Start

Home Assistant

Configuration files are in /home-assistant/.

Key Files:

configuration.yaml - Main HA configuration
automations.yaml - All automations
scripts.yaml - Reusable scripts
secrets.yaml - Sensitive data (create from secrets.yaml.example)

Deployment: Copy files to your Home Assistant config directory (typically /config/ in HA OS).

ESPHome Devices

Device configurations are in /esphome/.

Current Devices:

garage-controller - ESP32 with 8-relay board controlling garage doors, lights, and planned furnace integration

Deployment:

cd esphome
esphome run garage-controller.yaml

Or use Home Assistant ESPHome integration for OTA updates.

Voice Assistant

Local GPU-accelerated voice assistant system with Home Assistant integration.

System Components:

Gaming PC (RTX 5060): Docker containers for Ollama LLM, Whisper STT, Piper TTS, OpenWakeWord
Home Assistant: Voice pipeline coordinator
Surface Go: Wyoming satellite (microphone/speaker interface)

Quick Start:

Set up Gaming PC AI services: /voice-assistant/gaming-pc-setup/
Set up Surface Go satellite: /voice-assistant/surface-go-setup/
Merge voice HA config: See /docs/HOME-ASSISTANT-CONFIG-MERGE.md
Full documentation: /voice-assistant/README.md

Current Status: Operational - needs HA config merge for full integration

Active Projects

🔥 Furnace Control Integration

Status: Planning phase
Goal: Replace failed furnace board with ESP32-based smart control
Documentation: docs/FURNACE-PROJECT.md
Hardware: ESP32-WROOM-32E with relay board, 6x temp/humidity sensors
Features: Multi-zone monitoring (garage + shed), HA integration, safety interlocks

🎤 Local Voice Assistant

Status: Operational, pending HA config merge
Goal: GPU-accelerated local voice control with LLM
Documentation: voice-assistant/README.md
Hardware: Gaming PC (RTX 5060), Surface Go (Wyoming satellite)
Features: Ollama LLM, Whisper STT, Piper TTS, OpenWakeWord, no cloud dependencies
Integration: See docs/HOME-ASSISTANT-CONFIG-MERGE.md

🌐 Network Infrastructure

MQTT: Mosquitto broker for device communication
DNS: DNS-over-TLS with Unbound
Documentation: See docs/MQTT-SETUP.md and docs/DNS-OVER-TLS-SETUP.md

Documentation

All infrastructure documentation is in the /docs/ directory:

FURNACE-PROJECT.md - ESP32 furnace control integration
HOME-ASSISTANT-CONFIG-MERGE.md - Merge voice assistant HA config
MQTT-SETUP.md - MQTT broker setup and configuration
DNS-OVER-TLS-SETUP.md - Secure DNS configuration
MONITORING.md - System monitoring and alerting
SERVICES.md - Inventory of all services
DISASTER-RECOVERY.md - Backup and recovery procedures
RUNBOOK.md - Operational procedures and troubleshooting

Voice assistant documentation is in /voice-assistant/docs/:

Installation, commands, calendar setup, troubleshooting

Network Information

Current network setup and IP allocations are documented in:

IP-ALLOCATION.md - IP address assignments
DHCP exports in repository root

Contributing

This is a personal infrastructure repository. Updates are made through:

Local testing and validation
Git commits with descriptive messages
Push to GitHub for backup and history

Secrets Management

Sensitive information (passwords, API keys, etc.) is stored in secrets.yaml files which are gitignored.

Template files:

/home-assistant/secrets.yaml.example
Create your own secrets.yaml from the template

Backup Strategy

See DISASTER-RECOVERY.md for:

Backup procedures
Recovery steps
Critical system information

Support & Notes

Experience Level: 20+ years low voltage wiring, network infrastructure
Tools: Home Assistant, ESPHome, MQTT, Unbound DNS
Approach: Document everything, safety-first, incremental improvements

Recent Updates

2025-11-28:
- Consolidated all smart home projects into monorepo
- Added ESPHome directory and furnace control project documentation
- Integrated voice assistant project (Gaming PC AI + Surface Go)
- Created Home Assistant config merge guide
2025-11-27: Home Assistant configuration updates
2025-11-18: MQTT and DNS-over-TLS setup documentation

Maintained by: Fred N9MRQ Repository: https://github.com/FredN9MRQ/infrastructure