189 lines
5.0 KiB
Markdown
189 lines
5.0 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
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](https://gitea.nik4nao.com/nik/home-services/src/branch/main/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](https://gitea.nik4nao.com/nik/home-services/src/branch/main/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](https://gitea.nik4nao.com/nik/home-services/src/branch/main/discord-bot/README.md).
|
|
|
|
## Repo Structure
|
|
|
|
```text
|
|
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:
|
|
|
|
```bash
|
|
go work sync
|
|
```
|
|
|
|
Regenerate protobuf code after changing files under `proto/`:
|
|
|
|
```bash
|
|
buf generate
|
|
```
|
|
|
|
Run services in separate terminals:
|
|
|
|
```bash
|
|
cp ha-gateway/.env.example ha-gateway/.env
|
|
cd ha-gateway
|
|
go run ./cmd/gateway
|
|
```
|
|
|
|
```bash
|
|
cp ai-gateway/.env.example ai-gateway/.env
|
|
cd ai-gateway
|
|
go run ./cmd/gateway
|
|
```
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
go test ./ha-gateway/... ./ai-gateway/... ./discord-bot/...
|
|
```
|
|
|
|
Build service binaries from the workspace root:
|
|
|
|
```bash
|
|
go build ./ha-gateway/... ./ai-gateway/... ./discord-bot/...
|
|
```
|
|
|
|
Build container images from the workspace root:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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.
|