ryan
4a928b7067
- Add dashboard development commands (just dashboard, mix phx.server)
- Document Dashboard.Application and Dashboard.MqttSubscriber components
- Add comprehensive dashboard section with MQTT configuration details
- Include critical implementation notes for Tortoise handler return values
- Fix handle_message to return {:ok, state} instead of [] to prevent crashes
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
104 lines
3.8 KiB
Markdown
104 lines
3.8 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Common Commands
|
|
|
|
### Development
|
|
```bash
|
|
# Install dependencies
|
|
mix deps.get
|
|
|
|
# Compile the project
|
|
mix compile
|
|
|
|
# Run in development (non-halt mode)
|
|
mix run --no-halt
|
|
|
|
# Run tests
|
|
mix test
|
|
|
|
# Run specific test
|
|
mix test test/systant_test.exs
|
|
|
|
# Enter development shell (via Nix)
|
|
nix develop
|
|
|
|
# Run dashboard (Phoenix LiveView)
|
|
cd dashboard && mix phx.server
|
|
# or use justfile: just dashboard
|
|
```
|
|
|
|
### Production
|
|
```bash
|
|
# Build production release
|
|
MIX_ENV=prod mix release
|
|
|
|
# Run production release
|
|
_build/prod/rel/systant/bin/systant start
|
|
```
|
|
|
|
## Architecture Overview
|
|
|
|
This is an Elixir OTP application that serves as a systemd daemon for MQTT-based system monitoring, designed for deployment across multiple NixOS hosts to integrate with Home Assistant.
|
|
|
|
### Core Components
|
|
- **Systant.Application** (`lib/systant/application.ex`): OTP application supervisor that starts the MQTT client
|
|
- **Systant.MqttClient** (`lib/systant/mqtt_client.ex`): GenServer that handles MQTT connection, publishes stats every 30 seconds, and listens for commands
|
|
- **Dashboard.Application** (`dashboard/lib/dashboard/application.ex`): Phoenix LiveView dashboard application
|
|
- **Dashboard.MqttSubscriber** (`dashboard/lib/dashboard/mqtt_subscriber.ex`): Real-time MQTT subscriber that feeds data to the LiveView dashboard
|
|
- **Configuration**: MQTT settings configurable via environment variables or config files
|
|
|
|
### Key Libraries
|
|
- **Tortoise**: MQTT client library for pub/sub functionality
|
|
- **Jason**: JSON encoding/decoding for message payloads
|
|
|
|
### MQTT Behavior
|
|
- Publishes "Hello from systant" messages with timestamp and hostname to stats topic every 30 seconds
|
|
- Subscribes to commands topic for incoming events that can trigger user-customizable actions
|
|
- Uses randomized client ID to avoid conflicts across multiple hosts
|
|
- Sends immediate hello message on startup
|
|
|
|
### Default Configuration
|
|
- **MQTT Host**: `mqtt.home` (not localhost)
|
|
- **Stats Topic**: `systant/${hostname}/stats` (per-host topics)
|
|
- **Command Topic**: `systant/${hostname}/commands` (per-host topics)
|
|
- **Publish Interval**: 30 seconds
|
|
|
|
### NixOS Deployment
|
|
This project includes a complete Nix packaging and NixOS module:
|
|
|
|
- **Package**: `nix/package.nix` - Builds the Elixir release using beamPackages.mixRelease
|
|
- **Module**: `nix/nixos-module.nix` - Provides `services.systant` configuration options
|
|
- **Development**: Use `nix develop` for development shell with Elixir/Erlang
|
|
|
|
The NixOS module supports:
|
|
- Configurable MQTT connection settings
|
|
- Per-host topic naming using `${config.networking.hostName}`
|
|
- Environment variable configuration for runtime settings
|
|
- Systemd service with security hardening
|
|
- Auto-restart and logging to systemd journal
|
|
|
|
## Dashboard
|
|
|
|
The project includes a Phoenix LiveView dashboard (`dashboard/`) that provides real-time monitoring of all systant instances.
|
|
|
|
### Dashboard Features
|
|
- Real-time host status updates via MQTT subscription
|
|
- LiveView interface showing all connected hosts
|
|
- Automatic reconnection and error handling
|
|
|
|
### Dashboard MQTT Configuration
|
|
- Subscribes to `systant/+/stats` to receive updates from all hosts
|
|
- Uses hostname-based client ID: `systant-dashboard-${hostname}` to avoid conflicts
|
|
- Connects to `mqtt.home:1883` (same broker as systant instances)
|
|
|
|
### Important Implementation Notes
|
|
- **Tortoise Handler**: The `handle_message/3` callback must return `{:ok, state}`, not `[]`
|
|
- **Topic Parsing**: Topics may arrive as lists or strings, handle both formats
|
|
- **Client ID Conflicts**: Use unique client IDs to prevent connection instability
|
|
|
|
### Future Plans
|
|
- Integration with Home Assistant via custom MQTT integration
|
|
- Expandable command handling for host-specific automation
|
|
- Multi-host deployment for comprehensive system monitoring |