🎯 IELTS Guru — ieltsguru.ai

1Context, positioning & stack

IELTS Guru targets learners preparing for IELTS who want unlimited realistic practice and instant expert-level feedback without paying for the real exam or a private tutor. Positioning line: "AI Mentor for smart IELTS preparation" — the product claims AI Speaking/Writing grading at 1/50 the cost of the real exam. It serves three audiences at once: B2C self-study learners (Vietnam), international B2C learners (USD pricing via Polar), and B2B school tenants through white-label custom domains (including a dedicated ACCA tenant at acca.teado.ai).

• Brand & domains: the UI logo and SEO title say "IELTS GURU", but the codebase still canonicalizes every page to ielts.flyer.us; ieltsguru.ai serves the same app (its subdomain is on the first-party allow-list). Per-page SEO titles still carry the older name "FLYER IELTS Virtual Testing Platform" — a branding inconsistency to resolve (§13).
• Repo: standalone flyer/webs-ielts on Gitea (split from the flyer/webs monorepo with history preserved). Branch dev → dev env, main → staging, tags v*.*.* → production (currently v1.36.x line).
• Stack: Next.js 16.3.1 (Pages Router, Turbopack), React 19, TypeScript, Apollo Client (GraphQL v2 primary), TanStack Query + openapi-fetch (REST v3), Jotai, antd 5 + MUI 5 + Tailwind, next-translate (en/vi), Firebase (Auth, Analytics, Remote Config), Sentry (self-hosted), RecordRTC + wavesurfer/howler for audio, Rive/Lottie for animation, oxlint/oxfmt toolchain.
• Deploy: Docker (arm64) → ECR → EKS cluster flyer via Tanka/jsonnet; production HPA 2–5 replicas at 80% CPU; health checks on /api/ping; CI on Gitea Actions with Mattermost notifications.
• Companion apps: native iOS/Android app com.flyer.ielts (App Store id 1671502218) wired via universal links; teacher side lives in teacher.flyer.us (assignments, review); payments execute on exam.flyer.us checkout (VN) or Polar (US).

2Users & user stories

3Information architecture & routes

Single left-sidebar app shell (no footer). Locales: en (default, unprefixed) and /vi. Auth gating is soft: no middleware or server-side gate — anonymous visitors get a dismissible "please sign up" toast everywhere except a small exclude list, and the sidebar intercepts clicks on member-only items to open the sign-in modal.

Sidebar nav (desktop sidebar = mobile drawer): Mock tests → /, Study → /libraries, Missions, Mistakes, Vocabulary book, Learning profile, History; bottom block: Teacher role (opens teacher.flyer.us), Notifications popup, diamond counter → /diamonds-preview, avatar popup (Upgrade → /packages, Change interface, Active code, Switch profile, Edit profile, Log out).

4Content model & inventory

All content lives in the universal CheckPoint container shared across FLYER products, with per-skill IELTS part edges. Rendered question formats (MCQ, T/F/NG, matching, headings, form completion…) are all composed from just 3 detail primitives, driven by <blank id> placeholders inside contentHtml:

CheckPoint (test) ── time · maxGrade · diamond (AI cost) · isPremium · ieltsBand · topics
 ├─ IeltsListeningPart { audio, audioSubtitle (tapescript), expiredTime, questions[] }
 ├─ IeltsReadingPart   { contentHtml (passage), expiredTime, questions[] }
 ├─ IeltsWritingPart   { contentHtml, images[], sampleAnswerHtml, learnFromSampleHtml }
 ├─ IeltsSpeakingPart  { info{introductionText,audio}, questions[]{ timeToThink, timeToSpeak,
 │                       sampleAnswerHtml, sampleAnswerAudio } }
 └─ Question → details[] { detailType: GAP_FILL | SELECT | OPTION,
                           options[{label,text,correctAnswer}], explainHtml/En }

• GAP_FILL — free-text inline input, autosaves on blur. SELECT — radio, or multi-checkbox when the answer key has >1 correct option. OPTION — inline dropdown for matching/heading types.
• The separate quiz engine (community practice) supports 13 part types: multichoice, gapfill, dropdown, match, drag-drop onto image, word ordering, reorder, flashcard, AI-evaluated open-ended, passage, interactive YouTube video, audio response (×2).
• Sub-checkpoints (sectionCheckPoints) let a single Speaking part be sold/attempted separately with its own diamond price.

