Dattavani Backend: Gamification Diagram

Coins, XP, level, rings, streak, activity_logs and weekly_summary all change inside update_daily_stats_rpc, in one SQL function call.
Python only decides the amounts. Call gamification_service.update_daily_stats with them; do not update kid_profiles directly.
Every amount comes from points_config (activity_type + key) with fallbacks in xp_constants.py. Python caches points_config for 30 minutes.

daily_stats has four flags: learning_done, quiz_done, story_done, ask_tataji_done.
The streak counts a day only when learning, quiz and Ask Tataji are all done. Story is not part of the streak.
On the day the third ring closes, the kid gets streak XP plus milestone coins and XP at days 3, 7, 14 and 30. The milestone cycle repeats every 30 days.
get_effective_streak returns 0 when the last streak day is older than yesterday. kid_profiles.streak is not reset by a missed day.

Ranks are computed live from weekly_summary.total_xp for the current ISO week. Equal XP shares a rank (DENSE_RANK), top 20 ranks, global and by parent city.
Nothing resets the board. A new week_id simply starts empty. The Monday job run_leaderboard_rank only sends the reset notification.
GET /api/leaderboard also writes: it increments kid_profiles.leaderboard_visit_count.
Levels come from xp_levels via sync_kid_level_from_xp, run whenever XP is added through the RPC.

Badge coins and XP are added by a read-then-update on kid_profiles. A concurrent update_daily_stats_rpc can overwrite one of the two writes.
Badge XP skips weekly_summary, activity_logs and the level sync. It never counts on the leaderboard and does not level the kid up until the next XP write.
Duplicate awards are blocked by the user_badges_award_dedup_uidx unique index; an insert error is treated as already earned.
Migration 20260708120000 runs DELETE FROM user_badges. Re-applying it to a live database wipes every earned badge.

Amounts: points_config rows (seeded in supabase/seed.sql). Quiz XP math: xp_engine.compute_quiz_xp_from_score.
Streak and bonus logic: a new migration that replaces update_daily_stats_rpc. Three migrations already redefine it; the 20260703120000 one is live.
GET /api/kids/track-activity sets one ring flag with no XP. It is a GET that writes, so never let a cache or prefetch replay it.
Promo codes extend membership, not coins; see 09-access-and-limits.html.