knowfoolery/docs/4_work_plan/2.4-leaderboard-service.md

# 2.4 Leaderboard Service (Port 8083) - Detailed Implementation Plan

## Summary
Implement the Leaderboard Service as the read-optimized ranking and statistics service for game outcomes, consistent with implementation decisions used in `2.1` (Question Bank), `2.2` (User), and `2.3` (Game Session).

Runtime stack and conventions:
- Fiber HTTP service with shared bootstrap and observability.
- PostgreSQL persistence with `EnsureSchema(ctx)` startup DDL.
- Redis for read-optimized ranking cache and top-10 acceleration.
- Shared `backend/shared` packages for auth, errors, validation, logging, tracing, metrics, and readiness.

Scope boundary:
- Modify only `backend/services/leaderboard-service/**`.
- Do not modify `backend/services/*` other than leaderboard-service.
- Do not modify `backend/shared/**`.

## Decisions Reused from 2.1, 2.2, and 2.3
1. Service composition pattern:
- `internal/infra/config.FromEnv()`
- logger/metrics/tracer initialization in `cmd/main.go`
- repository initialization + `EnsureSchema(ctx)` at startup
- `/health`, `/ready`, `/metrics` registration
- route registration via `internal/interfaces/http/routes.go`

2. Persistence and state pattern:
- PostgreSQL as source of truth.
- Redis as optional performance layer, non-fatal when unavailable.
- service remains functional on PostgreSQL when Redis is down.

3. Error and transport pattern:
- domain/application errors mapped via shared `httputil.SendError`.
- standard response envelope style (`success`, `data`) used by existing services.

4. Inter-service integration approach:
- HTTP adapters with application interfaces so transport can evolve later without domain changes.
- explicit DTOs for upstream/downstream contracts.

5. Test pyramid:
- unit tests for ranking/statistics logic.
- HTTP integration tests with in-memory doubles/fakes.
- optional DB-backed integration tests gated by environment.

## Objectives
1. Provide public leaderboard query endpoints:
- top 10 scores
- player ranking and history
- global statistics
2. Provide internal score ingestion endpoint for completed sessions.
3. Ensure deterministic ranking:
- sort by score descending, then completion duration ascending, then completed_at ascending.
4. Maintain historical score records for analytics and auditability.
5. Deliver production-ready observability, readiness checks, and test coverage.

## API Endpoints
- `GET /leaderboard/top10`
- `GET /leaderboard/players/:id`
- `GET /leaderboard/stats`
- `POST /leaderboard/update` (internal command endpoint)

## Auth and Access Rules
1. Query endpoints:
- `GET /leaderboard/top10`, `GET /leaderboard/stats` are public read endpoints.
- `GET /leaderboard/players/:id` requires auth; user can read own detailed history.
- Admin role may read any player history.
2. Update endpoint:
- `POST /leaderboard/update` is internal-only and requires service/admin auth middleware.
- Reject anonymous or non-privileged callers.

## Inter-Service Contracts

### Game Session dependency
Purpose: ingest canonical final session outcomes.

Contract for `POST /leaderboard/update` request:
- `session_id` (string, required)
- `player_id` (string, required)
- `player_name` (string, required)
- `total_score` (int, required, >= 0)
- `questions_asked` (int, required, >= 0)
- `questions_correct` (int, required, >= 0)
- `hints_used` (int, required, >= 0)
- `duration_seconds` (int, required, >= 0)
- `completed_at` (RFC3339 timestamp, required)
- `completion_type` (`completed|timed_out|abandoned`, required)

Idempotency decision:
- deduplicate on `session_id` (unique).
- repeated update for same `session_id` returns success with existing persisted record.

### User Service dependency
Purpose: optional profile hydration fallback for player display fields.

Decision:
- leaderboard update request is authoritative for `player_name` to avoid hard runtime coupling.
- optional future enrichment can call `GET /users/:id`, but is not required for step `2.4`.

## Domain Model
Aggregates:
- `LeaderboardEntry` (one per completed session)
- `PlayerRankingSnapshot` (derived read model)

Value objects:
- `Rank` (positive integer)
- `SuccessRate` (0..100 percentage)
- `CompletionType`

Domain services:
- `RankingService` (ordering and tie-breaks)
- `StatisticsService` (global aggregates)

Core invariants:
1. Each `session_id` can be ingested once.
2. Score cannot be negative.
3. Questions counts cannot be negative.
4. `questions_correct <= questions_asked`.
5. Rank ordering rule is deterministic:
- score desc
- duration asc
- completed_at asc
6. Top10 response always returns at most 10 entries.

## Data Model (PostgreSQL)

