🍬 FLYER Study — kiến trúc & toàn bộ tính năng

1Bối cảnh & mục tiêu

FLYER có nhiều dòng sản phẩm cho học sinh: exam.flyer.us (thi và luyện đề chứng chỉ Cambridge/IELTS), Bingo AI (chat & gọi thoại với gia sư ảo), và Study — mảng "học đều mỗi ngày" mà tài liệu này mô tả.

Study được đặt cược cho ba mục tiêu:

1. Kéo tần suất mở ứng dụng — bài học ngắn 3–7 phút, không cần đề thi hoàn chỉnh, để HS mở ứng dụng hàng ngày thay vì chỉ trước khi thi.
2. Trung chuyển vào luyện đề — sau vài chục lesson Study, HS có nền tảng đủ để bắt đầu mock test trên exam.flyer.us.
3. Kênh cho GV giao bài tự động — Study path là "chương trình" mà giáo viên có thể xếp lịch giao (thấy trên tính năng Giao bài tự động).

Tại sao chỉ có 3 màn?

Study là một micro-frontend: chỉ chuyên phần bản đồ + bộ chạy bài học + màn kết quả. Mọi thứ khác — hồ sơ, kim cương, chuỗi ngày, cửa hàng, đăng nhập, bảng xếp hạng — nằm ở shell exam.flyer.us bọc ngoài. Study nhúng vào exam qua subdomain study.exam.flyer.us và truy cập cookie phiên cấp .flyer.us. Domain study.flyer.us là bản standalone (HS mở link trực tiếp).

2Người dùng & user stories

Persona

User stories chính

1. Là HS mới, tôi muốn vào Study không cần đăng nhập, để không bỏ giữa chừng vì gặp form.
2. Là HS, tôi muốn nhìn thấy vị trí hiện tại trên bản đồ khi mở ứng dụng, để biết bài tiếp theo là gì.
3. Là HS, tôi muốn hoàn thành 1 bài trong dưới 5 phút và nhận sao, để có động lực làm bài kế tiếp.
4. Là HS làm sai câu, tôi muốn được cho làm lại câu đó cuối lượt, để hiểu chỗ sai trước khi qua bài.
5. Là HS, tôi muốn mở rương ở checkpoint đặc biệt, để có phần thưởng nhỏ ăn mừng.
6. Là HS được GV giao bài, tôi muốn mở link Zalo → ứng dụng native → Study bài đúng, để không phải tìm.
7. Là HS iPad, tôi muốn nghe được cả 2 CDN (Cloudflare/Cloudfront) khi 1 bên nghẽn, để không bị treo audio.

3Phạm vi kỹ thuật

Có trong repo apps/study

Vay từ exam shell (KHÔNG có trong repo Study)

• Trang Hồ sơ HS, Nhiều learner_profile, Cửa hàng kim cương, Chuỗi ngày (streak), Trái tim, Achievements gallery, Leaderboard.
• Trang đăng nhập: Study chỉ có RequireLoginModal gọi khi bắt đầu bài; luồng OTP/Google/Facebook nằm ở exam.
• Trang bài kiểm tra xếp lớp, khiên Cambridge, báo cáo phụ huynh: ở exam.

Stack ngắn gọn

4Luồng sản phẩm

┌────────────────────────────────────────────────────────────┐
│                 study.flyer.us hoặc study.exam.flyer.us    │
└─────────────────────────┬──────────────────────────────────┘
                          │
                    ┌─────▼─────────┐
                    │ / (home)      │
                    │ Level map     │  ExamLessonPageView
                    │ + Rive marker │  revalidate = 3600s
                    └─────┬─────────┘
       ┌──────────────────┼──────────────────┐
       │                  │                  │
  Regular level       Chest level      BingoSubject level
       │                  │                  │
       │            ┌─────▼─────┐            │
       │            │ Chest     │            │
       │            │ ceremony  │  ExamChestsView
       │            │ (chest→   │  (show-chest → robot-talk
       │            │  robot →  │   → bingo-talk → select-target)
       │            │  bingo→   │            │
       │            │ target)   │            │
       │            └─────┬─────┘            │
       │                  │                  │
       │                  │                  ▼
       │                  │        AIConversationSession
       │                  │        (redirect sang Bingo AI)
       │                  │
       ▼                  ▼
  ┌────────────────────────────┐
  │ /[id]  Lesson runner       │
  │ - duolingoStartAttempt     │
  │ - loop parts + retry parts │  ExamLessonDetailsView
  │ - DuolingoSubmitPartAttempt│  useLearningFlow
  │ - DuolingoEndAttempt       │  1.420 LOC
  └────────────┬───────────────┘
               │
               ▼
  ┌────────────────────────────┐
  │ /result/[id]               │
  │ Sao, độ chính xác, mục tiêu│  ExamLessonResultView
  │ + review từng câu          │  ModalViewResult (758 LOC)
  └────────────────────────────┘

