# Architecture

How panel actually fits together. (An earlier revision of this document
described the original design — SvelteKit, SQLite, Casbin, SFTP; none of
that shipped. This is the real stack.)

## Topology

```
┌───────────────────────────────┐            ┌────────────────────────────┐
│         Controller            │  gRPC/mTLS │      Agent (per host)      │
│  - Embedded web dashboard     │◄──────────►│  - one persistent bidi     │
│  - REST /api/* + SSE events   │   :8443    │    stream (Agent.Connect)  │
│  - Postgres (all state)       │            │  - Docker runtime          │
│  - Internal CA + pairing      │            │  - module loader           │
│  - Scheduler (cron + CEL)     │            │  - RCON adapters           │
│  - Admin HTTP /admin/v1/*     │            │  - state tracker           │
│  - Prometheus /metrics        │            │  - SteamCMD / tar sidecars │
└───────────────────────────────┘            └────────────────────────────┘
        ▲ HTTP :8080                                │ docker.sock
   browser / panelctl / curl                 game containers (one per instance)
```

One controller orchestrates N agents. Agents connect **outbound only**
— an agent box needs no inbound panel ports, just its game ports.

## Components

**Controller** (`controller/cmd/controller`) — a single Go binary:

- **Embedded vanilla-JS dashboard.** No framework, no build step:
  `static/new.html` (shell) + `static/rcc.js` + `static/rcc.css`,
  compiled in via `//go:embed` and served hash-stamped with immutable
  caching. The legacy single-file `static/index.html` is a frozen
  "classic" UI, opt-in via the `panel_ui=classic` cookie. Live data
  reaches the browser over **SSE** (`GET /api/events`, with
  `Last-Event-ID` resume), not WebSockets.
- **Postgres** for everything durable: users/sessions, agents,
  instances + assigned ports, schedules, backup index, pair-token
  hashes, Steam credential ciphertext. Migrations are embedded and run
  at startup. (No SQLite anywhere.)
- **Internal CA** (`controller/internal/ca`, material in `data/ca/`) —
  issues the gRPC server cert and, via the pairing flow, each agent's
  client cert. `-tls auto` turns mTLS on whenever the CA exists.
- **Scheduler** — robfig/cron 6-field triggers **and** CEL expressions
  evaluated against the live event bus with sustained-for windows
  ("empty for 30 minutes → stop"). Actions: rcon, instance
  start/stop/restart, backup.
- **Auth** — argon2id + session cookies; roles are just
  `admin`/`user`; optional Sign-in-with-Steam (OpenID). No
  OIDC/WebAuthn/Casbin.
- **Admin HTTP** (`/admin/v1/*`) — out-of-band repair surface, gated by
  loopback or the `X-Panel-Admin-Token` header, usable when the
  dashboard or a session is broken.

**Agent** (`agent/cmd/agent`) — a single Go binary per game host:

- Dials the controller's gRPC port and holds one bidi stream; all
  control traffic (create/start/stop/update/backup/RCON/file ops,
  events, heartbeats) is multiplexed over `oneof` envelope messages
  (`proto/panel/v1`). Reconnect + rehydrate: instance metadata survives
  agent restarts via `--meta-dir` sidecar files rebuilt from the
  controller's DB.
- **Docker-per-game runtime** (`agent/internal/runtime`): one container
  per instance, named volumes and/or bind mounts under `--data-root`,
  optional host networking. `panel-*` images are **auto-built** from
  the module's in-tree Dockerfile on first use; third-party images are
  pulled. Windows-only servers run under Wine + Xvfb in those images.
- **Sidecars**: `steamcmd/steamcmd` for installs/updates (Windows-depot
  and beta-branch capable), alpine tar containers for backup/restore.
- **State tracker** (`agent/internal/state`): container state + RCON
  polling + log-line pattern matching → typed PlayerEvent/AppState
  events streamed upstream and fanned out to the browser (SSE), the
  scheduler (CEL), and `panelctl watch`.
- **RCON adapters** (`agent/internal/rcon`): `source_rcon`, `telnet`,
  `websocket_rcon` (Rust), `stdio`, `be_rcon` (DayZ), `docker_exec_rcon`
  — all redial on EOF.

**panelctl** (`controller/cmd/panelctl`) — operator CLI. gRPC surface
for day-to-day lifecycle (agents/instances/create/start/stop/rcon/
backup/watch), plus a `panelctl admin` HTTP surface for the repair
endpoints. Uses the same mTLS certs as agents.

**Modules** (`modules/<id>/module.yaml`) — declarative manifests: image
or Dockerfile, ports, env, volumes, config files + templated values,
RCON adapter + commands, state-source polls, log event patterns, update
providers, appearance. The loader (`pkg/module`) is strict
(`KnownFields`) — unknown keys are rejected, not ignored. The README's
"Module manifest" section documents the schema by example.

## Security model

- **Control plane:** gRPC with mTLS; agent certs are issued via
  one-time pairing tokens ([PAIRING.md](PAIRING.md)) and verified at the
  TLS handshake (`tls.RequireAndVerifyClientCert`). Plaintext exists
  only as an explicit dev opt-in (`--insecure` / `-tls off`).
- **Browser:** session cookies over your reverse proxy's TLS
  ([INSTALL.md](INSTALL.md)).
- **Secrets:** per-instance generated secrets in instance metadata;
  Steam credentials AES-GCM-encrypted with a key HKDF-derived from the
  CA key ([ADMIN.md](ADMIN.md)).
- **Blast radius:** the agent needs the Docker socket — root-equivalent
  on its host by design. Run agents on hosts you trust and don't expose
  the controller's gRPC port to the internet without cause.

## Data flow, end to end

1. Operator clicks Create → `POST /api/instances` → controller
   allocates host ports (per-agent window, DB-reserved — see
   [NETWORKING.md](NETWORKING.md)) → `InstanceCreate` envelope to the
   agent.
2. Agent resolves the manifest (env filtering, `$INSTANCE_ID` /
   `$DATA_PATH` substitution), auto-builds/pulls the image, creates the
   container, persists sidecar metadata.
3. Update → SteamCMD sidecar into the game volume. Start → container
   start; state tracker begins polling/tailing; readiness regex flips
   the card to Running.
4. Events stream to the controller → Postgres aggregates + SSE fanout →
   dashboard, scheduler CEL evaluation, `panelctl watch`.

## Not implemented (on purpose or yet)

- OIDC / WebAuthn / Casbin ACLs — local auth + Steam OpenID only.
- SFTP — the web file manager (docker exec/cp with bind-mount fast
  path) covers the common case.
- Host-mode (non-Docker) runtime — manifests declare it, the agent
  fails loudly if asked.
- Multi-tenancy/billing — this is for someone running their own boxes.