🗺️ Kiến trúc & hệ sinh thái FLYER

1Ecosystem map — bức tranh 1 phút

FLYER có hai "mặt tiền" chính chia theo địa lý và mục đích:

Sơ đồ khối

┌──────────────────────────────────────────────────────────────────────┐
│                       CÁC "MẶT TIỀN" (frontend)                      │
├──────────────────────────────────────────────────────────────────────┤
│ Marketing / Landing                                                  │
│   • flyer.vn        (LadiPage clone, HTML tĩnh, VI)                  │
│   • flyer.us        (Next.js, EN + ES)                               │
│   • teado.ai        (Next.js EN/VI/ES, Vercel)                       │
│                                                                      │
│ Học sinh                                                             │
│   • exam.flyer.us   (Phòng thi ảo · Cambridge/IELTS mock · gamify)   │
│      └─ study.exam.flyer.us  (Duolingo-style micro-frontend)         │
│   • ieltsguru.ai    (IELTS mock 4 kỹ năng + AI grade + AI Mentor)    │
│                                                                      │
│ Giáo viên / Trung tâm                                                │
│   • teacher.flyer.us  (partner-web · 228 route · Antd + GraphQL)     │
│   • teacher.teado.ai  (cùng partner-web, khác brand)                 │
│   • parent.flyer.us   (cùng partner-web, khác persona)               │
│                                                                      │
│ Internal (nội bộ)                                                    │
│   • roadmap.flyer.vn   • agent.flyer.vn   • meeting.flyer.vn         │
│   • hr.flyer.vn        • ketoan.flyer.vn  • marketing.flyer.vn       │
│   • cs.flyer.vn        • funnel.flyer.vn  • data.flyer.vn            │
└─────────────────────────────┬────────────────────────────────────────┘
                              │
                              ▼
┌──────────────────────────────────────────────────────────────────────┐
│                        BACKEND CHUNG (K8s prod)                      │
├──────────────────────────────────────────────────────────────────────┤
│  4 tầng API cùng chạy song song:                                     │
│  ┌───────────────┐ ┌───────────────┐ ┌──────────────┐ ┌────────────┐ │
│  │ GraphQL v1    │ │ GraphQL v2    │ │ REST v3      │ │ REST v4    │ │
│  │ Hasura        │ │ gqlgen (Go)   │ │ flyer-       │ │ teacher-   │ │
│  │ (legacy proxy)│ │ (chính)       │ │ backend-rust │ │ api (Go)   │ │
│  │               │ │               │ │ (182 endpt)  │ │ (11 endpt) │ │
│  └───────┬───────┘ └───────┬───────┘ └──────┬───────┘ └─────┬──────┘ │
│          └─────────────────┴────────────────┴───────────────┘        │
│                              │                                       │
│                    PostgreSQL 17 (Hasura)                            │
│                    - 284 bảng public                                 │
│                    - Read-replica ap-southeast-1 (analytics)         │
│                                                                      │
│  Sidecars:  imgproxy · slack notifier · birthday bot cron            │
└──────────────────────────────────────────────────────────────────────┘

2Persona & use case chính

3Chi tiết 6 nền tảng công khai

3.1 flyer.vn — Landing sales cho VN

3.2 flyer.us — Landing quốc tế (EN + ES)

3.3 exam.flyer.us — Phòng thi ảo (core học viên)

Đây là ứng dụng học chính của FLYER trên thị trường VN — nơi HS làm mock test Cambridge/IELTS, luyện tập, thi đua, xếp hạng. Gamification nặng: coin, kim cương, streak, khiên chứng chỉ. Study micro-frontend nhúng trong đây thành study.exam.flyer.us.

Menu chính (từ homepage)

Gamification hiển thị header

• Coin — kiếm bằng làm bài, đổi lấy phần thưởng
• Kim cương — tiền tệ premium, mua bằng VNPay/Polar, dùng trả phí chấm AI
• Trophy/Ranking — vị trí trong bảng xếp hạng
• Mission — nhiệm vụ ngày

Stack ước lượng (theo pattern chung với study/ielts trong flyer/webs)

• Next.js 15/16 Ứng dụng Router (như sibling apps)
• Apollo Client (GraphQL v2), React Query (REST v3/v4)
• next-intl EN/VI, next-translate hoặc như vậy
• Docker standalone → K8s prod cluster flyer-apps
• Đăng nhập: OTP SMS + Google/Facebook + tài khoản mật khẩu

3.4 teacher.flyer.us — Ứng dụng giáo viên / trung tâm

Repo partner-web — monolith frontend cho 3 domain: teacher.flyer.us, parent.flyer.us, tools.teado.ai (host header rewrite).

Route highlights (20 tính năng lớn phía teacher)