Chi tiết từng bước

1. Vào home: server-side fetch DuolingoPaths từ v2 GraphQL (kèm X-Service-Token), transform về shape viewerDuolingoPaths. Rive /animations/map_mover.riv load ngay (preload trong layout).
2. Chọn level: nếu chưa đăng nhập → mở RequireLoginModal. Nếu là Chest → chuyển tới ExamChestsView. Nếu là BingoSubject → gọi ViewerAIConversationSessionCreate rồi redirect ra Bingo.
3. Vào phòng học: query StudyCheckPointQuery lấy list part; gọi duolingoStartAttempt lấy userAttemptId. Nếu URL có ?target[]= thì gọi GetAttemptObjectivesLesson.
4. Chạy từng part: useLearningFlow tăng currentPartIndexAtom; sau khi trả lời gọi DuolingoSubmitPartAttempt. Part sai được đẩy vào retryPartsAtom.
5. Lượt retry: khi qua hết part lần 1, chạy lại từng part trong retryParts đến khi rỗng. Ngoại lệ: checkpoint Flashcards không retry.
6. Kết thúc: gọi DuolingoEndAttempt, chuyển đến /result/[userAttemptId].
7. Màn kết quả: query UserAttemptLessonQuery, hiển thị sao/độ chính xác/mục tiêu; mở ModalViewResult review từng câu (tôn trọng assignTest.isHiddenAnswer).

Deep-link về ứng dụng native khi có assignTestCode

Nếu URL có ?assignTestCode= và HS đang xem trên mobile browser (không phải trong WebView), component OpenInExamApp tự deep-link mở ứng dụng native Exam vào đúng bài — tránh lỗi giao diện responsive.

5Kho part type — 14 renderer × 30 challenge subtype × 6 story element

a) 14 DuolingoPartType — mỗi loại một thư mục renderer

b) 30 DuolingoChallengeType — subtype backend

Mỗi challenge subtype cụ thể hoá cách trình bày một part. Ví dụ MULTIPLE_CHOICE có thể ánh xạ về SELECT (chọn text), IMAGE_SELECT (chọn ảnh), LISTEN_TAP (nghe rồi chọn từ). Đầy đủ 30 giá trị:

c) 6 DuolingoStoryElementType — element bên trong Story Mode

Story Mode là kiểu bài đặc biệt hiển thị 1 câu chuyện có nhân vật; mỗi bước là một element:

d) Ba loại level trên bản đồ (DuolingoLevelType)

6Business rules & chấm điểm

Luồng chạy bài (Learning Flow Engine)

Vòng lặp trong useLearningFlow.ts:

  1. Chạy lần lượt từng part theo thứ tự listDuolingoPartsAtom.
  2. Sau mỗi part:
       - Nếu đúng → thêm vào listPartIdAnswersCorrectAtom, next.
       - Nếu sai → thêm vào retryPartsAtom, next.
  3. Sau khi hết listDuolingoParts:
       - Nếu retryParts rỗng → isLessonCompleted = true.
       - Nếu còn → chạy vòng retry, mỗi part chỉ ra khỏi vòng khi đúng.
  4. Ngoại lệ: checkpoint gồm 100% FLASHCARD KHÔNG chạy vòng retry
     (vì flashcard không có "đúng/sai" theo nghĩa chấm điểm).
  5. isAfterFlashCard: cờ để render banner "làm tốt lắm" sau đoạn flashcard.

Chấm điểm & sao

Danh sách mục tiêu (UserAttemptObjectiveKey)

• COMPLETE_IN_5_MIN — Hoàn thành bài trong 5 phút. Hiển thị đồng hồ đếm ngược react-countdown trên UI real-time.
• EXACT_THREE_FIRST_TRY — Đúng 3 câu đầu tiên trong lượt 1.

Live tracker query GetAttemptObjectivesLessonTargetRealTime chạy khi có ?target[]= trong URL (giao bài của GV).

Hai theme bản đồ

Bên cạnh đó có StudyThemeProvider đọc checkPoint.testLevel.slug để chọn palette con: starters, movers, flyers, ket, pet, toefl-primary, hoặc default.

7Data & GraphQL

Endpoint