Production content & usage inventory (read replica, 24/08/2026)

Writing has few "questions" because most writing tasks are part-level essay prompts, not question-level items. In-test notes saved by learners: 3,564 rows (ielts_notes).

5Mock test & practice flows

Two modes on every test

Per-skill session flow

1. Listening / Reading: Preview (mode cards + diamond cost + AI-vs-teacher scoring choice) → sound check (Listening only) → exam screen with react-hook-form state, 1-second countdown, question palette per part, Howler audio player (Listening) or resizable passage/questions splitter (Reading) → every answer autosaves via submitPartAttempt → Submit or timeout → endAttempt(violationCount) → result page.
2. Writing: Preview with scoring-method radio (Teacher — only if canRequestTeacher — vs FLYER AI) → split view: prompt + images left, essay textarea right with live word count (soft warning at 500 words, hard cap with toast) → autosave on blur → submit → result polls while AI grades.
3. Speaking: Preview (single-part practice or full simulation) → speaker check + mic check (local-only recording) → per part: typewriter intro → per question: prompt audio → think countdown (timeToThink) → recording auto-starts, ring fills over timeToSpeak, auto-stop → upload (RecordRTC mono 16 kHz → /record → recordId) → submit per question (+ optional note in simulation) → part timer can force-submit in-flight answers → end attempt → result.
4. School exam sessions (B2B, feature flag student_school_exam): a blocking popup lists the exam's per-skill sessions with status pills; "Enter exam" opens the test with ?examId&sessionId&examMode=1 — Practice mode is hidden, the attempt is linked to the session via REST (link-attempt), and violations are additionally reported live to POST /v3/learner/exams/cheats.

6AI grading — Writing & Speaking

Writing

• Trigger: learner chooses "FLYER AI" scoring at start (requestAIReview); costs the check point's diamond price. The client deliberately never pre-checks the wallet — the backend answers NOT_ENOUGH_DIAMOND (it also counts free quota).
• Result: report polls every 3 s until graded. Two report generations: legacy (4 criterion tiles + markdown commentary) and V2 whenever detailedFeedback exists.
• V2 rubric mirrors the official band descriptors — Task Achievement/Response, Coherence & Cohesion, Lexical Resource, Grammatical Range & Accuracy — each broken into sub-criteria (e.g. paragraphing, cohesive devices, collocation, punctuation control), every leaf a bilingual "Feedback + How to improve" pair with a machine key mapped to a severity badge.
• Sentence-level corrections: sentenceSuggestion[] underlines flagged sentences in the learner's essay, color-coded by worst errorImpact (CRITICAL/SEVERE/MODERATE/MINOR/NONE), with diff popovers, a vocabulary-suggestion list, and scroll-synced spotlighting. Sample answer shown alongside.
• Export: Word (docx), PDF (print), shareable link. Teacher path supports quoted inline comments, audio comments, fixed answer and a criteria table.

Speaking

• Pipeline: recording → upload → async grading after end-attempt (Azure Speech assessment + LLM); the result page polls every 3 s with a 2-minute deadline, then degrades gracefully.
• Attempt level: overall band + 4 progress bars (pronunciation, fluency, vocab, grammar), each with a correct/warning/incorrect decision color.
• Per question: learner audio playback, transcript, suggested answer (HTML + audio), skill chips. Pronunciation feedback renders per word: IPA, nativeness score, per-phoneme accuracy breakdown, TTS of the correct pronunciation next to the learner's own audio. Azure payload additionally carries a Cambridge assessment (grammar/vocabulary scores, mistakes EN/VI, suggestions).
• Quota: learners get a weekly free AI Speaking allowance (aiIeltsSpeakingQuota remaining/total/used) before diamonds are charged. Advertised diamond rates: from 2💎 per AI mini test, 25💎 per AI full test.
• A richer DetailedFeedbackSpeaking schema (band-descriptor breakdowns mirroring Writing V2) already exists server-side but is not yet consumed by the web client (§13).

