x0gp/server/CODEBASE.md

x0gp Go Codebase Map (Generated)

This file contains a compiled map of all packages, structures, interfaces, and public functions in the server directory. It is optimized for token-efficiency so AI agents and humans can understand the codebase layout without reading all files.

Package main (cmd/poc-server)

HTTP handlers for the catalog (tracks + cars).

All HTTP routes live under /api/*: GET /api/tracks list tracks (optional ?scope=system|public|private&tag=) GET /api/tracks/{id} get a single track POST /api/tracks create a track PUT /api/tracks/{id} update a track DELETE /api/tracks/{id} delete a track GET /api/cars list cars (optional ?scope=...&owner_id=...) GET /api/cars/{id} get a single car POST /api/cars create a car PUT /api/cars/{id} update a car DELETE /api/cars/{id} delete a car GET /api/catalog combined snapshot + summary

WebSocket access is wired up directly in main.go's readPump switch.

Structs

• struct Hub
• struct UDPVideoService
• struct WebRTCService

Functions

• func NewHub(*slog.Logger) *Hub
• func NewUDPVideoService(*slog.Logger, string, int) *UDPVideoService
• func NewWebRTCService(*slog.Logger, *control.Engine, *lobby.Service, *UDPVideoService, *catalog.Service) *WebRTCService

Methods

• func (*catalogBroadcaster) Run()
• func (*catalogBroadcaster) Stop()
• func (*Hub) BroadcastSnapshot(transport.RaceSnapshot)
• func (*statusRecorder) WriteHeader(int)
• func (*statusRecorder) Hijack() (net.Conn, *bufio.ReadWriter, error)
• func (*UDPVideoService) Start(context.Context, *sync.WaitGroup)
• func (*UDPVideoService) SendControlPacket(uint8, []byte) error
• func (*UDPVideoService) SendCommand(uint8, string) error
• func (*UDPVideoService) StreamHandler() http.HandlerFunc
• func (*UDPVideoService) ControlHandler() http.HandlerFunc
• func (*WebRTCService) Start(context.Context, *sync.WaitGroup)
• func (*WebRTCService) ConnectHandler() http.HandlerFunc
• func (*WebRTCService) CloseSession(string)
• func (*WebRTCService) CloseAll()

---

Package clans (internal/clans)

Package clans owns persistence and business logic for clans.

A clan has a unique 3-letter tag (A-Z, uppercase, exactly 3 chars), a name, and an optional avatar URL. Drivers reference a clan via a nullable FK (see internal/drivers).

Interfaces

• interface Store { Exec, Create, Get, GetByTag, List, Delete, Update, Count }

Structs

• struct Service
• struct CreateInput { ID, Tag, Name, AvatarURL }
• struct UpdateInput { Name, AvatarURL }
• struct Clan { ID, Tag, Name, AvatarURL, CreatedMs, UpdatedMs }
• struct PgStore

Functions

• func NewService(Store) *Service
• func IsValidTag(string) bool
• func NewPgStore(*pgxpool.Pool) *PgStore

Methods

• func (*Service) Create(context.Context, CreateInput) (Clan, error)
• func (*Service) Get(context.Context, string) (Clan, error)
• func (*Service) GetByTag(context.Context, string) (Clan, error)
• func (*Service) List(context.Context, int, int) ([]Clan, error)
• func (*Service) Update(context.Context, string, UpdateInput) (Clan, error)
• func (*Service) Delete(context.Context, string) error
• func (*PgStore) Exec(context.Context, string) (int64, error)
• func (*PgStore) Create(context.Context, Clan) error
• func (*PgStore) Get(context.Context, string) (Clan, error)
• func (*PgStore) GetByTag(context.Context, string) (Clan, error)
• func (*PgStore) List(context.Context, int, int) ([]Clan, error)
• func (*PgStore) Delete(context.Context, string) error
• func (*PgStore) Update(context.Context, Clan) error
• func (*PgStore) Count(context.Context) (int, error)

---

Package lobby (internal/lobby)

Package lobby owns the "outside any race" state of the server: which races are open, which drivers are connected but idle, who is the host of each race.

The lobby is the single source of truth for matchmaking and for rendering the "what races are available right now" list. It does NOT own per-race physics — that's the Engine (internal/control).

All operations are thread-safe. Mutations broadcast a snapshot event to subscribers (see Service.Subscribe).

Interfaces

• interface Persistence { UpsertRace, DeleteRace, AddDriver, RemoveDriver, SetRaceStatus, UpsertDriver, DeleteDriver }

Structs

• struct CreateRaceOptions { ID, Name, TrackID, MaxCars, Laps, TimeLimitS }
• struct RaceMeta { ID, Name, TrackID, MaxCars, Laps, TimeLimitS, DriverIDs, Status, CreatedMs, StartedMs }
• struct DriverMeta { ID, Name, Nickname, AvatarURL, ClanID, ClanTag, Status, RaceID, ConnectedMs, LastSeenMs, Country, AvatarHue, CarID }
• struct Snapshot { GeneratedMs, Races, Drivers, Version }
• struct Stats { RacesTotal, RacesOpen, RacesActive, DriversIdle, DriversTotal }
• struct Service

Functions

• func NewService() *Service

Methods

• func (*Service) CreateRace(CreateRaceOptions) (RaceMeta, error)
• func (*Service) AddRace(RaceMeta)
• func (*Service) AddDriver(string, string, string) (DriverMeta, error)
• func (*Service) RemoveDriver(string)
• func (*Service) Heartbeat(string)
• func (*Service) SetDriverProfile(string, string, string, string, string)
• func (*Service) AddDriverToRace(string, string) error
• func (*Service) RemoveDriverFromRace(string)
• func (*Service) SetRaceStatus(string, RaceStatus) error
• func (*Service) DeleteRace(string) error
• func (*Service) QuickPlay(string, int) (RaceMeta, error)
• func (*Service) GetRace(string) (RaceMeta, error)
• func (*Service) GetDriver(string) (DriverMeta, error)
• func (*Service) SelectCar(string, *string) error
• func (*Service) ListRaces() []RaceMeta
• func (*Service) ListDrivers() []DriverMeta
• func (*Service) SetPersistence(Persistence)
• func (*Service) SetRaceLifecycleHook(func, func)
• func (*Service) Subscribe() (?, func)
• func (*Service) Stop()
• func (*Service) Done() ?
• func (*Service) Snapshot() Snapshot
• func (*Service) Stats() Stats

---

Package races (internal/races)

Package races owns the cross-cutting "race list" surface: keyset-paginated listing of live and finished races, upcoming (next-N) selection, the driver-to-race queue and the recurring race-plan scheduler.

The package composes two storage backends:

• lobby.Service (in-memory): authoritative source for active races (status = lobby | countdown | racing). Used directly for the live page of /api/races, for the upcoming view and for the scheduler materialisation.
• Postgres (pgxpool): authoritative for finished races (snapshotted on SetRaceStatus(finished)), for race plans and for the queue. Finished races are read with keyset pagination on (finished_ms DESC, id DESC).

Structs

• struct Cursor { Ms, ID }
• struct LeaderboardEntry { DriverID, Name, Nickname, AvatarURL, ClanID, ClanTag, Points, BestPos, BestTimeMs, Rank }
• struct LeaderboardResult { Items, Total, CurrentDriver }
• struct TrackCalendarInfo { ID, TrackID, TrackName, StartAt, EndAt }
• struct TrackCalendarLeaderboard { TrackID, TrackName, StartAt, EndAt, Status, Podium, CurrentDriver }
• struct LiveStore
• struct Service
• struct ListFilter { Statuses, TrackID, Cursor, Limit }
• struct RaceItem { Source, Meta, Podium }
• struct ListResult { Items, NextCursor, TotalCount }
• struct UpcomingItem { Meta, QueueLen, PlanID, StartAtMs }
• struct JoinUpcomingResult { Joined, Skipped }
• struct SnapshotFinished { Meta, FinishedMs, TotalLaps, WinnerDriverID, WinnerName, BestLapMs, Results }
• struct CreatePlanInput { ID, Name, TrackID, MaxCars, Laps, TimeLimitS, StartAtMs, IntervalS, Count, Enabled }
• struct Scheduler
• struct PodiumEntry { Position, DriverID, Name, TotalTimeMs, Nickname, AvatarUrl, ClanID }
• struct DriverResult { DriverID, Name, TotalTimeMs, BestLapMs, Position, Nickname, AvatarUrl, ClanID }
• struct FinishedRace { ID, Name, TrackID, MaxCars, Laps, TimeLimitS, DriverIDs, Status, CreatedMs, StartedMs, FinishedMs, DurationMs, TotalLaps, TotalDrivers, Results, WinnerDriverID, WinnerName, BestLapMs, Podium }
• struct RacePlan { ID, Name, TrackID, MaxCars, Laps, TimeLimitS, StartAtMs, IntervalS, Count, Enabled, CreatedMs, UpdatedMs, NextFireMs, FiresDone }
• struct QueueEntry { DriverID, RaceID, PlanID, EnqueuedMs }
• struct PgStore
• struct DriverStats { TotalRacesStarted, TotalRacesFinished, Wins, Podiums, BestLapMs, TotalPlaytimeMs }
• struct DriverRaceSummary { RaceID, RaceName, FinishedMs, Position, TotalTimeMs, BestLapMs, TrackID, TrackName }

Functions

• func DecodeCursor(string) (Cursor, error)
• func NewLiveStore(*PgStore) *LiveStore
• func NewService(*PgStore, *lobby.Service) *Service
• func NewScheduler(*PgStore, *lobby.Service, time.Duration) *Scheduler
• func NewPgStore(*pgxpool.Pool) *PgStore
• func ParseStatusFilter(string) ([]StatusFilter, error)

Methods

• func (Cursor) String() string
• func (Cursor) IsZero() bool
• func (Cursor) Encode() string
• func (*PgStore) GetTrackLeaderboard(context.Context, string, int, int, int) ([]LeaderboardEntry, int, error)
• func (*PgStore) GetTrackLeaderboardDriver(context.Context, string, int, string) (*LeaderboardEntry, error)
• func (*PgStore) GetOverallLeaderboard(context.Context, int, int, int) ([]LeaderboardEntry, int, error)
• func (*PgStore) GetOverallLeaderboardDriver(context.Context, int, string) (*LeaderboardEntry, error)
• func (*PgStore) GetDriverLeaderboardProfile(context.Context, string) (*LeaderboardEntry, error)
• func (*PgStore) GetCalendarLeaderboardTracks(context.Context) ([]TrackCalendarInfo, error)
• func (*LiveStore) UpsertRace(context.Context, lobby.RaceMeta) error
• func (*LiveStore) DeleteRace(context.Context, string) error
• func (*LiveStore) AddDriver(context.Context, string, string, int) error
• func (*LiveStore) RemoveDriver(context.Context, string, string) error
• func (*LiveStore) SetRaceStatus(context.Context, string, lobby.RaceStatus, int64) error
• func (*LiveStore) UpsertDriver(context.Context, lobby.DriverMeta) error
• func (*LiveStore) DeleteDriver(context.Context, string) error
• func (*LiveStore) ListAllRaces(context.Context) ([]lobby.RaceMeta, error)
• func (*LiveStore) ListAllDrivers(context.Context) ([]lobby.DriverMeta, error)
• func (*LiveStore) ListLivePaged(context.Context, []string, string, Cursor, int) ([]lobby.RaceMeta, error)
• func (*LiveStore) ListUpcoming(context.Context, int) ([]lobby.RaceMeta, error)
• func (*LiveStore) Exec(context.Context, string) (int64, error)
• func (*Service) SetLiveStore(*LiveStore)
• func (*Service) RestoreFromDB(context.Context) (int, int, error)
• func (*Service) SetMaxUpcoming(int)
• func (*Service) ListRaces(context.Context, ListFilter) (ListResult, error)
• func (*Service) Upcoming(context.Context, int) ([]UpcomingItem, error)
• func (*Service) JoinUpcoming(context.Context, string, int) (JoinUpcomingResult, error)
• func (*Service) LeaveQueue(context.Context, string, string) error
• func (*Service) ListQueue(context.Context, string) ([]QueueEntry, error)
• func (*Service) PersistFinished(context.Context, SnapshotFinished) error
• func (*Service) CreatePlan(context.Context, CreatePlanInput) (RacePlan, error)
• func (*Service) ListPlans(context.Context, Cursor, int) ([]RacePlan, error)
• func (*Service) CountPlans(context.Context) (int, error)
• func (*Service) DeletePlan(context.Context, string) error
• func (*Service) GetLeaderboard(context.Context, string, int, int, int, string) (*LeaderboardResult, error)
• func (*Service) GetCalendarLeaderboard(context.Context, int, string) ([]TrackCalendarLeaderboard, error)
• func (*Service) GetRace(context.Context, string) (FinishedRace, error)
• func (*Service) GetLastFinished(context.Context) (FinishedRace, error)
• func (*Service) GetDriverProfileStats(context.Context, string) (DriverStats, *DriverRaceSummary, *DriverRaceSummary, error)
• func (*Scheduler) Run(context.Context)
• func (*Scheduler) Stop()
• func (*Scheduler) Done() ?
• func (*PgStore) Exec(context.Context, string, ?) (int64, error)
• func (*PgStore) ListTrackIDs(context.Context) ([]string, error)
• func (*PgStore) UpsertLive(context.Context, lobby.RaceMeta) error
• func (*PgStore) DeleteLive(context.Context, string) error
• func (*PgStore) AddLiveDriver(context.Context, string, string, int) error
• func (*PgStore) RemoveLiveDriver(context.Context, string, string) error
• func (*PgStore) SetLiveStatus(context.Context, string, lobby.RaceStatus, int64) error
• func (*PgStore) ListLivePaged(context.Context, []string, string, Cursor, int) ([]lobby.RaceMeta, error)
• func (*PgStore) ListLiveUpcoming(context.Context, int) ([]lobby.RaceMeta, error)
• func (*PgStore) GetLive(context.Context, string) (lobby.RaceMeta, error)
• func (*PgStore) ListAllRaces(context.Context) ([]lobby.RaceMeta, error)
• func (*PgStore) UpsertLobbyDriver(context.Context, lobby.DriverMeta) error
• func (*PgStore) DeleteLobbyDriver(context.Context, string) error
• func (*PgStore) ListLobbyDrivers(context.Context) ([]lobby.DriverMeta, error)
• func (*PgStore) InsertFinished(context.Context, FinishedRace) error
• func (*PgStore) ListFinished(context.Context, string, Cursor, int) ([]FinishedRace, error)
• func (*PgStore) CountRaces(context.Context, []string, string) (int, error)
• func (*PgStore) GetFinished(context.Context, string) (FinishedRace, error)
• func (*PgStore) GetLastFinished(context.Context) (FinishedRace, error)
• func (*PgStore) CreatePlan(context.Context, RacePlan) error
• func (*PgStore) GetPlan(context.Context, string) (RacePlan, error)
• func (*PgStore) ListPlans(context.Context, Cursor, int) ([]RacePlan, error)
• func (*PgStore) CountPlans(context.Context) (int, error)
• func (*PgStore) DeletePlan(context.Context, string) error
• func (*PgStore) SetPlanEnabled(context.Context, string, bool) error
• func (*PgStore) AdvancePlan(context.Context, string, int64) error
• func (*PgStore) DuePlans(context.Context, int64, int) ([]RacePlan, error)
• func (*PgStore) Enqueue(context.Context, string, string, string) (QueueEntry, error)
• func (*PgStore) Dequeue(context.Context, string, string) error
• func (*PgStore) ListQueueByDriver(context.Context, string) ([]QueueEntry, error)
• func (*PgStore) ListQueueByRace(context.Context, string) ([]QueueEntry, error)
• func (*PgStore) CountQueueByRace(context.Context, string) (int, error)
• func (FinishedRace) ToLobbyMeta() lobby.RaceMeta
• func (*PgStore) GetDriverStats(context.Context, string) (DriverStats, error)
• func (*PgStore) GetDriverLastRace(context.Context, string) (*DriverRaceSummary, error)
• func (*PgStore) GetDriverBestRace(context.Context, string) (*DriverRaceSummary, error)

---

Package main (scripts/genseed)

Package main contains the genseed utility. It is built into a standalone binary via go build ./scripts/genseed and is not part of the runtime.

Usage:

go run ./scripts/genseed seeds.json > 002_seed.sql

It reads the JSON dump produced by DUMP_SEEDS=1 go test ./internal/catalog and emits ON CONFLICT-safe INSERTs for the catalog tables.

---

Package main (scripts/genseed-json)

Package main contains a small helper that prints the default seeds (5 F1 tracks + 5 F1 cars) as JSON to stdout. It is run as:

go run ./scripts/genseed-json > seeds.json

which is then fed into scripts/genseed to regenerate the SQL.

---

Package main (scripts/graphify)

Package main is the graphify utility. It walks the codebase, parses Go AST, and outputs a highly compact symbol summary to server/CODEBASE.md. This is used for token savings and helping developers/AI agents quickly map out imports and structures.

Structs

• struct PackageSummary { Name, Path, Doc, Structs, Interfaces, Functions, Methods }

---

Package auth (internal/auth)

Package auth handles Supabase JWT validation and HTTP middleware.

Structs

• struct Claims { DriverID, Email }

Functions

• func ValidateJWT(string, string) (Claims, error)
• func Middleware(string, bool) func
• func DriverIDFromContext(context.Context) (string, bool)
• func EmailFromContext(context.Context) (string, bool)

---

Package main (.)

Smoke test: ws client connects, exchanges a few messages, exits. Run: go run ./smoke_test.go

---

Package seeddefs (internal/catalog/seeddefs)

Package seeddefs holds the canonical seed definitions for tracks and cars. It lives in its own package (no postgres dependencies) so both the catalog tests and the scripts/genseed SQL generator can consume the same source-of-truth data.

Structs

• struct Waypoint { X, Y, HeadingRad, SpeedMs, Curvature }
• struct Bounds { MinX, MinY, MaxX, MaxY, LengthM, WidthM }
• struct Track { ID, Name, Description, AuthorID, Visibility, Scale, LengthM, WidthM, LaneWidthM, Surface, Tags, Centerline, Bounds, BestLapMs, BestLapHolder }
• struct Chassis { Model, Material, Printed, WheelbaseMm, TrackMm }
• struct Motor { Kind, Class, KV, PowerW }
• struct Battery { VoltageV, CapacityMah, Cells, Chemistry }
• struct Car { ID, Name, OwnerID, Visibility, Scale, LengthMm, WidthMm, HeightMm, WeightG, Chassis, Motor, Battery, Drive, TopSpeedMs, ColorHex, Active, TotalDistanceM, TotalRaces, TotalLaps, BestLapMs }

Functions

• func DefaultTracks() []Track
• func DefaultCars() []Car
• func Monaco() Track
• func BarcelonaCatalunya() Track
• func AustriaRedBullRing() Track
• func GreatBritainSilverstone() Track
• func BelgiumSpa() Track
• func RedBullRB20() Car
• func FerrariSF24() Car
• func McLarenMCL38() Car
• func MercedesW15() Car
• func AstonMartinAMR24() Car
• func ComputeBounds([]Waypoint) Bounds

---

Package control (internal/control)

Package control owns the authoritative race state.

For PoC, the physics model is intentionally simple (no tire slip, no collision): each car integrates position from (throttle, brake, steering). Realistic physics, anti-cheat checks, and CV-based ground truth will be added in MVP / production phases.

Structs

• struct Car { ID, DriverID, DriverName, DeviceID, X, Y, Heading, Speed, Lap, Sector, LastLapMs, BestLapMs, DNF, AppliedSteering, AppliedThrottle, AppliedBrake }
• struct Engine

Functions

• func NewEngine(int) *Engine

Methods

• func (RacePhase) String() string
• func (*Car) ApplyInput(transport.InputState, float64)
• func (*Car) Snapshot() transport.CarInfo
• func (*Engine) Snapshots() ?
• func (*Engine) Phase() RacePhase
• func (*Engine) SetPhase(RacePhase)
• func (*Engine) AddCar(string, string, int, *int) (*Car, error)
• func (*Engine) RemoveCar(string)
• func (*Engine) GetCarByDriver(string) *Car
• func (*Engine) Run(context.Context)
• func (*Engine) Stop()

---

Package drivers (internal/drivers)

Package drivers owns persistence and business logic for drivers (racers). Each driver has a unique 3-letter nickname (A-Z, uppercase, exactly 3 chars), a name, an optional avatar URL and an optional clan reference.

Interfaces

• interface Store { Exec, Create, Get, GetByNickname, List, Delete, Update, Count }

Structs

• struct Service
• struct CreateInput { ID, Nickname, Name, AvatarURL, ClanID }
• struct UpdateInput { Nickname, Name, AvatarURL, ClanID }
• struct Driver { ID, Nickname, Name, AvatarURL, ClanID, CreatedMs, UpdatedMs }
• struct PgStore

Functions

• func NewService(Store) *Service
• func IsValidNickname(string) bool
• func NewPgStore(*pgxpool.Pool) *PgStore

Methods

• func (*Service) Create(context.Context, CreateInput) (Driver, error)
• func (*Service) Get(context.Context, string) (Driver, error)
• func (*Service) GetByNickname(context.Context, string) (Driver, error)
• func (*Service) List(context.Context, int, int, string) ([]Driver, error)
• func (*Service) Update(context.Context, string, UpdateInput) (Driver, error)
• func (*Service) Delete(context.Context, string) error
• func (*PgStore) Exec(context.Context, string) (int64, error)
• func (*PgStore) Create(context.Context, Driver) error
• func (*PgStore) Get(context.Context, string) (Driver, error)
• func (*PgStore) GetByNickname(context.Context, string) (Driver, error)
• func (*PgStore) List(context.Context, int, int, string) ([]Driver, error)
• func (*PgStore) Update(context.Context, Driver) error
• func (*PgStore) Delete(context.Context, string) error
• func (*PgStore) Count(context.Context) (int, error)

---

Package realtime (internal/realtime)

Package realtime manages WebSocket connections: registration, fan-out of race snapshots, and per-client send queues with backpressure handling.

Structs

• struct Client { ID, Send, SessionID, Done, DriverID, LastUDPCommand }
• struct Hub
• struct Stats { Connections, DropsTotal }

Functions

• func NewHub() *Hub
• func MustEnvelope(transport.MessageType, any) *transport.Envelope

Methods

• func (*Client) Close()
• func (*Hub) Stats() Stats
• func (*Hub) Register(*Client)
• func (*Hub) Unregister(*Client)
• func (*Hub) Run(context.Context)
• func (*Hub) Stop()
• func (*Hub) Publish(*transport.Envelope)

---

Package catalog (internal/catalog)

Package catalog owns the static configuration entities: tracks and cars. Both are first-class resources that drivers browse, pick, and (in later phases) author.

PoC: in-memory cache backed by a pluggable Store. The runtime uses postgres.PgStore so tracks / cars survive restarts. The cache is the source of truth for read paths; the Store is the source of truth for durability. Mutations go through the Store, then refresh the cache.

Design constraints come from the user's apartment layout:

• largest room: 4.46 m × 3.19 m (446 × 319 cm)
• car scale: 1/27 (Compact)
• printer: Bambu A1 (220×220×250 mm build volume)

Tracks are sized to fit a 4.5 × 3.2 m bounding box with a safety margin, which keeps them physically realizable in the apartment. Cars are sized to a 1/27 touring envelope (~80 × 35 × 25 mm).

Interfaces

• interface Store { Load, UpsertTrack, DeleteTrack, UpsertCar, DeleteCar, UpdateCarStats, GetTrackCalendar, CreateTrackCalendar, DeleteTrackCalendar }

Structs

• struct CreateTrackOptions { ID, Name, Description, AuthorID, Visibility, Scale, LengthM, WidthM, LaneWidthM, Surface, Tags, Centerline }
• struct UpdateTrackOptions { Name, Description, Visibility, LengthM, WidthM, LaneWidthM, Surface, Tags, Centerline }
• struct CreateCarOptions { ID, Name, OwnerID, Visibility, Scale, LengthMm, WidthMm, HeightMm, WeightG, Chassis, Motor, Battery, Drive, TopSpeedMs, ColorHex, AvatarURL, Active, DeviceID }
• struct UpdateCarOptions { Name, Visibility, LengthMm, WidthMm, HeightMm, WeightG, TopSpeedMs, ColorHex, Active, Chassis, Motor, Battery, Drive, DeviceID }
• struct Waypoint { X, Y, HeadingRad, SpeedMs, Curvature }
• struct Bounds { MinX, MinY, MaxX, MaxY, LengthM, WidthM }
• struct TrackMeta { ID, Name, Description, AuthorID, Visibility, Scale, LengthM, WidthM, LaneWidthM, Bounds, Surface, Tags, Centerline, BestLapMs, BestLapHolder, CreatedMs, UpdatedMs }
• struct TrackCalendarEntry { ID, TrackID, StartAt, EndAt }
• struct MotorSpec { Kind, Class, KV, PowerW }
• struct BatterySpec { VoltageV, CapacityMah, Cells, Chemistry }
• struct ChassisSpec { Model, Material, Printed, WheelbaseMm, TrackMm }
• struct CarMeta { ID, Name, OwnerID, Visibility, Scale, LengthMm, WidthMm, HeightMm, WeightG, Chassis, Motor, Battery, Drive, DeviceID, TopSpeedMs, ColorHex, AvatarURL, Active, TotalDistanceM, TotalRaces, TotalLaps, BestLapMs, CreatedMs, UpdatedMs }
• struct Snapshot { GeneratedMs, Version, Tracks, Cars }
• struct Stats { TracksTotal, TracksSystem, TracksPublic, TracksPrivate, CarsTotal, CarsSystem, CarsPublic, CarsPrivate, CarsActive }
• struct Event { Kind, TrackID, CarID, Snapshot }
• struct Service

Functions

• func NewService(context.Context, Store) (*Service, error)

Methods

• func (CreateTrackOptions) Validate() error
• func (*Service) CreateTrack(context.Context, CreateTrackOptions) (TrackMeta, error)
• func (*Service) UpdateTrack(context.Context, string, UpdateTrackOptions) (TrackMeta, error)
• func (*Service) DeleteTrack(context.Context, string) error
• func (CreateCarOptions) Validate() error
• func (*Service) CreateCar(context.Context, CreateCarOptions) (CarMeta, error)
• func (*Service) UpdateCar(context.Context, string, UpdateCarOptions) (CarMeta, error)
• func (*Service) DeleteCar(context.Context, string) error
• func (*Service) SetCarStats(context.Context, string, func) error
• func (*Service) ListTracksByVisibility(Visibility) []TrackMeta
• func (*Service) ListCarsByVisibility(Visibility) []CarMeta
• func (*Service) ListCarsByOwner(string) []CarMeta
• func (*Service) GetTrackCalendar(context.Context) ([]TrackCalendarEntry, error)
• func (*Service) CreateTrackCalendar(context.Context, string, time.Time, time.Time) (TrackCalendarEntry, error)
• func (*Service) DeleteTrackCalendar(context.Context, int) error
• func (*memoryStore) Load(context.Context) ([]TrackMeta, []CarMeta, error)
• func (*memoryStore) UpsertTrack(context.Context, TrackMeta) error
• func (*memoryStore) DeleteTrack(context.Context, string) error
• func (*memoryStore) UpsertCar(context.Context, CarMeta) error
• func (*memoryStore) DeleteCar(context.Context, string) error
• func (*memoryStore) UpdateCarStats(context.Context, string, func) error
• func (*memoryStore) GetTrackCalendar(context.Context) ([]TrackCalendarEntry, error)
• func (*memoryStore) CreateTrackCalendar(context.Context, TrackCalendarEntry) (TrackCalendarEntry, error)
• func (*memoryStore) DeleteTrackCalendar(context.Context, int) error
• func (*Service) Subscribe() (?, func)
• func (*Service) Stop()
• func (*Service) Done() ?
• func (*Service) Snapshot() Snapshot
• func (*Service) Stats() Stats
• func (*Service) ListTracks() []TrackMeta
• func (*Service) ListCars() []CarMeta
• func (*Service) GetTrack(string) (TrackMeta, bool)
• func (*Service) GetCar(string) (CarMeta, bool)

---

Package config (internal/config)

Package config loads runtime configuration from environment variables.

On startup Load() reads a .env file (if present) from the current working directory and merges its values into the process environment. Existing process env vars take precedence over .env so deployments can override .env without modifying the file.

Structs

• struct Config { HTTPAddr, TickRate, TickInterval, LogLevel, MaxClients, SnapshotRate, DevMode, DatabaseURL, JWTSecret, UDPVideoAddr, ESPCmdPort }

Functions

• func Load() (*Config, error)

---

Package seed (internal/races/seed)

Structs

• struct DefaultCounts { Finished, Live, Plans }
• struct Options { Counts, Seed, Reset, Now }
• struct Summary { FinishedInserted, LiveCreated, PlansInserted, QueueInserted, Duration }
• struct Runner

Functions

• func NewRunner(*races.PgStore, *lobby.Service, *races.LiveStore, *clans.PgStore, *drivers.PgStore) *Runner

Methods

• func (*Runner) Run(context.Context, Options) (Summary, error)

---

Package stats (internal/stats)

Package stats collects and exposes server and per-driver metrics.

PoC: in-memory only, atomic counters where possible, mutex around driver and race records. The data lives for the lifetime of the process. A future storage layer will swap this for Postgres/Redis.

Public surface is split into:

• lifecycle hooks (Connect/Disconnect/Race*/Lap*/Input*/RTT) — called from cmd/poc-server and from internal/control and lobby
• Snapshot() — full server snapshot for /stats/detailed
• DriverProfile(id) — per-driver summary
• RecentLaps(n) — last N laps across all races

