refactor: extract shuffleArray to lib/utils, rename correctAnswers to terms

documentation/tickets/t00003.md

@@ -0,0 +1,37 @@
+# refactor: extract shuffleArray to lib/utils, rename correctAnswers to terms
+
+## Problem
+
+Two readability issues in `gameService.ts`:
+
+1. `shuffle` was defined as a private function at the bottom of `gameService.ts`, after the function that calls it. It is a pure generic utility with no dependency on game domain logic, so it had no business living there.
+
+2. The variable holding terms fetched from the database was named `correctAnswers`. These are word pairs — they only become "correct answers" once options are built around them. The name was premature and misleading.
+
+## Options considered
+
+### Option A — Move `shuffle` up in the same file
+
+Simple, no new files. Fixes the ordering issue but keeps a generic utility buried in domain code.
+
+### Option B — Extract to `lib/utils.ts` ✅
+
+Move `shuffle` (renamed `shuffleArray`) to `apps/api/src/lib/utils.ts` and import it. Cleaner separation: domain logic stays in services, generic utilities live in `lib/`.
+
+Chosen because `lib/` already exists, the function is reusable, and it gives future utilities a home.
+
+## Solution
+
+- Created `apps/api/src/lib/utils.ts` with `shuffleArray`
+- Renamed `shuffle` → `shuffleArray` for clarity at the call site
+- Removed the inline `shuffle` from `gameService.ts` and imported from `lib/utils.ts`
+- Renamed `correctAnswers` → `terms` and `correctAnswer` → `term` throughout `gameService.ts`
+
+## Files changed
+
+- `apps/api/src/lib/utils.ts` — created
+- `apps/api/src/services/gameService.ts` — removed `shuffle`, updated import, renamed variables
+
+## Commit
+
+`refactor: extract shuffleArray to lib/utils, rename correctAnswers to terms`