Tất cả traffic đi qua rewrite /api/v2/graphql → ${SERVICE_API_V2}/v2/graphql. Server-side fetch (bản đồ) dùng thêm header X-Service-Token (env X_SERVICE_TOKEN) để bỏ qua auth cookie khi SSR.

Full list operation (đúng như trong codegen)

Fragment

• Viewer — bọc trong coin, star, frameImage, avatarUrl, subscriptionExpiresAt, isSubscribing (dùng cho shell hiển thị, KHÔNG hiển thị trong Study).
• LearnerProfile — hồ sơ HS.
• subChallenges — dùng khi 1 part có nhiều sub-question.

Bảng backend liên quan (Postgres · read-replica cho analytics)

8Media stack — nhiều layer cùng lúc

Cơ chế "1 audio 1 lần"

GlobalAudioStore trong hooks/useGlobalAudio.ts giữ 1 track chính; ai nhấn play tự pause người khác. Tránh cảnh 2 câu hỏi cùng phát audio khi HS nhấn nhanh.

Dual-CDN

localStorage.cdn_choice = 'cloudflare' | 'cloudfront' (mặc định cloudflare) cho phép người dùng chuyển CDN khi bị nghẽn — dùng để debug khi kêu iPad lag audio ở khu vực nhất định.

9Auth, giao bài & i18n

Auth — HS không đăng nhập vẫn học được (đến khi nộp)

1. Khi vào lần đầu, AuthProvider gọi AuthProviderCreateAnonymousLearnerProfileMutation, trả về ID.
2. ID được lưu vào cookie NEXT_PUBLIC_ANONYMOUS_LEARNER_PROFILE_ID ở domain root (.flyer.us hoặc .flyer.vn) → chia sẻ được cho study.exam.flyer.us.
3. HS có thể lướt map + xem bài. Khi nhấn bắt đầu bài → RequireLoginModal nếu chưa có phiên thật.
4. Đăng nhập rồi có thể đổi giữa nhiều learner (1 tài khoản nhiều bé) qua AuthProviderViewerSwitchLearnerProfileMutation.

Giao bài (assignTest interop)

URL từ GV: study.flyer.us/vi/{checkPointId}?assignTestCode=XYZ&target[]=COMPLETE_IN_5_MIN&target[]=EXACT_THREE_FIRST_TRY&levelId=…&bookLessonId=…

• assignTestCode gắn bài với 1 bản giao cụ thể; kết quả nộp về cùng attempt trên bảng assign_test_student (bên teacher).
• target[] mở live tracker mục tiêu.
• levelId + bookLessonId điều hướng ngữ cảnh (biết bài này thuộc unit/lesson nào để về đúng chỗ khi xong).
• Nếu mobile + có assignTestCode + không phải WebView → OpenInExamApp deep-link mở ứng dụng native để tránh giao diện web trên mobile.

i18n

Middleware src/middleware.ts chỉ dùng createMiddleware(routing) của next-intl, KHÔNG có logic auth ở edge. localePrefix: 'as-needed' nên URL EN không có /en/.

Deploy

10Rủi ro, edge case & tương lai

Rủi ro / nợ kỹ thuật hiện tại

Edge case đã xử lý

• Audio HLS timeout 6s → tự chuyển progressive mp3.
• 1 track audio 1 lần — nhấn câu mới tự dừng câu cũ.
• Flashcard-only checkpoint không chạy retry loop.
• Mobile browser + assignTestCode + không phải WebView → deep-link ứng dụng native.
• Chest ceremony có ExitConfirmationPopup chống thoát nhầm.
• SSR revalidate = 3600 để bản đồ có ISR, không bombard server.

Ngoài phạm vi / tương lai

• Kết nối Study path cho A1/A2/B1: nối 5.890 vocab A1 hiện có vào path chính thức; mở rộng lên Movers/Flyers/KET/PET.
• Chuyển Study path thành lộ trình cá nhân hoá: dùng kết quả placement để chọn unit khởi đầu.
• Rời khỏi shell exam về mặt UI: build streak/hearts/shop ở Study để bản standalone study.flyer.us đủ nghiện, không phụ thuộc exam.
• Tách ExamLessonDetailsView: mỗi part type một sub-component với contract chuẩn (onSubmit, onProgress).
• Thêm live tracker mục tiêu ngoài COMPLETE_IN_5_MIN: streak/day, phối hợp AI Bingo, mục tiêu speaking.
• SEO / preview linh hoạt: SSR trả về hero + demo bài để social preview không thấy màn trống.

← Danh mục PRD · Kiểm chứng số liệu production · System Design teacher.flyer.us · Roadmap chính