7AI Mentor (Bingo)

• Entry: the Dashboard's "Personal AI Teacher" textarea (12,000-char cap) creates a chat session and hands the first message over; or the sidebar hub at /real-time-conversation with two mode cards: Chat and Topic Talk.
• Chat (/real-time-conversation/chat/[id]): SSE-streamed markdown answers through an edge API route proxying the backend chat-AI endpoint, with conversation history rail, suggestion chips, infinite scroll, switch-to-call affordance.
• Topic Talk (/real-time-conversation/topic): browse Bingo subjects (level, topic, attempts, score; sortable), then a voice conversation: learner records, audio uploads and attaches to the message, and the reply streams back as interleaved text chunks + base64 MP3 audio + viseme frames driving a lip-synced Rive avatar, played through an ordered audio queue. Each subject carries a learningOutcomeSubjects[] checklist ticked off live as the learner covers each point; sessions complete explicitly.
• Limits: daily voice-call quota ("You have used up your call limit for today"). A third "Free talk / Call Bingo" mode is translated and partly implemented but not wired into the mode chooser (§13).
• Supporting AI endpoints: reply suggestions, TTS (textToSpeak), dictionary (EN-VI/EN-EN/synonyms with Google Translate + MyMemory fallbacks), open-ended quiz auto-evaluation, mistake-word pronunciation re-scoring.

8Progress, reports & study tools

9Accounts, auth & multi-tenant

• Login methods: phone-or-username + password, and Google via Firebase. No Apple/Facebook; email is a profile field, not a login. Password recovery by OTP.
• Signup: phone → OTP → password (modal flow; legacy full-page also live). Dual OTP transport: backend SMS OTP for VN numbers, Firebase phone OTP + invisible reCAPTCHA for international; Cloudflare Turnstile on top. ?ref= captures white-label source domain.
• Multi-profile: one FLYER account holds up to 20 learner profiles; switcher at /profiles; anonymous visitors get a cookie-based anonymous profile so they can attempt tests pre-signup. A cross-app profile_id cookie on the apex domain keeps exam/study/ranking/speaking apps in sync.
• Sessions: cookie-based Apollo with device: WEB_IELTS; single-session enforcement — logging in elsewhere triggers a live GraphQL-subscription event and a blocking "you were logged out from X" toast.
• Settings: Profiles tab (avatar upload, name, DOB, gender, province/school/class join, read-only email/phone, subscription expiry, change password) and Theme tab (light/dark + 8 accent colors, persisted pre-hydration; English/Vietnamese switch). WCAG-AA contrast is enforced by a custom lint gate on the token file.
• White-label: any non-first-party subdomain is a tenant; auth routes bounce to the main domain and back; per-domain flags hide diamonds or lock name changes; the ACCA tenant gets a placement lead form (/join-placementest) and suppressed sign-up nags.
• Notifications: in-app popup only (badge count, challenge invites); no push/email preference center.

10Monetization & premium gates

Subscription plans (FLYER IELTS PRO)

Diamond top-up (AI-grading currency)

Wallet = diamond (purchased) + freeIeltsDiamond (rewarded), shown with a breakdown popover. Third monetization channel: activation codes redeemed at /active-account (grants plan days + diamonds, with redemption history).

Four independent gates

1. Subscription entitlement — locked check points (isPremium / viewerCanAccess) redirect logged-in non-subscribers to /packages.
2. Band-range entitlement — the subscription tier carries bandFrom–bandTo; the band filter and visible catalogue are scoped to that window (legacy packages = all bands 0–10).
3. Diamonds per attempt — AI grading for Speaking/Writing charges the check point's diamond price; enforcement is server-side (NOT_ENOUGH_DIAMOND).
4. Teacher review — the "Request scoring from teacher" option appears only when the learner's profile has canRequestTeacher.

Attribution: UTM cookies (24h TTL), referral_code (member-get-member, capture only — no referral UI), ?ref source domain into signup. Analytics: GTM + GA4, Firebase Analytics, Meta Pixel; Sentry for errors. iOS smart-app banner + universal links to com.flyer.ielts.