Có PRD riêng cho mỗi cái ở /tinh-nang. Nhóm nhanh:

3.5 ieltsguru.ai — Sản phẩm IELTS chuyên sâu

📄 PRD chi tiết đầy đủ 14 mục có sẵn — dưới đây chỉ tóm tắt.

3.6 teado.ai — Thương hiệu AI-first cho LatAm

Teado là bước đi mở thị trường Mỹ Latin — cùng backend FLYER, thương hiệu & UX rebrand. Có 2 phần:

3.6.a Landing teado.ai (marketing)

3.6.b Platform teacher.teado.ai

Cùng repo partner-web với teacher.flyer.us — chỉ khác host header. next.config rewrite host = tools.teado.ai → /flyer-ai. Full stack đã mô tả ở §3.4.

3.7 study.flyer.us · study.exam.flyer.us — Duolingo micro-frontend

📄 PRD chi tiết đầy đủ 10 mục. Tóm tắt:

4Tool nội bộ & landing phụ

Ngoài 6 platform khách hàng, có nhiều tool nội bộ chạy trên Cloudflare Pages / Vercel — mostly một-mình-một-repo, tự deploy bằng wrangler pages deploy hoặc push Git.

5Kiến trúc backend chung

4 tầng API — di sản của quá trình migrate

Frontend luôn đi qua Next.js rewrites

