feat(server): initial implementation

This commit captures the full server code accumulated across
several development sessions. It includes the following layers,
applied in roughly this order during development:

1. Base infrastructure
   - cmd/poc-server HTTP+WebSocket server, /health, /stats
   - internal/transport wire types (Envelope + all message types)
   - internal/catalog, internal/realtime, internal/stats
   - internal/storage/postgres with migrations 001-004
   - .env, .env.example, docker-compose, Dockerfile, scripts/

2. Swagger documentation
   - go get github.com/swaggo/http-swagger
   - swag init produces docs/docs.go
   - /swagger/index.html UI, /swagger/doc.json spec
   - annotations on health/stats/ws and catalog handlers

3. Races API
   - internal/races/{store,service,keyset,types}.go
   - migration 005_races.sql: finished_races, race_plans, race_queue
   - GET /api/races with keyset pagination, status filter
   - GET /api/races/upcoming
   - POST /api/races/queue/join, GET, DELETE
   - POST/GET /api/races/plans, DELETE /{id}
   - lobby.RaceMeta simplification (no host_id/host_name)

4. Races seeder
   - internal/races/seed with deterministic generator
   - --seed-races / --reset CLI flags in main.go
   - 30 finished + 5 live + 5 plans + 4 queue entries

5. Drivers and clans
   - internal/drivers, internal/clans (CRUD, validation)
   - migration 008_drivers_clans.sql
   - /api/clans and /api/drivers endpoints
   - 3-letter uppercase nickname/tag validation
   - lobby.DriverMeta: Nickname, AvatarURL, ClanID, ClanTag

6. Podium
   - internal/transport.RacePodiumEntry
   - lobby.SetDriverProfile for in-memory metadata sync
   - migration 007_podium.sql (podium JSONB column)
   - seeder populates top-3 per finished race

7. Live races persistence
   - migration 009_live_persistence.sql: live_races,
     live_race_drivers, lobby_drivers
   - internal/races/live_store.go: LiveStore with write-side
     mirror for lobby.Service mutations
   - Service.collectLive and Upcoming read from Postgres
   - main.go RestoreFromDB rehydrates lobby on startup

8. Unify live + finished into one races table
   - migration 010_unify_races.sql: rename finished_races to
     races, expand status CHECK, merge live rows
   - PgStore now hosts both write paths; LiveStore is a
     thin facade implementing lobby.Persistence
   - seeder resetAll drops only finished/cancelled rows and
     race_plans / race_queue / lobby_drivers

Each layer is consistent on its own; cross-layer changes are
visible in the file history. A future refactor may split this
commit into the per-stage boundaries listed above.

server/Makefile

@@ -0,0 +1,87 @@
+# x0gp PoC server Makefile
+#
+# Common targets:
+#   make tidy      - go mod tidy
+#   make build     - compile poc-server (linux/arm64 by default for Orange Pi 5 Pro)
+#   make run       - build + run locally (dev mode, port 8080)
+#   make proto     - regenerate Go from proto/ via Docker
+#   make test      - go test ./...
+#   make lint      - go vet + (optional) golangci-lint
+#   make docker    - build the api-gateway image
+#   make compose   - run dev stack (postgres + redis + prometheus + grafana + api-gateway)
+
+GO ?= go
+APP := poc-server
+BIN_DIR := bin
+GOOS ?= linux
+GOARCH ?= arm64
+GOARM ?=
+LDFLAGS := -s -w -X main.version=$(shell git describe --tags --always --dirty 2>/dev/null || echo dev)
+
+# Honour explicit user overrides of GOOS/GOARCH (e.g. make build GOARCH=amd64).
+ifeq ($(GOARCH),arm64)
+  ifeq ($(GOOS),linux)
+    TARGET := $(BIN_DIR)/$(APP)-linux-arm64
+  endif
+endif
+ifeq ($(GOARCH),amd64)
+  ifeq ($(GOOS),linux)
+    TARGET := $(BIN_DIR)/$(APP)-linux-amd64
+  endif
+endif
+ifeq ($(GOARCH),arm64)
+  ifeq ($(GOOS),darwin)
+    TARGET := $(BIN_DIR)/$(APP)-darwin-arm64
+  endif
+endif
+ifeq ($(GOOS),windows)
+  TARGET := $(BIN_DIR)/$(APP)-windows-$(GOARCH).exe
+endif
+TARGET ?= $(BIN_DIR)/$(APP)
+
+.PHONY: tidy
+tidy:
+	$(GO) mod tidy
+
+.PHONY: build
+build:
+	mkdir -p $(BIN_DIR)
+	GOOS=$(GOOS) GOARCH=$(GOARCH) $(GO) build -ldflags "$(LDFLAGS)" -o $(TARGET) ./cmd/poc-server
+	@echo "built: $(TARGET)"
+
+.PHONY: run
+run: build
+	X0GP_DEV_MODE=true X0GP_LOG_LEVEL=debug ./$(TARGET)
+
+.PHONY: proto
+proto:
+	@echo "Regenerating protobuf Go code via buf in Docker..."
+	docker run --rm -v "$$PWD":/workspace -w /workspace bufbuild/buf:latest generate
+	@echo "Done. Generated code is in proto/gen/."
+
+.PHONY: test
+test:
+	$(GO) test ./... -race -count=1
+
+.PHONY: lint
+lint:
+	$(GO) vet ./...
+	@command -v golangci-lint >/dev/null && golangci-lint run || echo "(golangci-lint not installed, skipping)"
+
+.PHONY: docker
+docker:
+	docker build -t x0gp/api-gateway:dev -f Dockerfile .
+
+.PHONY: compose-up
+compose-up:
+	docker compose up -d
+
+.PHONY: compose-down
+compose-down:
+	docker compose down
+
+.PHONY: clean
+clean:
+	rm -rf $(BIN_DIR)
+
+.DEFAULT_GOAL := build