# CLAUDE.md

## Project Overview

Wild Central is the networking and coordination platform for the Wild product family. It runs as a standalone service on a local network device (e.g., Raspberry Pi) and manages:

- **DNS** (dnsmasq) — internal name resolution + optional DHCP
- **Gateway** (HAProxy) — L4 SNI passthrough + L7 HTTP reverse proxy with TLS termination
- **Firewall** (nftables) — host firewall rules
- **VPN** (WireGuard) — remote access with peer management
- **TLS** (certbot) — certificate provisioning via DNS-01
- **Tunnels** (cloudflared) — outbound-only public exposure via Cloudflare
- **DDNS** (Cloudflare) — A record + CNAME management
- **Security** (CrowdSec) — intrusion detection
- **NATS JetStream** — coordination bus for domain registration, presence, and events
- **Domain Registration** — the contract API for Wild Cloud and Wild Works

## Architecture

Wild Central is a Go service that manages Linux networking daemons via config file generation and systemctl commands. It provides an HTTP API and an embedded NATS JetStream server.

**Consumers:**
- **Wild Cloud** — registers k8s instance domains for L4 SNI passthrough
- **Wild Works** — registers domains for L7 HTTP reverse proxy with TLS termination

Both connect to Central's NATS (port 4222) or use the HTTP API (port 5055) to register services.

## Development

```bash
make dev    # Run with live reloading (requires air)
make build  # Build binary
make test   # Run tests
make check  # Lint + test
```

### Environment Variables

- `WILD_CENTRAL_DATA_DIR` — Data directory (default: `/var/lib/wild-central`)
- `WILD_CENTRAL_PORT` — API listen port (default: `5055`)
- `WILD_CENTRAL_NATS_PORT` — NATS listen port (default: `4222`)
- `WILD_CENTRAL_DNSMASQ_CONFIG_PATH` — dnsmasq config path
- `WILD_CENTRAL_HAPROXY_CONFIG_PATH` — HAProxy config path
- `WILD_CENTRAL_NFTABLES_RULES_PATH` — nftables rules path
- `WILD_CENTRAL_VPN_CONFIG_PATH` — WireGuard config path
- `WILD_CENTRAL_CORS_ORIGINS` — Allowed CORS origins
- `WILD_CENTRAL_STATIC_DIR` — Web UI static files directory
- `WILD_CENTRAL_VITE_URL` — Vite dev server URL for frontend proxying

### Data Directory

Runtime state is persisted in `{WILD_CENTRAL_DATA_DIR}/`:
- `state.yaml` — operator, domain, firewall, DDNS, DHCP settings (managed via API)
- `secrets.yaml` — API tokens and credentials
- `domains/` — per-domain registration files
- `nats/` — embedded NATS JetStream data
- `instances/` — Wild Cloud instance configs

## Domain Registration API

The key abstraction. Domains register with Central to get DNS, gateway routing, TLS, and public exposure.

```
POST   /api/v1/domains              Register a domain
GET    /api/v1/domains              List all domains
GET    /api/v1/domains/{domain}     Get domain details
PATCH  /api/v1/domains/{domain}     Update domain
DELETE /api/v1/domains/{domain}     Deregister domain
```

### Domain payload

```json
{
  "domain": "my-api.payne.io",
  "source": "wild-works",
  "backend": {
    "address": "192.168.8.60:9001",
    "type": "http",
    "health": "/health"
  },
  "public": false,
  "tls": "terminate"
}
```

### Backend types

- `tcp-passthrough` — L4, SNI routing, backend handles TLS (Wild Cloud k8s)
- `http` — L7, Central terminates TLS with wildcard cert (Wild Works)
- `dns-only` — DNS resolution only, no gateway routing (SSH, game servers, etc.)

### Public

- `false` (default) — LAN-visible only (DNS + gateway + TLS)
- `true` — internet-visible (+ DDNS or tunnel exposure)