Skip to main content

AI Tutor

A student opens AI Tutor, types or speaks a question about something they're studying, and gets a streamed answer from the assistant. Each query spends coins from their inventory. When they run out, they request more from a parent or the school admin via the Request Coins flow.

At a glance​

Who can do thisStudents only (in the student app). Teachers have their own separate AI Assistant — see Distinguishing from teacher AI below.
Where it livesStudent app /dashboard/ai-tutor (text chat) · /dashboard/voice-interaction (voice mode). Coin requests at /dashboard/req-coin.
Cost~2 coins per AI query, debited from the student's coin balance
Triggers notifications?Coin requests trigger parent/admin notifications — not the chat itself
Related featuresCoins & Credits · Doubts (the human alternative) · Notifications

How it flows​

State lifecycle (a single chat turn)​

If a brand-new conversation fails on the very first reply, the freshly-created conversation is auto-deleted so the sidebar doesn't fill with empty threads.

Step-by-step​

1. Open AI Tutor (text mode)​

  • App / route: Student app → /dashboard/ai-tutor.
  • Header shows: AI bot avatar, "AI Tutor" title (or current conversation title), an "Online · Ready" indicator, the coin balance pill (e.g. "220+"), and a conversations sidebar toggle.
  • The chat area opens with a welcome bubble: "Welcome! I am your AI Tutor. Feel free to ask me any questions about your studies, and I will help you understand the concepts better."
  • Three suggestion chips at the bottom (only when no user message yet): Explain a concept, Solve a problem, Quiz me.

2. Send a message​

  • The student types in the input bar and hits Enter (or taps Send).
  • Optimistic UI: the user bubble appears immediately on the right.
  • The reply streams from the backend:
    • First, a status ping ("Thinking...", or a tool-status string) appears in an italic ghost bubble.
    • On first token, a fresh assistant bubble appears and tokens append into it live.
    • If the assistant invokes a tool mid-reply, the current bubble closes and a new bubble starts after the tool finishes.
    • Markdown is rendered (bold, lists, code, links). Internal links of the form /dashboard/... are intercepted and route inside the app instead of opening externally.
  • On complete, the conversation list is refreshed so the just-active thread bubbles to the top of the sidebar.

3. Conversations sidebar​

  • Toggled by the messages-square icon in the top-right.
  • New Chat button at the top — creates a fresh conversation (active conversation set to undefined; first message in the new chat triggers conversation creation server-side).
  • List of past conversations with relative timestamps ("Just now", "5m ago", "3d ago", etc.).
  • Per-row actions on hover/active: rename (pencil) and delete (trash). Delete is immediate; the active conversation falls back to a new chat if deleted.
  • Text size slider at the bottom (12 – 20 px). Persisted to localStorage under ai-tutor-font-size.

4. Voice mode​

  • Tap the audio-lines button at the right of the input row → routes to /dashboard/voice-interaction.
  • Header mirrors the text page (AI avatar, "Voice Tutor", "Listening mode" label, coin balance pill).
  • Mic and video toggles available; voice mode lets the student speak the question and hear the answer.
  • Back arrow returns to /dashboard/ai-tutor.

5. What kinds of questions​

  • Curriculum-aligned subject help: "Explain photosynthesis", "Solve x² + 5x + 6 = 0", "Quiz me on the French Revolution", etc.
  • Concept walk-throughs and step-by-step problem solving.
  • Quizzes / practice questions on demand.
  • The assistant has tools wired in (visible only via "Thinking..." status pings). Replies are markdown-formatted, so tables / lists / code blocks render properly.

6. Coin spend & top-up​

  • Each completed query debits roughly 2 coins from the student's inventory. The coin balance pill in the header is the live indicator.
  • When the student wants more, they go to /dashboard/req-coin:
    • AI Access info card: "Coins are used to ask AI questions and get explanations." · "1 AI query ≈ 2 coins".
    • Pick a preset (250 is the default highlight) or enter a custom amount.
    • Type a purpose (required) — e.g. "Need more coins for revision".
    • Submit → routed back to the dashboard, request type ai_coins.
  • The parent / school admin sees the request and approves or denies; on approval the coin balance updates. Full lifecycle is in Coins & Credits.

Distinguishing from the teacher AI Assistant​

  • AI Tutor lives in the student app at /dashboard/ai-tutor. It is coin-metered and tuned for a learner's voice ("Welcome! I am your AI Tutor…", suggestion chips like "Quiz me").
  • The teacher app has its own /dashboard/ai-tutor route, but it is the teacher's AI Assistant — used for grading, lesson planning, content drafting, etc., not the same surface as the student's tutor.
  • The two are not interchangeable: a teacher logging into the student app will not see the teacher Assistant, and vice versa.

Edge cases & things to test​

  • Streaming interrupted mid-reply: kill the network during a reply — the in-flight bubble must not stay stuck on "..."; an error bubble should replace it ("Sorry, something went wrong. Please try again.") and isStreaming must reset so the next message is sendable.
  • First reply fails on a new conversation: confirm the auto-created conversation is rolled back (deleted) instead of leaving an empty thread in the sidebar.
  • Send while already streaming: the input is disabled with placeholder "AI is responding..."; pressing Enter again does nothing.
  • Markdown links: /dashboard/... links inside replies route in-app; external https:// links should still open in the browser/new tab.
  • Conversation rename: rename to whitespace-only — should be ignored. Rename to a valid title — sidebar updates immediately, header title updates if the conversation is active.
  • Delete the active conversation: the chat area should reset to the welcome bubble; sidebar removes the row.
  • Suggestion chip after a real message: chips should disappear once any user message exists — only show on a fresh empty thread.
  • Text-size slider: drag, release — value should persist across reload (localStorage).
  • Initial message handoff: opening AI Tutor with an initialMessage (e.g. from "Explain this homework") should auto-send once and not re-fire on re-renders.
  • Voice mic permission denied: mic permission rejected → state should not lock up; user can still navigate back to text mode.
  • Coin balance hits 0: confirm the UX path when a query is attempted with insufficient coins — student should be nudged to /dashboard/req-coin.
  • Coin request validation: zero / negative coin amounts blocked; empty purpose blocked client-side.
  • Multiple devices: open AI Tutor on phone + laptop → starting a chat on one should reflect in the other's sidebar after refresh.
  • Long responses: ask for a 1,000-word essay — confirm the chat container auto-scrolls to bottom as tokens arrive and doesn't jump back when the user scrolls up to read earlier text.
  • Markdown-heavy reply: code fences, tables, math — render without overflow on small screens.
  • Coins & Credits — full economy: how students earn, request, and spend coins
  • Doubts — slower, human alternative when the student wants a real teacher's voice
  • Notifications — coin requests fan out to parents/admins