Structs

• struct ServerStats { StartedMs, UptimeMs, CurrentClients, PeakClients, TotalConnections, TotalDisconnects, TotalRacesCreated, TotalRacesStarted, TotalRacesFinished, TotalLapsRecorded, TotalInputsRecv, TotalSnapshotsSent, SnapshotsDropped, AvgRTTMs, RecentRTTs }
• struct DriverProfile { ID, Name, TotalRacesStarted, TotalRacesFinished, TotalLaps, BestLapMs, LastLapMs, TotalDistanceM, TotalPlaytimeMs, Wins, Podiums, LastSeenMs }
• struct LapRecord { RaceID, DriverID, LapMs, Sector1Ms, Sector2Ms, Sector3Ms, Position, TSMs }
• struct RaceResult { RaceID, DriverID, FinishedAtMs, Position, TotalLaps, BestLapMs, TotalTimeMs, DNF }
• struct Collector

Functions

• func NewCollector() *Collector

Methods

• func (*Collector) Start()
• func (*Collector) OnConnect(string, string)
• func (*Collector) OnDisconnect(string, int64)
• func (*Collector) OnRaceCreated()
• func (*Collector) OnRaceStarted([]string)
• func (*Collector) OnRaceFinished(RaceResult)
• func (*Collector) OnLapRecorded(LapRecord)
• func (*Collector) OnInputProcessed()
• func (*Collector) OnSnapshotSent(uint64, uint64)
• func (*Collector) OnRTT(int64)
• func (*Collector) OnDistance(string, float64)
• func (*Collector) Server() ServerStats
• func (*Collector) Driver(string, string) DriverProfile
• func (*Collector) Drivers() []DriverProfile
• func (*Collector) RecentLaps(int) []LapRecord
• func (*Collector) RecentResults(int) []RaceResult

