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/internal/drivers/service.go

@@ -0,0 +1,110 @@
+package drivers
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+	"time"
+
+	"github.com/jackc/pgx/v5/pgconn"
+)
+
+// Service composes validation on top of PgStore.
+type Service struct {
+	pg  *PgStore
+	now func() time.Time
+}
+
+// NewService wires a service.
+func NewService(pg *PgStore) *Service {
+	return &Service{pg: pg, now: time.Now}
+}
+
+// CreateInput is what the HTTP handler hands to the service.
+type CreateInput struct {
+	ID        string
+	Nickname  string
+	Name      string
+	AvatarURL string
+	ClanID    string
+}
+
+// Create validates and inserts a driver.
+func (s *Service) Create(ctx context.Context, in CreateInput) (Driver, error) {
+	nick := strings.ToUpper(strings.TrimSpace(in.Nickname))
+	if !IsValidNickname(nick) {
+		return Driver{}, fmt.Errorf("%w: nickname must be 3 uppercase ASCII letters", ErrInvalidInput)
+	}
+	name := strings.TrimSpace(in.Name)
+	if name == "" {
+		return Driver{}, fmt.Errorf("%w: name required", ErrInvalidInput)
+	}
+	d := Driver{
+		ID:        in.ID,
+		Nickname:  nick,
+		Name:      name,
+		AvatarURL: in.AvatarURL,
+		ClanID:    in.ClanID,
+	}
+	if d.ID == "" {
+		d.ID = fmt.Sprintf("driver-%d-%d", s.now().UnixMilli(), time.Now().UnixNano()%1000)
+	}
+	if err := s.pg.Create(ctx, d); err != nil {
+		var pgErr *pgconn.PgError
+		if errors.As(err, &pgErr) && pgErr.Code == "23505" {
+			return Driver{}, fmt.Errorf("%w: %s", ErrAlreadyExists, nick)
+		}
+		return Driver{}, err
+	}
+	return s.pg.Get(ctx, d.ID)
+}
+
+// Get loads a driver by id.
+func (s *Service) Get(ctx context.Context, id string) (Driver, error) {
+	return s.pg.Get(ctx, id)
+}
+
+// GetByNickname loads a driver by nickname.
+func (s *Service) GetByNickname(ctx context.Context, nick string) (Driver, error) {
+	nick = strings.ToUpper(strings.TrimSpace(nick))
+	return s.pg.GetByNickname(ctx, nick)
+}
+
+// List returns drivers with limit/offset and optional clan filter.
+func (s *Service) List(ctx context.Context, limit, offset int, clanID string) ([]Driver, error) {
+	return s.pg.List(ctx, limit, offset, clanID)
+}
+
+// UpdateInput is the patch payload.
+type UpdateInput struct {
+	Name      string
+	AvatarURL string
+	ClanID    *string // nil = leave unchanged, &"" = clear, &"..." = set
+}
+
+// Update applies a partial patch.
+func (s *Service) Update(ctx context.Context, id string, in UpdateInput) (Driver, error) {
+	cur, err := s.pg.Get(ctx, id)
+	if err != nil {
+		return Driver{}, err
+	}
+	if in.Name != "" {
+		cur.Name = in.Name
+	}
+	if in.AvatarURL != "" {
+		cur.AvatarURL = in.AvatarURL
+	}
+	if in.ClanID != nil {
+		cur.ClanID = *in.ClanID
+	}
+	if err := s.pg.Update(ctx, cur); err != nil {
+		return Driver{}, err
+	}
+	return s.pg.Get(ctx, id)
+}
+
+// Delete removes a driver.
+func (s *Service) Delete(ctx context.Context, id string) error {
+	return s.pg.Delete(ctx, id)
+}