🎯 IELTS Guru — ieltsguru.ai

1Bối cảnh, định vị & stack

IELTS Guru nhắm đến người học cần luyện IELTS sát đề thật không giới hạn và nhận phản hồi chất lượng chuyên gia ngay lập tức, không phải trả tiền thi thật hay thuê gia sư riêng. Câu định vị: "AI Mentor for smart IELTS preparation" — sản phẩm quảng bá chấm AI Speaking/Writing với chi phí bằng 1/50 kỳ thi thật. Phục vụ cùng lúc 3 nhóm: B2C tự học tại Việt Nam, B2C quốc tế (giá USD qua Polar), và B2B trường học qua white-label custom domain (có tenant riêng cho ACCA tại acca.teado.ai).

• Thương hiệu & domain: logo và SEO title ghi "IELTS GURU", nhưng codebase vẫn canonical mọi trang về ielts.flyer.us; ieltsguru.ai serve cùng một app (subdomain nằm trong allow-list first-party). SEO title từng trang vẫn mang tên cũ "FLYER IELTS Virtual Testing Platform" — điểm lệch thương hiệu cần xử lý (§13).
• Repo: flyer/webs-ielts độc lập trên Gitea (tách từ monorepo flyer/webs, giữ nguyên lịch sử). Nhánh dev → môi trường dev, main → staging, tag v*.*.* → production (hiện ở dòng v1.36.x).
• Stack: Next.js 16.3.1 (Pages Router, Turbopack), React 19, TypeScript, Apollo Client (GraphQL v2 là chính), 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 cho audio, Rive/Lottie cho animation, toolchain oxlint/oxfmt.
• Deploy: Docker (arm64) → ECR → EKS cluster flyer qua Tanka/jsonnet; production HPA 2–5 replicas theo 80% CPU; health check tại /api/ping; CI trên Gitea Actions, báo kết quả về Mattermost.
• App đi kèm: app native iOS/Android com.flyer.ielts (App Store id 1671502218) nối qua universal links; phía giáo viên nằm ở teacher.flyer.us (giao bài, chấm tay); thanh toán chạy trên checkout của exam.flyer.us (VN) hoặc Polar (US).

2Người dùng & user stories

3Kiến trúc thông tin & routes

App một khung sidebar trái (không có footer). Ngôn ngữ: en (mặc định, không prefix) và /vi. Chặn đăng nhập kiểu mềm: không có middleware hay chặn phía server — khách vãng lai nhận toast "mời đăng ký" tắt được ở mọi trang trừ một danh sách loại trừ nhỏ, còn sidebar chặn click vào các mục cần tài khoản để mở modal đăng nhập.

Sidebar (desktop = drawer mobile): Mock tests → /, Study → /libraries, Missions, Mistakes, Vocabulary book, Learning profile, History; khối dưới: Teacher role (mở teacher.flyer.us), popup Thông báo, số kim cương → /diamonds-preview, popup avatar (Upgrade → /packages, Đổi giao diện, Mã kích hoạt, Đổi hồ sơ, Sửa hồ sơ, Đăng xuất).

4Mô hình nội dung & kho đề

Toàn bộ nội dung nằm trong container CheckPoint dùng chung giữa các sản phẩm FLYER, với các cạnh part riêng cho IELTS theo kỹ năng. Mọi dạng câu hỏi hiển thị (MCQ, T/F/NG, nối, chọn heading, điền form…) đều được ghép từ đúng 3 primitive, điều khiển bằng placeholder <blank id> trong contentHtml:

