# Homelab Topology

## Nodes

| Node | Role |
|---|---|
| SATURN | Control and development node |
| PIHA | Infrastructure and monitoring node |
| SOLARIA | AI and compute node |
| VPS | Public ingress and edge node |
| CHELSTY | LTE-connected edge hypervisor and Home Assistant node |

## Architecture Principles

- Git is the source of truth.
- SATURN is the primary orchestration and commit node.
- Runtime state lives outside repositories.
- Tailscale provides internal mesh networking.
- Docker Compose remains the deployment model.
- Public ingress is centralized on VPS.
- Deployment uses lightweight shell scripts.
- Avoid Kubernetes and heavy orchestration frameworks.

## CHELSTY Home Automation

CHELSTY hosts the local home automation control plane. Because it uses an LTE
uplink and may be intermittently connected, Home Assistant, Zigbee2MQTT, and
Mosquitto must continue operating without SATURN, VPS, or Forgejo.

The CHELSTY Home Assistant inventory is split across:

- `hosts/chelsty/services.yaml`
- `hosts/chelsty/networking.yaml`
- `hosts/chelsty/paths.yaml`

Service exposure is classified as:

- `local-only`: available only on local host, LAN, or container networks.
- `tailscale-internal`: available to approved Tailscale clients only.
- `public`: available from the public internet through explicit ingress.

Initial CHELSTY service intent:

| Service | Role | Exposure | Offline required |
|---|---|---|---|
| homeassistant | Home automation controller | tailscale-internal | yes |
| zigbee2mqtt | Zigbee to MQTT bridge | local-only | yes |
| mosquitto | Local MQTT broker | local-only | yes |

The Zigbee coordinator is an SLZB-06U network coordinator. It should be modeled
as an Ethernet/WiFi network device consumed by Zigbee2MQTT, not as a USB dongle.
Do not use `/dev/ttyUSB0` or other USB device mappings for this coordinator.

## Runtime Layout

Runtime data should live under:

/opt/homelab

with separated:
- services
- data
- config
- logs

CHELSTY follows the same layout:

- `/opt/homelab/data/<service>` for persistent service data.
- `/opt/homelab/config/<service>` for host-local configuration and secrets.
- `/opt/homelab/logs/<service>` for logs that should stay outside Git.

Critical backup sets on CHELSTY include Home Assistant config, Zigbee2MQTT
config and network state, Mosquitto config/data, and SLZB-06U coordinator state.