11Data, API & infrastructure

API surface

• GraphQL v2 (primary; ~80 queries, ~62 mutations, 1 subscription; all inline codegen documents): content catalogue, the symmetric per-skill attempt lifecycle startAttempt → submitPartAttempt (per part/question) → endAttempt(violationCount), results/reports with grading fragments, auth/profile, notifications, missions, AI-conversation sessions, notes/dictionary/mistake words, stats. The single subscription pushes session-invalidation events.
• REST v3 ("Flyer EdTech Platform API", Rust backend; 242 generated hooks but only 4 used): feature configs, learner exams, link-attempt (bind attempt ↔ school exam session), cheat reporting. Escape-hatch hooks exist for the remaining 182 paths.
• Edge SSE proxies for AI chat/call streaming; audio uploads via a REST record endpoint; speech-to-text via a v2 REST endpoint.

Key entities

CheckPoint (universal content container, ~80 fields) → per-skill parts → questions → 3-primitive details; UserAttempt (~55 fields — one attempt entity for every FLYER product, with per-skill part attempts, band/score fields, AI + teacher grading, violation count, gamification earnings); User (wallet, subscriptions + band entitlements) → up to 20 LearnerProfile (target band, exam date, streak, AI speaking quota, school/class, custom domains). Production tables: 22 ielts_* tables on the read replica (parts/questions/attempts per skill + notes).

Infrastructure

• Gitea Actions CI → Docker arm64 → ECR → EKS via Tanka/jsonnet; dev (dev branch), staging (main), production (version tags). HPA 2–5 replicas at 80% CPU with documented scaling rationale; health probes on /api/ping.
• Custom imgproxy pipeline for images (human-readable URLs, 307 fallback to Next image when imgproxy is down); media on statics.flyer.us.
• Sentry self-hosted (init lives in the Apollo module; sampled 10%/1%); GA4 + GTM + Meta Pixel + Firebase Analytics; Remote Config as a second feature-flag channel next to /v3/learner/feature-configs.
• Engineering conventions worth keeping: oxlint/oxfmt, knip, a hardcoded-hex ratchet budget and a WCAG-AA contrast gate as custom lint scripts, heavily documented config files ("comments are the documentation").

12Edge cases & error handling

13Known gaps & technical debt

Found during the full-codebase scan — each is either a product decision to make or a fix to schedule.

14Acceptance criteria & future

Acceptance criteria (verified against production, 24/08/2026)

1. All four skills offer both Practice and Simulation modes with the mode differences in §5; simulation enforces fullscreen anti-cheat and submits violationCount.
2. AI Writing report returns the 4-criteria band breakdown with bilingual sub-criteria feedback and sentence-level corrections; AI Speaking report returns transcript + per-word pronunciation with IPA/phonemes; both poll at 3 s.
3. Diamond charging is enforced server-side including free quota; wallet = purchased + rewarded diamonds.
4. Band-tier subscriptions scope the visible catalogue via bandFrom–bandTo entitlements.
5. School exam sessions hide Practice mode, link attempts to sessions, and report cheats live.
6. Anonymous visitors can browse and attempt tests on an anonymous profile; one account supports up to 20 learner profiles with single-session enforcement.
7. Production numbers on this page reproduce from the read replica (ielts_* tables; usage = user_attempts.type_attempt='IELTS').

Recommended next (from the gaps)

• Close the loop on personalization: placement test + onboarding → use ieltsTargetScore/ieltsExamDate to actually recommend content (the "roadmap" the marketing already promises).
• Ship Speaking feedback V2 (schema already live) and the Free-talk voice mode.
• International revenue fixes: Polar for diamonds, correct anonymous geo-pricing, delete-account flow for app-store compliance.
• Brand consolidation on ieltsguru.ai: canonical/sitemap/robots/OG + per-page titles, plus dynamic sitemap for test pages.
• Security hygiene: rotate committed secrets, move to the k8s secret store.

← PRD catalogue · Source: direct scan of flyer/webs-ielts branch dev (24/08/2026) + FLYER production read replica · Internal — FLYER only.