Skip to main content

Coins & Credits Economy

Scholiphi runs on two parallel virtual currencies. AI coins unlock the AI Tutor (~2 coins per query). Teacher credits unlock paid teacher interactions. Students request more from the admin, parents top up coins via Razorpay, and admin sets the conversion rate.

At a glance​

Two currenciesAI coins (ai_coins) — for AI Tutor queries · Teacher credits (teacher_credit) — for paid teacher interactions
Who can do thisStudents request both · Parents buy AI coins for their child · Admins approve requests & set pricing
Where it livesStudent app /dashboard/req-coin, /dashboard/req-credits · Parent app /buy-coins · Admin /dashboard/school/:id/req-coin (token approval) and /dashboard/coin-pricing
Triggers notifications?Yes — on approval / rejection / successful top-up
Related featuresAI Tutor · Homework · Notifications

How it flows​

The economy has four phases — Earn, Request, Buy, Spend — and only the last is mandatory for a student to use AI features. The other three are alternative ways to fill the wallet.

Phase 1 — Earn (passive top-ups)​

Phase 2 — Request (student asks admin)​

Phase 3 — Buy (parent pays for child)​

Phase 4 — Spend (mainly AI Tutor)​

Status lifecycle​

The status machine below applies to a token request (the Request phase). Buy and Earn are point-in-time events without intermediate states.

Admin's token-approval table labels these as Reviewing, Authorized, Declined.

Step-by-step​

1. Student requests AI coins​

  • App / route: Student app → /dashboard/req-coin.
  • Form fields:
    • Quick amount: +100, +250, +500 (default selection: 250).
    • Enter coins: free-form numeric input with + / - steppers.
    • Purpose: required free-text (e.g. "exam prep").
  • Live summary: shows estimated AI queries (coins / 2) and the typed purpose.
  • On Send Request → request enters pending, student is navigated back to /dashboard.

2. Student requests teacher credits​

  • App / route: Student app → /dashboard/req-credits.
  • Same form shape as the coin request, but requestType = teacher_credit. The summary line reads "Estimated teacher queries" instead of AI queries.

3. Admin reviews requests​

  • App / route: Admin → /dashboard/school/:id/req-coin (page title: Asset Allocation Registry). See Token Approval for the full admin walkthrough.
  • Admin sees a paginated table with: requester, asset class (AI Coins / Teacher Credit), volume, status, timeline, actions.
  • Filters: search by student, request-type filter, status filter (pending / approved / rejected / cancelled), date range picker.
  • Actions on a pending row:
    • Authorize — flips to approved; balance is credited.
    • Decline — confirmation modal, flips to rejected with reason "Transaction declined by administration".
  • Tapping a non-pending row opens a detail modal with the requester's "Operational Rationale" and reviewer info.

4. Parent buys AI coins for their child​

  • App / route: Parent app → /buy-coins.
  • Load:
    • Pulls all linked students from the parent's profile.
    • Pulls live coin pricing (coinsPerRupee, minPurchaseRupees, maxPurchaseRupees, isEnabled).
    • If isEnabled is false, the page renders "Coin purchases are currently unavailable."
  • UI:
    • Selected child's current coin balance (yellow card).
    • Child selector chip row (only if multiple children are linked).
    • Enter amount (₹) input with quick presets ₹50 / ₹100 / ₹250 / ₹500 / ₹1000 (presets outside min/max are filtered out).
    • Order summary: child, coins received (amount × coinsPerRupee), total ₹.
    • Rate tag in the header: "₹1 = N coins".
  • Pay button: disabled until amount is a positive integer between min and max.
  • On tap: opens hosted Razorpay checkout via openCheckoutUrl. After successful payment, the child's aiCoins balance increases.

5. Admin sets pricing​

  • App / route: Admin → /dashboard/coin-pricing (Coin Pricing page).
  • Editable: Coins per ₹1, Min purchase (₹), Max purchase (₹), Currency, Enabled toggle.
  • Validation: min ≤ max; rate > 0.01.
  • Switching off "Enabled" hides the buy flow for parents.

6. Student spends on AI Tutor​

  • App / route: Student app → /dashboard/ai-tutor (or wherever the AI Tutor button surfaces).
  • The header shows a coin chip (e.g. 220+) next to the conversations icon.
  • Each AI query costs roughly 2 coins (per the on-screen hint on the Request Coins page).
  • When balance is insufficient, the student is funnelled toward Request Coins / parent top-up.

Edge cases & things to test​

  • Zero / negative input: Send Request button stays disabled when numberOfCoins ≤ 0.
  • Empty purpose: blocked client-side with a toast.
  • Out-of-range parent amount: parent enters ₹10 when min is ₹50 → toast "Amount must be between ₹X and ₹Y".
  • Pricing disabled mid-session: parent loads /buy-coins with prices enabled, admin disables → next reload should show the "unavailable" state.
  • Multi-child parent: top up Child A, ensure Child B's balance does not change. Selected child should persist across re-loads when navigated from a child profile (location.state.studentProfileId).
  • Concurrent approvals: two admins authorize the same pending request — only one credit should land.
  • Request after rejection: student creates a new request after a rejection — should appear as a new pending row, not edit the old one.
  • Decimal amounts: parent types ₹50.5 — should be stripped to 50 (input filters non-digits).
  • Razorpay failure / cancel: parent opens checkout then cancels — no coins added, no error toast on return.
  • Notification fan-out on approval: student gets push + in-app notification with the new balance reflected in real time.
  • Admin filter persistence: setting status = approved and changing pages should keep the filter and reset to page 1 only when filters change.
  • AI Tutor with empty wallet: send a query at 0 coins — flow should block before streaming, not after.
  • Coin chip refresh: after a successful Razorpay top-up, the student's AI Tutor coin chip should update without a hard refresh.
  • Earn-on-activity attribution: completing a chapter test should credit coins exactly once (no double-credit on retake).