Implement leaderboard service and POC HTTP handlers with Swagger documentation

server/internal/transport/codec.go

@@ -839,6 +839,29 @@ type RaceResultMsg struct {
 	FinishedAtMs int64  `json:"finished_at_ms"`
 }
 
+// LeaderboardEntry is a single row in the paginated leaderboard response.
+type LeaderboardEntry struct {
+	DriverID  string `json:"driver_id" example:"driver-seed-001"`
+	Nickname  string `json:"nickname" example:"ACE"`
+	Name      string `json:"name" example:"Alice"`
+	AvatarURL string `json:"avatar_url" example:"https://cdn.example.com/u/ace.png"`
+	ClanID    string `json:"clan_id,omitempty" example:"clan-seed-001"`
+	ClanTag   string `json:"clan_tag,omitempty" example:"ACE"`
+	Points     int    `json:"points" example:"25"`
+	BestPos    *int   `json:"best_pos,omitempty" example:"1"` // Only populated for track-specific leaderboard
+	BestTimeMs *int64 `json:"best_time_ms,omitempty" example:"15000"`
+	Rank       int    `json:"rank" example:"1"`
+}
+
+// LeaderboardResponse is the paginated response for GET /api/leaderboard.
+type LeaderboardResponse struct {
+	Items         []LeaderboardEntry `json:"items"`
+	Total         int                `json:"total" example:"8"`
+	Limit         int                `json:"limit" example:"50"`
+	Offset        int                `json:"offset" example:"0"`
+	CurrentDriver *LeaderboardEntry  `json:"current_driver,omitempty"`
+}
+
 // Encode marshals an envelope to JSON bytes.
 func Encode(env *Envelope) ([]byte, error) {
 	if env.TSMs == 0 {