Dattavani Backend: Learning Content Diagram

A book holds sections (learning_nodes), then chapters, scenes and chunks. A story holds scenes and chunks.
The v2 routes (/api/v2/learnings, /api/v2/stories) are the current path. The v1 /api/learnings and /api/stories routes are still mounted.
Every route needs a kid JWT. get_active_kid_context skips the database when the token already carries consent and kid_active claims.

The app calls POST /api/check-usage before opening a chapter or story. One RPC checks consent, membership, the kid's daily minutes and the trial cap.
Chunk complete re-checks membership and the trial cap inside v2_complete_chunk_progression_rpc, in the same database round-trip.
Quiz submit and story chunk complete do not check membership. They trust that check-usage ran first.
Detail on each gate: 09-access-and-limits.html.

Book content is cached in process memory for 300 s and the book list for 60 s. Progress is read fresh on every call.
Caches live per worker process. POST /api/learnings/internal/cache/invalidate clears only the v1 catalog caches in the worker that receives it, not this v2 content cache.
After an admin edit, expect up to 5 minutes of old content.
RPCs return R2 object paths. The app prefixes cdn_public_base_url from GET /api/config. utils/cdn_url.with_cdn_url exists but nothing calls it.

Every coin, XP point, ring and streak change goes through update_daily_stats_rpc. See 08-gamification.html.
Quiz submit computes rewards in Python, then writes quiz_submissions, chapter status and daily stats in one RPC. It is not retried, because a retry could insert a duplicate submission.
Epic intro XP (chapter order 0) is paid once per chapter, guarded by an activity_logs lookup inside the RPC.

update_daily_stats catches every error and returns success false. A failed story reward is only logged; the kid's story XP and ring are silently lost.
The chunk progression migration comment points to 20260717130000_v2_learnings_chunk_complete_trial_access.sql, which is not in this repo.
To change content reads, edit the RPCs in supabase/migrations and book_detail_v2_service.py together.