# NODES.md — James Node Model

James treats all machines as part of a single distributed system.

---

## Node Identity

Each node defines:

- `JAMES_NODE` (hostname)
- `JAMES_ROLE` (function)

**Example:**

- `gpu-box` → compute
- `pi-server` → control
- `main-host` → storage

---

## Node Health Model

```json
{
  "node": "main-host",
  "role": "storage",
  "status": "degraded",
  "issues": ["disk_usage_high"],
  "timestamp": 1738678200
}
```

---

## System Awareness

James maintains a global view of:

- Compute availability
- Storage health
- Control plane uptime
- Container distribution

This enables cross-node decisions:

- Workload reassignment
- Alert escalation
- Failure isolation

---

## Node Capabilities

### GPU Box

- **Role:** Compute
- **Services:** Game servers (Minecraft, Valheim, ARK, Factorio)
- **Monitored:** GPU VRAM, CPU, container health

### Pi Server (if applicable)

- **Role:** Control plane
- **Services:** Redis, lightweight watchers
- **Monitored:** Uptime, network connectivity

### Main Host

- **Role:** Storage + orchestration
- **Services:** NAS (DS213, DS414), Home Assistant
- **Monitored:** Disk usage, backup status

---

## Docker Integration

Watchers monitor:

- Container states (`running`, `stopped`, `restarting`)
- Resource usage per container
- Health check failures
- Network connectivity

**Docker socket:** `/var/run/docker.sock` (mounted read-only to watchers)