# Gamification spec

A lightweight points-and-badges layer that motivates weekly completion. There is
no separate progress service — points are written by the test flow and badges are
computed at render time.

- **Ledger:** the `leaderboard` collection
- **Award path:** `src/lib/testService.js → saveTestResult`
- **Display:** `src/pages/Leaderboard.jsx` (+ the Dashboard mini-leaderboard)

---

## Points

- **+2 points per correct quiz answer** (`pointsEarned = score * 2`).
- Written via `db.upsertLeaderboardEntry(userId, name, pointsDelta, testsCompletedDelta)`,
  which increments `points` and `tests_completed`.

`leaderboard` fields: `user_id`, `name`, `points`, `tests_completed`,
`learnings_completed` (reserved).

---

## Badges (computed at render time)

Defined in `Leaderboard.jsx`; not stored in the database:

| Badge | Condition |
|---|---|
| First Steps | `tests_completed > 0` |
| Veteran | `tests_completed >= 5` |
| Perfectionist | any test scored 100% (`perfectScores > 0`) |

---

## Leaderboard

- Admins are filtered out of the public board.
- All non-admin members appear, even with 0 points.
- Sorted by `points` descending; top 3 shown as a podium, the rest as a ranked list
  with their earned badges. The current user is highlighted.
- The Dashboard shows a compact top-3 + the viewer's rank.

---

## Notes & possible extensions

- The earlier design described developer-themed XP ("commits"), levels
  (Intern→Principal), weekly streaks, a GitHub-style heatmap, and public milestone
  cards. **None of those shipped** — the live system is the points + 3-badge model
  above.
- If extending: add fields to `leaderboard` (or a new collection + migration in
  `pb_migrations/`, mirrored in `scripts/setup-pb-collections.mjs`), increment them
  on the relevant completion events, and surface them in `Leaderboard.jsx`.