### `leaderboard_entries`
- `id UUID PRIMARY KEY`
- `session_id VARCHAR(64) NOT NULL UNIQUE`
- `player_id VARCHAR(128) NOT NULL`
- `player_name VARCHAR(50) NOT NULL`
- `score INT NOT NULL`
- `questions_asked INT NOT NULL`
- `questions_correct INT NOT NULL`
- `hints_used INT NOT NULL DEFAULT 0`
- `duration_seconds INT NOT NULL`
- `success_rate NUMERIC(5,2) NOT NULL`
- `completion_type VARCHAR(16) NOT NULL`
- `completed_at TIMESTAMPTZ NOT NULL`
- `created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()`

Indexes:
- `(score DESC, duration_seconds ASC, completed_at ASC)`
- `(player_id, completed_at DESC)`
- `(completion_type, completed_at DESC)`
- `(created_at DESC)`

### `leaderboard_player_stats`
Pre-aggregated player read model for fast rank/profile reads.
- `player_id VARCHAR(128) PRIMARY KEY`
- `player_name VARCHAR(50) NOT NULL`
- `games_played INT NOT NULL DEFAULT 0`
- `games_completed INT NOT NULL DEFAULT 0`
- `total_score BIGINT NOT NULL DEFAULT 0`
- `best_score INT NOT NULL DEFAULT 0`
- `avg_score NUMERIC(10,2) NOT NULL DEFAULT 0`
- `avg_success_rate NUMERIC(5,2) NOT NULL DEFAULT 0`
- `total_questions BIGINT NOT NULL DEFAULT 0`
- `total_correct BIGINT NOT NULL DEFAULT 0`
- `best_duration_seconds INT NULL`
- `last_played_at TIMESTAMPTZ NULL`
- `updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()`

Indexes:
- `(best_score DESC, best_duration_seconds ASC, last_played_at ASC)`
- `(last_played_at DESC)`

Note:
- all write updates to `leaderboard_player_stats` happen transactionally with `leaderboard_entries` insert in the same repository method.

## Redis Usage
Key prefix: `lb:`

Keys:
- `lb:top10:v1` -> serialized top10 payload (TTL cache)
- `lb:rank:{player_id}` -> cached player rank snapshot
- `lb:stats:global:v1` -> cached global stats payload
- `lb:zset:scores` -> sorted set score index (optional acceleration, non-authoritative)

Rules:
1. PostgreSQL remains source of truth.
2. On successful update ingestion:
- invalidate `lb:top10:v1`
- invalidate `lb:stats:global:v1`
- invalidate `lb:rank:{player_id}`
- best-effort Redis operations; failures logged and counted, not fatal.
3. If Redis is unavailable:
- query endpoints compute from PostgreSQL and still return success.
- readiness check marks Redis as down but optional.

## Endpoint Behavior (Decision Complete)

### `POST /leaderboard/update`
Input: final session outcome payload (see contract above).

Flow:
1. authenticate internal caller.
2. validate input fields and invariants.
3. start transaction.
4. check existing by `session_id`.
5. if existing:
- return existing normalized entry response (`200`, idempotent success).
6. insert into `leaderboard_entries`.
7. upsert/refresh `leaderboard_player_stats` aggregate.
8. commit transaction.
9. invalidate related Redis caches.
10. emit structured log + metrics counter.

Output:
- persisted leaderboard entry summary including computed `success_rate`.

### `GET /leaderboard/top10`
Query params:
- optional `completion_type` filter (`completed|timed_out|abandoned`)
- optional `window` (`24h|7d|30d|all`, default `all`)

Flow:
1. attempt Redis cache hit for matching key variant.
2. on miss, query PostgreSQL ordered by ranking rule.
3. compute rank values (1..N), cap at 10.
4. cache result with short TTL.

Output:
- ordered top list with rank, player_id, player_name, score, questions_asked, success_rate, duration_seconds, completed_at.

### `GET /leaderboard/players/:id`
Auth:
- self or admin.

Query params:
- `page` (default 1)
- `page_size` (default 20, max 100)

Flow:
1. auth and ownership/admin check.
2. fetch player aggregate from `leaderboard_player_stats`.
3. fetch paginated history from `leaderboard_entries`.
4. compute current global rank from ordering criteria against all players using `best_score` then tie-breakers.

Output:
- player summary:
  - current_rank, games_played, best_score, avg_score, avg_success_rate, total_score
- paginated history list.

### `GET /leaderboard/stats`
Flow:
1. attempt Redis cache hit.
2. on miss, aggregate from PostgreSQL.

Returned stats:
- `total_games`
- `total_players`
- `avg_score`
- `avg_success_rate`
- `max_score`
- `score_p50`, `score_p90`, `score_p99`
- `updated_at`

## Package Layout
- `backend/services/leaderboard-service/cmd/main.go`
- `backend/services/leaderboard-service/internal/infra/config/config.go`
- `backend/services/leaderboard-service/internal/domain/leaderboard/`
- `backend/services/leaderboard-service/internal/application/leaderboard/`
- `backend/services/leaderboard-service/internal/infra/persistence/ent/`
- `backend/services/leaderboard-service/internal/infra/state/`
- `backend/services/leaderboard-service/internal/interfaces/http/`
- `backend/services/leaderboard-service/tests/`

