ruwords-api

Backend API for RuWords.

Current scope:

• cmd/content — content delivery API (/content/v1/*)
• leaderboard MVP API (/v1/ranked-runs, /v1/leaderboards/*)
• daily boundary context API (/v1/daily-context)

Project layout

• cmd/content/ — HTTP server (content + leaderboard handlers)
• migrations/ — SQL migrations for leaderboard tables
• openapi.yaml — API contract
• deploy/ — Docker + Caddy deployment templates

Local run

Content-only mode (default)

CONTENT_ROOT=./content/prod \
PORT=8080 \
go run ./cmd/content serve

Content + leaderboard mode

LEADERBOARD_ENABLED=true \
LEADERBOARD_DATABASE_URL='postgres://analytics:password@127.0.0.1:5432/ruwords_staging?sslmode=disable' \
LEADERBOARD_BEARER_TOKEN='dev_token' \
CONTENT_ROOT=./content/prod \
PORT=8080 \
go run ./cmd/content serve

Validate release layout

go run ./cmd/content validate --root ./content/prod

Build and test

go fmt ./...
go test ./...
go build ./cmd/content

Leaderboard configuration

Environment variables:

• LEADERBOARD_ENABLED (default: false)
• LEADERBOARD_DATABASE_URL (required when enabled)
• LEADERBOARD_BEARER_TOKEN (required when enabled)
• LEADERBOARD_EXPECTED_QUESTION_COUNT (default: 15)
• LEADERBOARD_MAX_BODY_BYTES (default: 65536)
• LEADERBOARD_DEFAULT_LIMIT (default: 50)
• LEADERBOARD_MAX_LIMIT (default: 100)
• DAILY_RESET_TIMEZONE (default: Europe/Moscow)
• DAILY_RESET_HOUR (default: 0)
• DAILY_RESET_MINUTE (default: 0)

Daily context endpoint (GET /v1/daily-context) returns server-authoritative dayKey, nextResetAt, and secondsToReset for countdown UI and fair day rollover.

Migrations

Compatible with migrate/migrate:

migrate -path ./migrations -database "$LEADERBOARD_DATABASE_URL" up