home-services/README.md

home-services

home-services is a Go workspace for internal home-control services. It keeps Home Assistant behind a gRPC gateway, adds an AI command gateway backed by Ollama, and exposes both through a Discord slash-command bot.

Architecture

The services follow hexagonal architecture:

• internal/core contains domain types and ports
• internal/app contains use-case orchestration
• internal/adapters contains gRPC, Discord, Home Assistant, Ollama, logging, and telemetry edges
• dependencies point inward toward the app and core packages

Service flow:

Discord users
     |
     v
discord-bot -----> ha-gateway -----> Home Assistant REST API
     |
     v
ai-gateway ------> Ollama
     |
     v
ha-gateway

The protobuf contracts live under proto/. Generated Go code is committed under gen/ and shared by all modules through the Go workspace.

Services

ha-gateway

Internal gRPC gateway for Home Assistant.

• Default port: 50051
• Talks to Home Assistant through the REST API
• Implements entity state lookup and discovery
• Implements light control and light discovery
• Implements switch discovery
• Stubs switch control and event streaming
• Supports optional mTLS when TLS_DIR is set
• Exposes gRPC health checks and reflection

See ha-gateway/README.md.

ai-gateway

Internal gRPC gateway for AI-assisted home commands.

• Default port: 50052
• Calls Ollama for intent extraction and model listing
• Calls ha-gateway for light discovery and light actions
• Caches light discovery results for prompt context
• Supports optional mTLS when TLS_DIR is set
• Exposes gRPC health checks; reflection is enabled in debug logs

See ai-gateway/README.md.

discord-bot

Discord slash-command process for home control.

• Registers /light, /switch, and /ai commands
• Calls ha-gateway for direct Home Assistant commands
• Calls ai-gateway for free-form AI queries and model management
• Supports optional mTLS for gateway clients when TLS_DIR is set

See discord-bot/README.md.

Repo Structure

home-services/
├── ai-gateway/          # AI gRPC gateway backed by Ollama and ha-gateway
├── discord-bot/         # Discord slash-command bot
├── gen/                 # Committed generated protobuf/gRPC Go code
├── ha-gateway/          # Home Assistant gRPC gateway
├── proto/               # Source protobuf contracts
├── buf.gen.yaml         # Buf generation config
├── buf.yaml             # Buf module config
└── go.work              # Go workspace

Local Development

Prerequisites:

• Go 1.26+
• buf, when changing .proto files
• grpcurl, for manual gRPC checks
• Home Assistant with a long-lived access token
• Ollama, if running AI queries
• A Discord application and bot token, if running discord-bot

Set up dependencies:

go work sync

Regenerate protobuf code after changing files under proto/:

buf generate

Run services in separate terminals:

cp ha-gateway/.env.example ha-gateway/.env
cd ha-gateway
go run ./cmd/gateway

cp ai-gateway/.env.example ai-gateway/.env
cd ai-gateway
go run ./cmd/gateway

cp discord-bot/.env.example discord-bot/.env
cd discord-bot
go run ./cmd/bot

Each service loads .env from its current working directory, so run commands from the service directory when using the example env files.

Test And Build

Run tests from the workspace root:

go test ./ha-gateway/... ./ai-gateway/... ./discord-bot/...

Build service binaries from the workspace root:

go build ./ha-gateway/... ./ai-gateway/... ./discord-bot/...

Build container images from the workspace root:

docker build -f ha-gateway/Dockerfile -t ha-gateway:dev .
docker build -f ai-gateway/Dockerfile -t ai-gateway:dev .
docker build -f discord-bot/Dockerfile -t discord-bot:dev .

gRPC Smoke Checks

With ha-gateway running locally:

grpcurl -plaintext -d '{"domain":"light"}' \
  localhost:50051 ha.v1.EntityService/ListStates

grpcurl -plaintext -d '{"entity_id":"light.living_room","brightness_pct":80}' \
  localhost:50051 ha.v1.LightService/TurnOn

With ai-gateway running locally:

grpcurl -plaintext -d '{"text":"turn on the desk lamp","source":"local"}' \
  localhost:50052 ai.v1.AIService/Query

grpcurl -plaintext -d '{}' localhost:50052 ai.v1.AIService/ListModels

Configuration Notes

• LOG_FORMAT=json is the production default; LOG_FORMAT=text is easier locally.
• OTEL_ENDPOINT enables OTLP gRPC traces and metrics. Leave it empty for local no-op telemetry.
• TLS_DIR enables mTLS. The directory must contain tls.crt, tls.key, and ca.crt.
• Inbound app-layer authorization is not implemented. Keep the gateways on a trusted internal network or use mTLS.