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.

ARCHITECTURE.md

@@ -0,0 +1,223 @@
+# x0gp — Architecture Overview
+
+Корень проекта. Содержит общую картину системы, glossary и связи между
+подсистемами.
+
+Дата фиксации архитектурных решений: 2026-06-18.
+Дата обновления (Bambu A1, своё шасси, домашний сервер): 2026-06-18.
+Дата обновления v2 (Orange Pi 5 Pro + Coolify, Compact 1/27): 2026-06-18.
+
+---
+
+## 1. Что такое x0gp
+
+x0gp — это платформа для проведения **гонок на реальных радиоуправляемых
+машинках** через интернет. Игроки подключаются через Web (позже — мобильное
+приложение), платят за заезд/турнир и управляют физической машинкой в
+реальном времени.
+
+Целевой пользователь: гонщик-любитель 16-45 лет, желающий участвовать в
+реальных гонках без необходимости ехать в хобби-клуб.
+
+---
+
+## 2. Целевые метрики
+
+| Метрика | Цель |
+|---|---|
+| Round-trip команды (экран -> колёса) p50 | < 100 мс |
+| Round-trip команды p99 | < 200 мс |
+| Tick rate гонки | 60 Hz |
+| Одновременных активных заездов на Edge-инстанс | 50-100 |
+| Доступность | 99.5% (PoC) -> 99.9% (prod) |
+| Конверсия "регистрация -> первый заезд" | > 30% |
+| Стоимость инфраструктуры на 1 заезд/час | < 5 руб. (цель) |
+
+---
+
+## 3. Компоненты системы
+
+### 3.1. Слой клиента
+
+- **Web client** — React, Vite, TypeScript. WebSocket-клиент с
+  client-side prediction. Canvas/WebGL-рендер трассы и машинок.
+- **Mobile client** (фаза 5) — React Native, общий с Web протокол.
+- **Admin panel** — React + TanStack Table, управление трассами, турнирами,
+  пользователями.
+
+### 3.2. Edge-сервер (Go)
+
+- **api-gateway** — stateless, REST + WS-терминация, auth, rate-limit.
+- **race-engine** — stateful, authoritative tick 60 Hz, fan-out.
+- **agent-linker** — long-lived WS к бортовым агентам в помещении.
+- **indexer** — пайплайн телеметрии в TimescaleDB.
+- **replay-recorder** — пишет replay-чанки в S3.
+
+### 3.3. Локальная инфраструктура в помещении
+
+- **Gateway-агент (мини-ПК)** — Go-бинарь, держит связь с Edge-сервером
+  и машинками, выполняет CV-инференс, буферизует команды на случай обрыва WAN.
+- **Wi-Fi роутер** — выделенный SSID "x0gp-track", WPA3.
+- **Overhead-камеры** — 1-2 шт, 1080p 60 fps global shutter.
+- **IR-магнитные петли** — на секторах трассы.
+
+### 3.4. Борт машинки
+
+- **ESP32-S3 агент** — Wi-Fi, WebSocket к gateway, генерация команд ESC/серво.
+- **Brushless ESC + мотор** — 1/18 scale.
+- **Mini digital servo** — рулевое.
+- **IMU, IR/магнитные сенсоры** — телеметрия.
+
+### 3.5. Хранение
+
+- **PostgreSQL** — пользователи, платежи, гонки, турниры.
+- **Redis** — сессии, pub/sub, лобби, rate-limit.
+- **TimescaleDB** — телеметрия, replay-индекс.
+- **S3-совместимое** — replay-чанки (видео, JSON-логи).
+
+### 3.6. Observability
+
+- **Loki** — логи.
+- **Prometheus + Grafana** — метрики.
+- **Tempo / Jaeger** — трейсы.
+- **Sentry** — ошибки на клиенте и сервере.
+
+---
+
+## 4. Поток данных (упрощённый)
+
+```
+1. Игрок нажимает газ в браузере
+   |
+2. Web-client отправляет InputState{seq, tsMs, throttle: 1.0} по WS
+   |
+3. api-gateway принимает, валидирует, кладёт в Redis Stream "race:{id}:inputs"
+   |
+4. race-engine на ближайшем тике читает stream, применяет к state
+   |
+5. race-engine публикует RaceSnapshot в Redis pub/sub
+   |
+6. race-engine шлёт AgentCommand в agent-linker (WebSocket в помещение)
+   |
+7. agent-linker шлёт AgentCommand по WS на ESP32-S3 машинки
+   |
+8. ESP32-S3 выдаёт PWM на ESC и серво
+   |
+9. ESP32-S3 шлёт AgentTelemetry обратно (10-30 Hz)
+   |
+10. gateway-агент делает CV-инференс и шлёт CarFrame на сервер
+   |
+11. race-engine обновляет authoritative state, шлёт следующий Snapshot
+   |
+12. Web-client получает Snapshot, корректирует prediction, рисует кадр
+```
+
+Типичный round-trip: 50-120 мс (зависит от расстояния до Edge-сервера).
+
+---
+
+## 5. Модель доверия
+
+**Authoritative server**: истиной владеет сервер. Клиент может рендерить
+раньше (через client-side prediction), но любое решение о кругах, победах,
+позициях принимается сервером на основе данных от agent-linker (телеметрия
+ESP32 + CV).
+
+**Anti-cheat контур**: вход -> sanity check -> race-engine (state) ->
+agent-linker (CV) -> indexer (telemetry) -> admin (manual review).
+
+---
+
+## 6. Структура репозитория
+
+```
+x0gp/
+  ARCHITECTURE.md         # этот файл
+  README.md               # quickstart, how to run
+  server/                 # Go-код (см. server/PLAN.md)
+    PLAN.md
+    cmd/
+    internal/
+    proto/
+    migrations/
+    deploy/
+  hardware/               # CAD, спецификации, BOM (см. hardware/PLAN.md)
+    PLAN.md
+    cad/
+    bom/
+    photos/
+  web/                    # React-клиент (отдельный пакет)
+  mobile/                 # React Native (фаза 5)
+  ops/                    # общие devops-скрипты, конфиги
+  docs/                   # ADR, RFC, диаграммы
+    adr/
+    diagrams/
+```
+
+---
+
+## 7. Glossary
+
+| Термин | Значение |
+|---|---|
+| **Race** | Одна гонка: 2-12 игроков на трассе, общий старт, финиш по N кругов или по времени |
+| **Lobby** | Пре-гонка: игроки подключаются, выбирают машину, ждут старта |
+| **Tick** | 1 шаг симуляции (16.67 мс, 60 Hz) |
+| **Snapshot** | Полное состояние гонки на момент тика (позиции, скорости, круги) |
+| **Prediction** | Локальная симуляция у клиента между Snapshot'ами |
+| **Correction** | Сообщение сервера о расхождении клиентского prediction |
+| **Agent** | Софт на борту машинки (ESP32-S3) или в помещении (мини-ПК) |
+| **Edge** | Сервер в регионе, ближайшем к игрокам и помещению с трассой |
+| **Gateway-агент** | Локальный мини-ПК, "мост" между сервером и машинками в помещении |
+| **Track** | Физическая трасса + логическая (layout_id) |
+| **Class** | Класс машинки (1/18 Formula, 1/20 Mini и т.д.) |
+| **Sector** | Часть круга (1/3, 2/3) — IR-магнитная метка |
+| **DNF** | Did Not Finish — игрок не закончил гонку |
+| **DQF** | Disqualified — дисквалификация за нарушение |
+| **Replay** | Запись гонки для просмотра и разбора |
+
+---
+
+## 8. Ключевые ADR (Architecture Decision Records)
+
+Подробности — в `docs/adr/`. Здесь — сводка:
+
+- **ADR-001**: WebSocket + protobuf как основной транспорт.
+- **ADR-002**: Authoritative server + client-side prediction.
+- **ADR-003**: ESP32-S3 как бортовая MCU, MicroPython в PoC -> ESP-IDF в проде.
+- **ADR-004**: Гибрид IR-магнитные секторы + overhead-CV для позиционирования.
+- **ADR-005**: Масштаб машинки 1/18 (длина шасси 18-22 см), ширина полосы 30-40 см.
+- **ADR-006**: Edge + Gateway-агент: сервер не знает о Wi-Fi трассе, агент буферизует обрыв WAN.
+- **ADR-007**: Биллинг через ЮKassa (РФ) + Stripe (международный).
+- **ADR-008**: 3D-принтер **Bambu A1** как основной для производства шасси,
+  барьеров, маунтов, кузовов. Альтернатива — Bambu P1S при необходимости
+  enclosure для инженерных пластиков.
+- **ADR-009**: Шасси машинки **полностью своё**, спроектированное и
+  напечатанное на 3D-принтере. Не используем покупные донорские деки.
+- **ADR-010**: Edge-сервер в PoC и MVP работает на **домашнем сервере** с
+  доступом из интернета через Cloudflare Tunnel (default) или WireGuard.
+  Перенос на облако/VPS — только при появлении коммерческой нагрузки и
+  SLA обязательств.
+- **ADR-011**: Домашний сервер — **Orange Pi 5 Pro** (RK3588S, ARM64, 8 cores,
+  6 TOPS NPU, 2×2.5 GbE) с развёрнутым **Coolify** (self-hosted PaaS) для
+  деплоя и управления сервисами. NPU Orange Pi используется для CV-инференса
+  (YOLO/ByteTrack через RKNN Toolkit 2). LAN-порт Orange Pi изолирует сеть
+  трассы от домашней сети. Доступ из интернета — Caddy + Let's Encrypt
+  напрямую (статический IP от провайдера).
+- **ADR-012**: Масштаб машинки — **Compact 1/27** как primary класс
+  (длина шасси 13-15 см, wheelbase 100-115 мм, вес 150-220 г). Ширина полосы
+  трассы 20-25 см, рабочая зона трассы 200×130 см (помещается в комнату
+  446×319 см с запасом). Альтернативный класс — Standard 1/24 (16-18 см)
+  для тех, кому нужна чуть большая стабильность. Цель — минимизация площади
+  трассы и стоимости при сохранении управляемости 3D-печати.
+
+---
+
+## 9. Что дальше
+
+После фиксации плана — переход к **PoC**:
+1. Минимальный набор: 1 машинка, 1 трасса 100x60 см, 1 gateway-агент, 1 сервер.
+2. Цель: end-to-end "команда -> колёса крутятся, телеметрия возвращается".
+3. Срок: 1-2 недели.
+
+Детали — в `server/PLAN.md` (фаза S0) и `hardware/PLAN.md` (фаза H0).