Trình duyệt không gọi thẳng backend service. Mọi request đi qua /api/* của Next.js rồi Next inject X-Session-Token, gắn cookie same-origin, log request và tránh CORS.

Cluster K8s

• Namespace production (prod) và development (dev).
• Registry registry.flyer.vn — image flyer/partner-web:main, flyer/webs-*, flyer/exam-*.
• Sidecar imgproxy chạy cạnh — nhận URL ảnh + resize.
• Deploy: kubectl rollout restart deploy ... -n production — chưa có GitHub Actions gate.

Domain routing

Ba domain teacher.flyer.us, parent.flyer.us, tools.teado.ai đều trỏ vào cùng pod partner-web; phân biệt bằng host header + rewrite trong next.config.js. Tương tự study.flyer.us và study.exam.flyer.us cùng vào pod study.

6Database & data model

Nguồn thật

Bảng lõi (nhóm theo domain)

Bẫy hay gặp khi audit / báo cáo

• assign_tests bẫy is_sample=true — mỗi GV đăng ký được tự sinh 10 bài mẫu; luôn filter is_sample=false khi đo usage. teacher_id 100% NULL — dùng teacher_profile_id.
• Checkpoint dùng chung nhiều level — 1 checkPointId xuất hiện ở nhiều duolingo_level; count qua bảng duolingo_level_check_points tránh double.
• study vocab A1 mồ côi — 5.890 bài đã build nhưng 99% chưa nối vào path nào; A1 chưa có Study path live.
• teacher active KPI — dùng cohort "tháng này vs cùng kỳ tháng trước", KHÔNG cộng dồn all-time (trùng người).
• ai_speaking_record_count — là remaining credit, KHÔNG phải usage. Muốn đo usage phải join speaking_question_attempts.
• content grammar — audit chính tả từ replica (44 bảng) — pipeline có sẵn, duolingo_parts đã xong 678 lỗi.

7Auth & multi-tenant

Cấu trúc phiên

Cách đăng nhập

• OTP SMS — số điện thoại VN → gửi qua vendor SMS
• Google OAuth — dùng cho HS/GV có gmail
• Facebook OAuth — thị trường VN vẫn dùng nhiều
• Email + password — legacy, ít dùng
• Google Workspace @flyer.us — cho tool nội bộ (roadmap, meeting, hr, ketoan…)

Multi-tenant hierarchy

User (1 tài khoản)
  ├── LearnerProfile 1..N (1 phụ huynh nhiều con)
  ├── TeacherProfile 0..N (GV làm nhiều trường)
  │     └── School (trường/trung tâm)
  │           └── CustomDomain? (703 trường đã có)
  └── Cookie phiên: .flyer.us (chia sẻ sang exam / teacher / study / ielts)

Guard component (teacher.flyer.us)

Trong app/Guard.tsx, mỗi route đổi:

1. Chưa login & route cần auth → redirect login.
2. Chưa xong onboarding → chuyển tới bước đang thiếu.
3. URL có ?schoolId=X khác trường hiện tại → SwitchSchoolMutation.

8AI/ML stack

1. Chấm AI Writing

• Trigger: HS/GV submit bài Writing → route /api/…/write/grade.
• Provider: Claude (chính) + DeepSeek (fallback rẻ hơn cho bulk).
• Rubric: IELTS Task 1/2 (4 tiêu chí × band 1-9) hoặc KET/PET/Starters/Movers/Flyers rubric riêng.
• Output: JSON có band từng tiêu chí + strengths/weaknesses + suggested improvements + overall band.
• Lưu: ai_writing_records + user_attempt_score_details.
• Quota: mỗi bài trừ N kim cương ví HS.

2. Chấm AI Speaking

• Trigger: HS ghi âm (RecordRTC) → upload → chấm.
• Provider: OpenAI Whisper transcribe → LLM (Claude/GPT) chấm nội dung + phần thô về phát âm.
• Rubric: 4 tiêu chí IELTS Speaking (Fluency, Vocabulary, Grammar, Pronunciation) hoặc Cambridge YLE.
• Lưu: ai_speaking_records.

3. Bingo AI (hội thoại)

• 3 chế độ trên 30 ngày gần đây: TOPIC (29,9k), CHAT (16,6k), CALL (16,4k) — tổng 63k phiên.
• Bảng: ai_conversation_sessions, ai_conversations, ai_partner_conversations.
• CALL: dùng WebRTC + STT streaming + TTS provider (ElevenLabs).
• ElevenLabs key: ~/.claude/secrets/elevenlabs.txt.

4. AI Mentor / Trợ giảng AI

• Tab "Trợ Giảng AI" trong teacher.flyer.us — hỏi đáp về bài, phân tích lớp.
• Tab "AI Mentor" trong ieltsguru.ai — coaching cá nhân hoá cho HS IELTS.
• Provider: Claude Sonnet — context injection từ user profile + last attempts.

Prompt hosting

Prompt engineering nằm trong repo backend (không nhìn thấy được từ frontend). Version control qua Git; PM muốn chỉnh phải PR trực tiếp vào backend repo, không có UI cho việc này.

9Media & CDN

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

Toàn ứng dụng học chỉ có một track chính chạy tại 1 thời điểm — GlobalAudioStore trong hooks/useGlobalAudio.ts giữ single-track control. Nhấn câu mới tự pause câu cũ. Tránh cảnh 2 câu hỏi cùng phát audio khi HS nhấn nhanh.

10Data flow — 3 sơ đồ chính

10.1 Luồng làm bài (HS attempt)

HS mở exam.flyer.us
   │
   ▼ chọn check_point (từ map/discovery)
StudyCheckPointQuery (GraphQL v2)  ─────►  gqlgen Go
   │                                          │
   ▼                                     read `check_points` + parts
duolingoStartAttempt / user_attempt_create
   │  mutation ─────────────────────►  Postgres INSERT `user_attempts`
   ▼                                          │
   Vòng lặp part:                             ▼
     - DuolingoSubmitPartAttempt      INSERT `duolingo_part_attempts`
     - hoặc REST v3 `/v3/…/submit`    INSERT `speaking_question_attempts` / `writing_part_attempts`
   ▼
DuolingoEndAttempt                    UPDATE `user_attempts.total_score`, .status
   │                                          │
   ▼                                          ▼
/result/[userAttemptId] ◄───── UserAttemptLessonQuery ─── join score_details
   │
   ▼ (Bingo call, Chấm AI Writing… → luồng AI riêng — §8)

10.2 Luồng GV giao bài + HS nhận

GV vào teacher.flyer.us/assigned-tests/new
   │
   ▼ chọn check_point + lớp
POST /api/v3/assign_tests { check_point_id, class_id, deadline, target[] }
   │
   ▼   flyer-backend-rust INSERT `assign_tests`, `assign_test_classes`, `assign_test_student`
   │   TRIGGER Zalo ZNS + push notification cho HS
   │
   ▼
HS click link Zalo hoặc mở app
   │
   ▼ deep-link: study.flyer.us/vi/{checkPointId}?assignTestCode=XYZ&target[]=...
   ▼ nếu HS đang mobile browser + có assignTestCode + không phải WebView
      └─► OpenInExamApp component tự chuyển sang app native
   ▼
HS làm bài (§10.1) → user_attempts được gắn với assign_test qua trigger
   │
   ▼
GV mở /report/... hoặc /assigned-tests/[id]
   │ query aggregate: bao nhiêu HS đã làm, điểm trung bình, HS chưa nộp
   ▼
Nếu HS chưa nộp qua deadline → cron gửi nhắc Zalo lại

10.3 Luồng thanh toán / kim cương

HS (VN) mua kim cương / gói PRO
   │
   ▼ chọn phương thức
   ├─ VNPay      ─► redirect merchant → callback POST /v3/vnpay/callback
   │                                  → INSERT `vnpay_payments` (status='SUCCESS')
   │                                  → UPDATE `wallets.balance`
   │
   ├─ Polar      ─► redirect polar.sh (dùng cho HS quốc tế)
   │
   ├─ In-app     ─► App Store / Google Play → server-to-server verify → `in_app_payments`
   │
   └─ Chuyển khoản tự động
       └─ BankHub / SePay → webhook match số dư → confirm
                        → INSERT `tuition_transactions`
                        → UPDATE `tuitions.payment_status='PAID'`

Center owner đóng học phí theo tháng cho lớp:
   GV tạo `group_invoices` cho lớp → gửi Zalo ZNS phụ huynh
   PH click → SePay/BankHub link → tự confirm

11Deployment & DevOps

3 target deploy khác nhau — mỗi cái làm việc gì

Runtime env injection

K8s apps dùng @beam-australia/react-env — entrypoint chạy react-env --env APP_ENV --prefix PUBLIC trước Next → sinh __ENV.js chứa PUBLIC_* tại thời điểm start pod. 1 image dùng chung dev/staging/prod, chỉ đổi ConfigMap.

Observability

• Datadog Browser Logs + RUM — trên tất cả frontend K8s (teacher, exam, ielts, study). trackUser(user) gắn userId + schoolId cho toàn session.
• Google Analytics + GTM — marketing sites (flyer.vn/us, teado.ai).
• Slack side-car — mỗi lần pod partner-web restart, script slack.mjs post lên Slack. Chạy nối tiếp && nên nếu Slack fail thì pod fail — rủi ro biết.
• Sentry: không tìm thấy config, chỉ Datadog.

12Ma trận phụ thuộc giữa các platform

13API bên ngoài & tích hợp

14Nợ kỹ thuật & rủi ro nổi bật

15Checklist onboarding cho thành viên mới — 30 ngày đầu

Tuần 1: Truy cập & đọc tài liệu

• [ ] Nhận email @flyer.us — Google Workspace + Slack + Notion + Github
• [ ] Được add vào GCP project để xem OAuth client, Cloud SQL
• [ ] Được add vào Cloudflare account (Pages + DNS + Workers)
• [ ] Nhận credential read-replica Postgres — user readonly_analyst_full cho analytics
• [ ] Được add vào Datadog để xem RUM/logs
• [ ] Được add Pipedrive (nếu quản B2B)
• [ ] Đọc PRD này (bạn đang đọc), đọc PRD IELTS, PRD Study, PRD teacher.flyer.us
• [ ] Đọc /tinh-nang — 20 PRD tính năng teacher

Tuần 2: Chạy sản phẩm thật + audit số

• [ ] Login exam.flyer.us làm 1 bài (thấy flow chấm ngay).
• [ ] Login teacher.flyer.us: tạo lớp giả 5 HS, giao 1 bài, xem báo cáo.
• [ ] Login ieltsguru.ai làm 1 Writing task 2 → gõ đáp án → xem chấm AI ra sao.
• [ ] Chạy 3 câu SQL mẫu trên read-replica để cảm nhận data volume.
• [ ] Xem Kiểm chứng production DB v2 để hiểu adoption thực tế từng feature.
• [ ] Ngồi cùng 1 CS staff xem họ handle 1 ticket phụ huynh.

Tuần 3: Nắm engineering

• [ ] Clone partner-web + flyer-webs + webs-ielts chạy local 1 lần. Xem CLAUDE.md của mỗi repo.
• [ ] Ngồi ăn trưa với 1 engineer backend (Go/Rust) → hỏi 4 tầng API tại sao còn đó.
• [ ] Ngồi ăn trưa với 1 engineer frontend → hỏi làm sao đưa 1 feature nhỏ từ ý tưởng lên prod.
• [ ] Xem 1 lần rollout Kubernetes prod (kubectl rollout restart deploy partner-web -n production).

Tuần 4: Xử lý 1 sự vụ nhỏ end-to-end

• [ ] Nhận 1 bug từ CS / Slack → thử reproduce → mở PR / issue → theo dõi tới khi ship.
• [ ] Tự tạo 1 PRD nhỏ cho 1 tính năng đề xuất → treo lên roadmap.flyer.vn.
• [ ] Chạy 1 report ad-hoc từ SQL trả lời 1 câu hỏi của Sales / CEO.

Người cần biết (khi PM cũ không còn)

Tài liệu bổ sung nên đọc

• PRD System Design teacher.flyer.us — sâu về partner-web
• PRD Study — Duolingo micro-frontend
• PRD IELTS Guru — 14 mục chi tiết
• Kiểm chứng số liệu production v2 — feature nào thực sự chạy
• Hub /tinh-nang — mọi PRD tính năng con
• Quy trình phát triển AI-first — cách team build feature
• Roadmap board — sprint hiện tại và backlog

← Danh mục PRD · Kiểm chứng production · System Design teacher · PRD Study · PRD IELTS · Roadmap board