---

Package postgres (internal/storage/postgres)

Package postgres owns the persistence layer of the catalog.

It exposes a *pgxpool.Pool plus a small set of repository helpers used by internal/catalog. Migrations are applied at startup from the SQL files in the migrations/ subdirectory.

Structs

• struct PgStore
• struct Config { URL, Host, Port, User, Password, Database, SSLMode, MaxConns, MinConns, ConnectTimeout }

Functions

• func NewPgStore(*pgxpool.Pool) *PgStore
• func Open(context.Context, Config) (*pgxpool.Pool, error)
• func Migrate(context.Context, *pgxpool.Pool) error

Methods

• func (*PgStore) Load(context.Context) ([]catalog.TrackMeta, []catalog.CarMeta, error)
• func (*PgStore) UpsertTrack(context.Context, catalog.TrackMeta) error
• func (*PgStore) DeleteTrack(context.Context, string) error
• func (*PgStore) UpsertCar(context.Context, catalog.CarMeta) error
• func (*PgStore) DeleteCar(context.Context, string) error
• func (*PgStore) UpdateCarStats(context.Context, string, func) error
• func (*PgStore) GetTrackCalendar(context.Context) ([]catalog.TrackCalendarEntry, error)
• func (*PgStore) CreateTrackCalendar(context.Context, catalog.TrackCalendarEntry) (catalog.TrackCalendarEntry, error)
• func (*PgStore) DeleteTrackCalendar(context.Context, int) error
• func (Config) DSN() (string, error)

