Files

Paul Payne 3c3d5be1ea docs: Add CLAUDE.md for Wild Central

Document the project overview, architecture, development commands,
environment variables, and the service registration API contract.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-07-09 00:05:17 +00:00

3.1 KiB

Raw Blame History

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 service registration, presence, and events
Service 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 services 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

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_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

Service Registration API

The key abstraction. Services register with Central to get DNS, proxy, TLS, and public exposure.

POST   /api/v1/services              Register a service
GET    /api/v1/services              List all services
GET    /api/v1/services/{name}       Get service details
PATCH  /api/v1/services/{name}       Update service
DELETE /api/v1/services/{name}       Deregister service

Service payload

{
  "name": "my-api",
  "source": "wild-works",
  "domain": "my-api.payne.io",
  "backend": {
    "address": "192.168.8.60:9001",
    "type": "http",
    "health": "/health"
  },
  "reach": "internal",
  "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 services)
static — L7, static file serving (Wild Works frontends)

Reach levels

off — localhost only
internal — LAN-visible (DNS + proxy + TLS)
public — internet-visible (+ tunnel or direct exposure)

3.1 KiB Raw Blame History