CheckPoint (đề) ── time · maxGrade · diamond (giá chấm AI) · isPremium · ieltsBand · topics
 ├─ IeltsListeningPart { audio, audioSubtitle (tapescript), expiredTime, questions[] }
 ├─ IeltsReadingPart   { contentHtml (bài đọc), 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 — ô nhập tự do, tự lưu khi blur. SELECT — radio, hoặc checkbox nhiều đáp án khi đáp án đúng >1. OPTION — dropdown inline cho dạng nối/heading.
• Engine quiz riêng (đề cộng đồng) hỗ trợ 13 dạng part: multichoice, gapfill, dropdown, nối, kéo-thả lên ảnh, xếp từ, xếp lại câu, flashcard, câu mở chấm AI, passage, video YouTube tương tác, thu âm trả lời (×2).
• Sub-checkpoint (sectionCheckPoints) cho phép bán/làm riêng từng part Speaking với giá kim cương riêng.

Kho đề & usage production (read replica, 24/08/2026)

Writing ít "câu hỏi" vì phần lớn writing task là đề bài luận cấp part, không chia câu. Ghi chú học viên lưu trong bài: 3.564 dòng (ielts_notes).

5Luồng mock test & practice

Hai chế độ trên mọi đề

Luồng từng kỹ năng

1. Listening / Reading: Preview (thẻ chọn chế độ + giá kim cương + chọn chấm AI hay giáo viên) → kiểm tra loa (chỉ Listening) → màn làm bài với state react-hook-form, đồng hồ đếm từng giây, bảng câu hỏi theo part, trình phát Howler (Listening) hoặc splitter bài đọc/câu hỏi kéo được (Reading) → mỗi câu trả lời tự lưu qua submitPartAttempt → Nộp hoặc hết giờ → endAttempt(violationCount) → trang kết quả.
2. Writing: Preview với radio chọn cách chấm (Giáo viên — chỉ khi có canRequestTeacher — hoặc FLYER AI) → màn chia đôi: đề + hình bên trái, ô luận bên phải có đếm từ trực tiếp (cảnh báo mềm ở 500 từ, chặn cứng kèm toast) → tự lưu khi blur → nộp → trang kết quả poll trong lúc AI chấm.
3. Speaking: Preview (practice 1 part hoặc simulation đủ) → kiểm tra loa + mic (thu âm chỉ tại máy) → mỗi part: intro chạy chữ → mỗi câu: audio đề → đếm ngược suy nghĩ (timeToThink) → tự động bắt đầu thu, vòng tròn chạy theo timeToSpeak, tự dừng → upload (RecordRTC mono 16 kHz → /record → recordId) → nộp từng câu (+ ghi chú tuỳ chọn ở simulation) → đồng hồ part có thể ép nộp câu đang dở → kết thúc bài → kết quả.
4. Kỳ thi trường học (B2B, feature flag student_school_exam): popup chặn liệt kê các phiên thi theo kỹ năng kèm trạng thái; "Enter exam" mở đề với ?examId&sessionId&examMode=1 — ẩn hẳn chế độ Practice, attempt được nối vào phiên thi qua REST (link-attempt), vi phạm còn được báo trực tiếp về POST /v3/learner/exams/cheats.

6Chấm AI — Writing & Speaking

Writing

• Kích hoạt: học viên chọn chấm "FLYER AI" lúc bắt đầu (requestAIReview); trừ kim cương theo giá của đề. Client cố tình không kiểm tra ví trước — backend trả NOT_ENOUGH_DIAMOND (backend còn tính cả quota miễn phí).
• Kết quả: trang report poll 3 giây/lần đến khi chấm xong. Hai thế hệ report: bản cũ (4 ô tiêu chí + nhận xét markdown) và V2 khi có detailedFeedback.
• Rubric V2 bám đúng band descriptors chính thức — Task Achievement/Response, Coherence & Cohesion, Lexical Resource, Grammatical Range & Accuracy — mỗi tiêu chí chia tiêu chí con (chia đoạn, từ nối, collocation, dấu câu…), mỗi mục là cặp "Feedback + Cách cải thiện" song ngữ kèm machine key gắn badge mức độ.
• Sửa tới từng câu: sentenceSuggestion[] gạch chân câu lỗi trong bài của học viên, tô màu theo errorImpact nặng nhất (CRITICAL/SEVERE/MODERATE/MINOR/NONE), popover hiện diff, danh sách gợi ý từ vựng, spotlight cuộn đồng bộ. Bài mẫu hiển thị bên cạnh.
• Xuất file: Word (docx), PDF (in), link chia sẻ. Nhánh giáo viên hỗ trợ comment trích dẫn inline, comment giọng nói, bài đã sửa và bảng tiêu chí.

Speaking

• Pipeline: thu âm → upload → chấm bất đồng bộ sau khi kết thúc bài (Azure Speech + LLM); trang kết quả poll 3 giây/lần, quá 2 phút thì dừng lịch sự.
• Cấp bài: band tổng + 4 thanh điểm (phát âm, trôi chảy, từ vựng, ngữ pháp), mỗi thanh có màu theo mức đúng/cảnh báo/sai.
• Từng câu: nghe lại bài nói, transcript, câu trả lời gợi ý (HTML + audio), chip điểm kỹ năng. Phản hồi phát âm tới từng từ: IPA, điểm bản xứ, phân tích từng phoneme, TTS phát âm chuẩn đặt cạnh audio của học viên. Payload Azure còn kèm Cambridge assessment (điểm ngữ pháp/từ vựng, lỗi EN/VI, gợi ý).
• Quota: mỗi tuần học viên có lượt chấm AI Speaking miễn phí (aiIeltsSpeakingQuota remaining/total/used) trước khi trừ kim cương. Giá niêm yết: từ 2💎 mỗi AI mini test, 25💎 mỗi AI full test.
• Schema DetailedFeedbackSpeaking giàu hơn (phân tích theo band descriptors như Writing V2) đã có phía server nhưng web chưa dùng (§13).

7AI Mentor (Bingo)

• Lối vào: ô "Personal AI Teacher" trên Dashboard (tối đa 12.000 ký tự) tạo phiên chat và chuyển tin nhắn đầu tiên sang; hoặc hub /real-time-conversation với 2 thẻ chế độ: Chat và Topic Talk.
• Chat (/real-time-conversation/chat/[id]): trả lời markdown stream qua SSE (route API chạy trên edge proxy về backend chat-AI), có rail lịch sử hội thoại, chip gợi ý, cuộn vô hạn, nút chuyển sang gọi.
• Topic Talk (/real-time-conversation/topic): chọn chủ đề Bingo (level, topic, số lượt, điểm; sắp xếp được), rồi hội thoại giọng nói: học viên thu âm, audio upload đính vào tin nhắn, phản hồi stream về dạng xen kẽ text + audio MP3 base64 + viseme điều khiển avatar Rive nhép môi, phát theo hàng đợi có thứ tự. Mỗi chủ đề có checklist learningOutcomeSubjects[] tick trực tiếp khi học viên nói trúng ý; phiên kết thúc tường minh.
• Giới hạn: quota gọi thoại theo ngày ("You have used up your call limit for today"). Chế độ thứ ba "Free talk / Call Bingo" đã dịch và làm dở nhưng chưa nối vào màn chọn chế độ (§13).
• Endpoint AI phụ trợ: gợi ý câu trả lời, TTS (textToSpeak), từ điển (EN-VI/EN-EN/đồng nghĩa, fallback Google Translate + MyMemory), tự chấm câu mở của quiz, chấm lại phát âm từ sai.

8Tiến độ, báo cáo & công cụ học

9Tài khoản, đăng nhập & multi-tenant

• Cách đăng nhập: số điện thoại-hoặc-username + mật khẩu, và Google qua Firebase. Không có Apple/Facebook; email chỉ là trường hồ sơ, không dùng đăng nhập. Quên mật khẩu qua OTP.
• Đăng ký: số điện thoại → OTP → mật khẩu (luồng modal; trang cũ vẫn chạy). Hai kênh OTP: SMS backend cho số VN, Firebase phone OTP + reCAPTCHA ẩn cho quốc tế; thêm Cloudflare Turnstile. ?ref= ghi nhận domain nguồn white-label.
• Nhiều hồ sơ: một tài khoản FLYER chứa tối đa 20 hồ sơ người học; đổi tại /profiles; khách vãng lai có hồ sơ ẩn danh theo cookie nên làm bài được trước khi đăng ký. Cookie profile_id trên apex domain đồng bộ các app exam/study/ranking/speaking.
• Phiên: Apollo theo cookie với header device: WEB_IELTS; ép một phiên duy nhất — đăng nhập nơi khác đẩy sự kiện qua GraphQL subscription và toast chặn "bạn đã bị đăng xuất từ X".
• Cài đặt: tab Hồ sơ (avatar, tên, ngày sinh, giới tính, tỉnh/trường/lớp, email/SĐT chỉ đọc, hạn gói, đổi mật khẩu) và tab Giao diện (sáng/tối + 8 màu nhấn, áp trước khi hydrate; đổi English/Tiếng Việt). Độ tương phản WCAG AA được ép bằng lint gate riêng trên file token.
• White-label: mọi subdomain ngoài danh sách first-party là một tenant; route đăng nhập bật về domain chính rồi quay lại; flag theo domain để ẩn kim cương hoặc khoá đổi tên; tenant ACCA có form placement (/join-placementest) và tắt toast mời đăng ký.
• Thông báo: chỉ popup trong app (badge, lời mời thách đấu); chưa có trung tâm cài đặt push/email.

10Monetization & các lớp gate

Gói thuê bao (FLYER IELTS PRO)

Nạp kim cương (tiền tệ chấm AI)

Ví = diamond (mua) + freeIeltsDiamond (thưởng), có popover tách hai nguồn. Kênh thứ ba: mã kích hoạt nhập tại /active-account (cộng ngày gói + kim cương, có lịch sử mã đã dùng).

Bốn lớp gate độc lập

1. Quyền gói — đề khoá (isPremium / viewerCanAccess) chuyển user đã đăng nhập chưa mua sang /packages.
2. Quyền theo band — gói mang khoảng bandFrom–bandTo; filter band và kho đề nhìn thấy bị giới hạn trong khoảng đó (gói cũ = toàn bộ band 0–10).
3. Kim cương theo lượt — chấm AI Speaking/Writing trừ giá kim cương của đề; kiểm soát phía server (NOT_ENOUGH_DIAMOND).
4. Chấm giáo viên — lựa chọn "Request scoring from teacher" chỉ hiện khi hồ sơ có canRequestTeacher.

Attribution: cookie UTM (TTL 24h), referral_code (member-get-member, mới chỉ ghi nhận — chưa có UI giới thiệu), ?ref domain nguồn vào đăng ký. Analytics: GTM + GA4, Firebase Analytics, Meta Pixel; Sentry bắt lỗi. Banner smart-app iOS + universal links về com.flyer.ielts.

11Data, API & hạ tầng

Bề mặt API

• GraphQL v2 (chính; ~80 queries, ~62 mutations, 1 subscription; toàn bộ là document codegen inline): danh mục nội dung, vòng đời attempt đối xứng theo kỹ năng startAttempt → submitPartAttempt (từng part/câu) → endAttempt(violationCount), kết quả/report kèm fragment chấm điểm, auth/hồ sơ, thông báo, missions, phiên AI conversation, ghi chú/từ điển/từ sai, thống kê. Subscription duy nhất đẩy sự kiện huỷ phiên đăng nhập.
• REST v3 ("Flyer EdTech Platform API", backend Rust; sinh 242 hooks nhưng chỉ dùng 4): feature configs, danh sách kỳ thi, link-attempt (nối attempt ↔ phiên thi trường), báo gian lận. Có sẵn hook thoát hiểm cho 182 path còn lại.
• Proxy SSE trên edge cho stream chat/gọi AI; upload audio qua endpoint record REST; speech-to-text qua endpoint REST v2.

Thực thể chính

CheckPoint (container nội dung dùng chung, ~80 trường) → parts theo kỹ năng → câu hỏi → 3 primitive; UserAttempt (~55 trường — một thực thể attempt cho mọi sản phẩm FLYER, gồm part attempts theo kỹ năng, các trường band/điểm, chấm AI + giáo viên, số vi phạm, thưởng gamification); User (ví, gói + quyền band) → tối đa 20 LearnerProfile (band mục tiêu, ngày thi, streak, quota AI speaking, trường/lớp, custom domain). Bảng production: 22 bảng ielts_* trên read replica (parts/câu hỏi/attempts theo kỹ năng + ghi chú).

Hạ tầng

• CI Gitea Actions → Docker arm64 → ECR → EKS qua Tanka/jsonnet; dev (nhánh dev), staging (main), production (tag phiên bản). HPA 2–5 replicas theo 80% CPU với ghi chú lý do scaling ngay trong code; probe tại /api/ping.
• Pipeline ảnh imgproxy riêng (URL dễ đọc, hỏng thì 307 về Next image); media trên statics.flyer.us.
• Sentry self-hosted (init nằm trong module Apollo; sample 10%/1%); GA4 + GTM + Meta Pixel + Firebase Analytics; Remote Config là kênh feature-flag thứ hai bên cạnh /v3/learner/feature-configs.
• Quy ước engineering đáng giữ: oxlint/oxfmt, knip, budget "ratchet" cho màu hex hardcode và gate tương phản WCAG AA dưới dạng script lint riêng, file config chú thích rất kỹ ("comment chính là tài liệu").

12Edge cases & xử lý lỗi

13Gaps & nợ kỹ thuật đã biết

Phát hiện trong đợt quét toàn bộ codebase — mỗi mục hoặc là quyết định product cần chốt, hoặc là việc cần xếp lịch sửa.

14Acceptance criteria & tương lai

Acceptance criteria (đã kiểm chứng trên production, 24/08/2026)

1. Cả 4 kỹ năng đều có chế độ Practice và Simulation với các khác biệt ở §5; simulation ép fullscreen chống gian lận và nộp violationCount.
2. Report AI Writing trả phân tích band 4 tiêu chí với feedback tiêu chí con song ngữ và sửa lỗi tới từng câu; report AI Speaking trả transcript + phát âm từng từ với IPA/phoneme; cả hai poll 3 giây.
3. Trừ kim cương kiểm soát phía server, tính cả quota miễn phí; ví = kim cương mua + kim cương thưởng.
4. Gói theo band giới hạn kho đề nhìn thấy qua quyền bandFrom–bandTo.
5. Phiên thi trường học ẩn chế độ Practice, nối attempt vào phiên thi và báo gian lận trực tiếp.
6. Khách vãng lai xem và làm bài được trên hồ sơ ẩn danh; một tài khoản tối đa 20 hồ sơ với ép một phiên duy nhất.
7. Số liệu production trên trang này tái lập được từ read replica (bảng ielts_*; usage = user_attempts.type_attempt='IELTS').

Đề xuất bước tiếp theo (từ danh sách gaps)

• Khép vòng cá nhân hoá: placement test + onboarding → dùng ieltsTargetScore/ieltsExamDate để gợi ý nội dung thật (đúng cái "roadmap" marketing đang hứa).
• Ship Speaking feedback V2 (schema đã sẵn) và chế độ Free-talk giọng nói.
• Sửa doanh thu quốc tế: Polar cho kim cương, giá theo geo đúng cho khách chưa đăng nhập, luồng xoá tài khoản cho chuẩn app store.
• Gom thương hiệu về ieltsguru.ai: canonical/sitemap/robots/OG + title từng trang, kèm sitemap động cho trang đề.
• Vệ sinh bảo mật: xoay vòng secrets đã commit, chuyển vào secret store của k8s.

← Danh mục PRD · Nguồn: quét trực tiếp flyer/webs-ielts nhánh dev (24/08/2026) + read replica production của FLYER · Nội bộ FLYER.