---

Package transport (internal/transport)

Package transport defines the wire format between clients and the server.

PoC: JSON for fast iteration. Specified by proto/client_server.proto for the production binary protobuf format.

TODO PoC: replace JSON with protobuf-generated structs (see ../proto/client_server.proto).

Structs

• struct Envelope { Type, Seq, TSMs, Payload }
• struct ClientHello { Version, Token, Locale, ClientID }
• struct ServerHello { SessionID, RaceTick, ServerVersion, Config }
• struct JoinRace { RaceID, CarSlot, CarName }
• struct LeaveRace { RaceID }
• struct InputState { Steering, Throttle, Brake, Gear, Buttons }
• struct ChatMessage { Text }
• struct Ping { ClientTSMs }
• struct RaceSnapshot { Tick, TSMs, Elapsed, Cars }
• struct CarInfo { ID, DriverName, X, Y, Heading, Speed, Lap, Sector, LastLapMs, BestLapMs, InputApplied, DNF }
• struct InputAck { Seq, AppliedAtMs, ServerTickMs }
• struct Correction { Tick, DeltaSteering, DeltaThrottle, Reason }
• struct RaceEvent { RaceID, Event, CarID, Sector, LapMs, TSMs }
• struct Pong { ClientTSMs, ServerTSMs }
• struct ErrorMsg { Code, Message }
• struct LobbyRace { ID, Name, TrackID, MaxCars, Laps, TimeLimitS, DriverIDs, Status, CreatedMs, StartedMs, Podium }
• struct RacePodiumEntry { Position, DriverID, Name, TotalTimeMs, Nickname, AvatarUrl, ClanID }
• struct VersionResponse { Version }
• struct WebRTCConnectRequest { SDP, Type, DriverID }
• struct WebRTCConnectResponse { SDP, Type }
• struct LobbyDriver { ID, Name, Status, RaceID, ConnectedMs, LastSeenMs, Country, AvatarHue }
• struct LobbySnapshot { GeneratedMs, Version, Races, Drivers }
• struct LobbyCreate { RaceID, Name, TrackID, MaxCars, Laps, TimeLimitS }
• struct LobbyJoinRace { RaceID, CarSlot, CarName }
• struct LobbyLeaveRace { RaceID }
• struct LobbyKickDriver { RaceID, DriverID }
• struct LobbyDelete { RaceID }
• struct LobbyCreatedAck { Ok, Race, Error, Driver }
• struct LobbyJoinAck { Ok, Race, Error }
• struct TrackWaypoint { X, Y, HeadingRad, SpeedMs, Curvature }
• struct TrackBounds { MinX, MinY, MaxX, MaxY, LengthM, WidthM }
• struct TrackWire { ID, Name, Description, AuthorID, Visibility, Scale, LengthM, WidthM, LaneWidthM, Bounds, Surface, Tags, Centerline, BestLapMs, BestLapHolder, CreatedMs, UpdatedMs, IsActive }
• struct TrackListRequest { Scope, Tag }
• struct TrackGetRequest { ID }
• struct TrackCreateRequest { Track }
• struct TrackUpdateRequest { ID, Patch }
• struct TrackPatch { Name, Description, Visibility, Scale, LengthM, WidthM, LaneWidthM, Surface, Tags, Centerline }
• struct TrackDeleteRequest { ID }
• struct TrackSnapshot { GeneratedMs, Version, Tracks }
• struct TrackAck { Ok, ID, Error, Track }
• struct MotorWire { Kind, Class, KV, PowerW }
• struct BatteryWire { VoltageV, CapacityMah, Cells, Chemistry }
• struct ChassisWire { Model, Material, Printed, WheelbaseMm, TrackMm }
• struct CarWire { ID, Name, OwnerID, Visibility, Scale, LengthMm, WidthMm, HeightMm, WeightG, Chassis, Motor, Battery, Drive, TopSpeedMs, ColorHex, AvatarURL, Active, TotalDistanceM, TotalRaces, TotalLaps, BestLapMs, CreatedMs, UpdatedMs, DeviceID }
• struct CarListRequest { Scope, OwnerID }
• struct CarGetRequest { ID }
• struct CarCreateRequest { Car }
• struct CarUpdateRequest { ID, Patch }
• struct CarPatch { Name, Visibility, Scale, LengthMm, WidthMm, HeightMm, WeightG, Chassis, Motor, Battery, Drive, TopSpeedMs, ColorHex, AvatarURL, Active, DeviceID }
• struct CarDeleteRequest { ID }
• struct CarSnapshot { GeneratedMs, Version, Cars }
• struct CarAck { Ok, ID, Error, Car }
• struct CatalogSummary { TracksTotal, TracksSystem, TracksPublic, TracksPrivate, CarsTotal, CarsSystem, CarsPublic, CarsPrivate, CarsActive, TSMs }
• struct RaceListResponse { Items, NextCursor, Count }
• struct RaceUpcomingItem { Meta, QueueLen, PlanID, StartAtMs }
• struct RaceUpcomingResponse { Items, Count }
• struct RaceQueueEntry { DriverID, RaceID, PlanID, EnqueuedMs }
• struct RaceQueueJoinRequest { DriverID, Limit }
• struct RaceQueueJoinResponse { Joined, Skipped }
• struct RaceQueueListResponse { Items, Count }
• struct RacePlan { ID, Name, TrackID, MaxCars, Laps, TimeLimitS, StartAtMs, IntervalS, Count, Enabled, CreatedMs, UpdatedMs, NextFireMs, FiresDone }
• struct RacePlanCreateRequest { ID, Name, TrackID, MaxCars, Laps, TimeLimitS, StartAtMs, IntervalS, Count, Enabled }
• struct RacePlanListResponse { Items, NextCursor, Count }
• struct Driver { ID, Nickname, Name, AvatarURL, ClanID, CreatedMs, UpdatedMs }
• struct DriverCreateRequest { ID, Nickname, Name, AvatarURL, ClanID }
• struct DriverUpdateRequest { Nickname, Name, AvatarURL, ClanID }
• struct DriverProfileResponse { Driver, Stats, LastRace, BestRace }
• struct DriverStats { TotalRacesStarted, TotalRacesFinished, Wins, Podiums, BestLapMs, TotalPlaytimeMs }
• struct DriverRaceSummary { RaceID, RaceName, FinishedMs, Position, TotalTimeMs, BestLapMs, TrackID, TrackName }
• struct DriverListResponse { Items, Count }
• struct Clan { ID, Tag, Name, AvatarURL, CreatedMs, UpdatedMs }
• struct ClanCreateRequest { ID, Tag, Name, AvatarURL }
• struct ClanUpdateRequest { Name, AvatarURL }
• struct ClanListResponse { Items, Count }
• struct StatsServer { StartedMs, UptimeMs, CurrentClients, PeakClients, TotalConnections, TotalDisconnects, TotalRacesCreated, TotalRacesStarted, TotalRacesFinished, TotalLapsRecorded, TotalInputsRecv, TotalSnapshotsSent, SnapshotsDropped, AvgRTTMs }
• struct StatsDriver { ID, Name, TotalRacesStarted, TotalRacesFinished, TotalLaps, BestLapMs, LastLapMs, TotalDistanceM, TotalPlaytimeMs, Wins, Podiums, LastSeenMs }
• struct StatsLap { RaceID, DriverID, LapMs, Sector1Ms, Sector2Ms, Sector3Ms, Position, TSMs }
• struct StatsRaceResult { RaceID, DriverID, FinishedAtMs, Position, TotalLaps, BestLapMs, TotalTimeMs, DNF }
• struct StatsSnapshot { Server, Drivers, Laps, Results, TSMs }
• struct StatsRequest { Scope, TargetID }
• struct RaceStanding { Position, CarID, DriverID, DriverName, Lap, Sector, BestLapMs, LastLapMs, GapMs, DNF }
• struct RaceStandingsMsg { RaceID, Tick, TSMs, Lap, Elapsed, Rows }
• struct LapRecordedMsg { RaceID, DriverID, Lap, LapMs, Sector1Ms, Sector2Ms, Sector3Ms, TSMs, Position }
• struct RaceResultMsg { RaceID, DriverID, Position, TotalLaps, BestLapMs, TotalTimeMs, DNF, FinishedAtMs }
• struct LeaderboardEntry { DriverID, Nickname, Name, AvatarURL, ClanID, ClanTag, Points, BestPos, BestTimeMs, Rank }
• struct LeaderboardResponse { Items, Total, Limit, Offset, CurrentDriver }
• struct TrackCalendarEntry { ID, TrackID, StartAt, EndAt }
• struct TrackCalendarCreateRequest { TrackID, StartAt, EndAt }
• struct TrackCalendarResponse { Items }
• struct TrackCalendarLeaderboard { TrackID, TrackName, StartAt, EndAt, Status, Podium, CurrentDriver }
• struct TrackCalendarLeaderboardResponse { Items }

Functions

• func Encode(*Envelope) ([]byte, error)
• func Decode([]byte) (*Envelope, error)

---