## Configuration
Service-specific:
- `LEADERBOARD_PORT` (default `8083`)
- `LEADERBOARD_TOP_LIMIT` (default `10`)
- `LEADERBOARD_PLAYER_HISTORY_DEFAULT_LIMIT` (default `20`)
- `LEADERBOARD_PLAYER_HISTORY_MAX_LIMIT` (default `100`)
- `LEADERBOARD_CACHE_TTL` (default `60s`)
- `LEADERBOARD_UPDATE_REQUIRE_AUTH` (default `true`)

Optional integration:
- `GAME_SESSION_BASE_URL` (default `http://localhost:8080`) for future backfill tooling
- `UPSTREAM_HTTP_TIMEOUT` (default `3s`)

Shared:
- `POSTGRES_*`, `REDIS_*`, `TRACING_*`, `METRICS_*`, `LOG_LEVEL`, `ZITADEL_*`

## Implementation Work Breakdown

### Workstream A - Bootstrap, config, wiring
1. Add `internal/infra/config/config.go` env parsing.
2. Wire logger/metrics/tracer in `cmd/main.go`.
3. Initialize postgres + redis clients.
4. Initialize repository and `EnsureSchema(ctx)`.
5. Register `/health`, `/ready`, `/metrics`.
6. Build auth middleware and register routes.

### Workstream B - Domain and application
1. Define domain entities, value objects, and domain errors.
2. Implement ranking and statistics calculation services.
3. Implement application use-cases:
- `UpdateScore`
- `GetTop10`
- `GetPlayerRanking`
- `GetGlobalStats`

### Workstream C - Persistence
1. Implement repository interfaces and SQL-backed repository.
2. Add `EnsureSchema(ctx)` DDL for both tables and indexes.
3. Implement transactional ingestion:
- insert entry
- upsert player stats
4. Implement top10/history/stats query methods.

### Workstream D - HTTP interface
1. Add request/response DTOs with validation tags.
2. Implement handlers with shared error mapping.
3. Apply ownership/admin checks for player history endpoint.
4. Keep response envelope consistent with existing services.

### Workstream E - Cache and read optimization
1. Add Redis cache adapter for top10/stats/rank snapshots.
2. Implement cache keys, invalidation, and graceful fallback.
3. Add counters for cache hit/miss and invalidation failures.

### Workstream F - Testing
1. Unit tests:
- ranking tie-break correctness
- success-rate calculation
- stats aggregate math
- update idempotency behavior
2. HTTP integration tests:
- update + top10 happy path
- duplicate update idempotency
- player endpoint auth guards
- stats endpoint and metrics availability
3. Optional DB-backed tests (env-gated):
- schema creation
- transactional consistency
- unique `session_id` constraint

## Error Handling Contract
- `400`: invalid input or invariant violation
- `401`: missing/invalid auth for protected endpoints
- `403`: ownership/admin violation
- `404`: player not found (for player ranking endpoint)
- `409`: conflicting update (non-idempotent invalid duplicate payload scenario)
- `500`: unexpected internal failures

## Observability
1. Structured logs:
- include `session_id`, `player_id`, endpoint, and operation outcome.
- avoid PII-heavy payload logging.
2. Metrics:
- `leaderboard_updates_total{status}`
- `leaderboard_top10_requests_total{cache}`
- `leaderboard_player_requests_total{status}`
- `leaderboard_stats_requests_total{cache}`
- `leaderboard_update_latency_seconds`
3. Tracing:
- endpoint -> application -> repository/cache spans.
- include attributes for cache hit/miss and DB query class.

## Delivery Sequence (3-4 Days)
1. Day 1: bootstrap/config + schema + repository scaffolding.
2. Day 2: `POST /leaderboard/update` transactional ingestion + cache invalidation.
3. Day 3: query endpoints (`top10`, `players/:id`, `stats`) + auth checks.
4. Day 4: tests, observability hardening, bugfix buffer.

## Verification Commands
From `backend/services/leaderboard-service`:
```bash
go test ./...
go vet ./...
```

Optional workspace-level check from `backend`:
```bash
go test ./...
```

## Definition of Done
1. All four endpoints implemented and route protection rules enforced.
2. Ranking order and tie-break behavior matches functional requirement.
3. Update ingestion is idempotent by `session_id`.
4. `/health`, `/ready`, `/metrics` functional with meaningful checks.
5. Redis cache fallback behavior works when Redis is unavailable.
6. `go test ./...` and `go vet ./...` pass for leaderboard-service.
7. No code changes outside `backend/services/leaderboard-service/**`.

## Assumptions and Defaults
1. Inter-service transport remains HTTP in phase 2.
2. Leaderboard consistency can be eventual within seconds.
3. `POST /leaderboard/update` is called by internal trusted workflow after session termination.
4. No changes are made in other services or `backend/shared` during this step.