🏗️ Kiến trúc hệ thống teacher.flyer.us

1Bối cảnh & mục tiêu kiến trúc

partner-web là monolith frontend phục vụ ba nhóm người dùng khác nhau qua ba domain (nhưng cùng một Next.js ứng dụng):

Ba lý do vì sao dùng chung một codebase (thay vì tách 3 ứng dụng riêng):

• Chia sẻ UI kit và design tokens — FlyerComponentsV2/ (756 file component) dùng chung cho teacher & parent, tránh drift.
• Chia sẻ auth flow — GraphQL Viewer query trả về cả teacherProfile, learnerProfile, schools; Guard chỉ route theo persona.
• Editor & AI features chia sẻ — CKEditor, chấm AI, chatbot-widget dùng chung; nếu tách phải sync 3 lần.

Đánh đổi: bundle size lớn (~450 dependencies), thời gian dev-start chậm (openapi-gen + gqlgen chạy trước Next dev), và provider tree 14 tầng khiến việc trace bug khó hơn — nhưng team đánh giá cost tách nhỏ hơn cost đồng bộ.

2Tổng quan hệ thống

          ┌─────────────────────────────────────────────────┐
          │ Trình duyệt: teacher.flyer.us / parent.flyer.us │
          └──────────────────────┬──────────────────────────┘
                                 │ HTTPS (cookies + X-Session-Token)
                                 ▼
                    ┌────────────────────────┐
                    │  partner-web           │
                    │  Next.js 15 (K8s pod)  │
                    │  server.js (standalone)│
                    └──────────┬─────────────┘
                               │
     ┌────────────┬────────────┼────────────┬─────────────┐
     │            │            │            │             │
     ▼            ▼            ▼            ▼             ▼
┌─────────┐ ┌─────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐
│ GraphQL │ │ GraphQL │ │ REST v3   │ │ REST v4   │ │ Static /  │
│ API v1  │ │ API v2  │ │ flyer-    │ │ teacher-  │ │ Media CDN │
│(legacy) │ │(gqlgen) │ │backend-   │ │ api       │ │           │
│         │ │         │ │rust:3000  │ │ :8081     │ │           │
└────┬────┘ └────┬────┘ └─────┬─────┘ └─────┬─────┘ └───────────┘
     │           │            │             │
     └─── PostgreSQL 17 (Hasura) ───────────┘
                             │
                             ▼
                 Read-replica ap-southeast-1
                 (analytics · truy vấn nội bộ)

Điểm cần nhớ:

• Toàn bộ traffic backend đi qua Next.js rewrites() — trình duyệt không gọi thẳng vào các backend service. Điều này cho phép Next inject header, log request, và tránh CORS.
• Ba backend service (GraphQL v2, REST v3, REST v4) chạy độc lập nhưng cùng đọc/ghi một PostgreSQL Hasura → data consistency dựa vào tầng DB, không phải tầng API.
• Có thêm một pod slack.mjs khởi động bên trong container để post deploy notification (xem §8).

3Frontend stack

Cấu trúc thư mục

src/
├── __generated__/          # GraphQL codegen (types + hooks)
├── api/
│   ├── __generated__/      # OpenAPI codegen v3
│   ├── v4/                 # OpenAPI codegen v4 (tách khỏi v3)
│   ├── client.ts           # openapi-fetch client + interceptors
│   ├── common.ts           # GraphQL queries dùng chung
│   └── hooks.ts            # Wrapper hooks kết hợp GraphQL + REST
├── app/
│   ├── Guard.tsx           # Auth guard, gate route
│   └── LoadingScreen.tsx
├── components/             # 756 file — FlyerComponents / FlyerComponentsV2 + common
├── containers/             # DialogsContainer, ProgressBarContainer
├── layouts/
│   ├── main/               # Layout chính có sidebar
│   ├── authen/             # Login/signup layout
│   └── routeConfig.tsx     # Mapping route → layout
├── pages/                  # 228 file — Next.js Pages Router
├── providers/              # 14 provider (xem §6)
│   ├── flyer/              # Auth, User, Recap, Onboarding
│   ├── teado/              # Cross-domain session token
│   └── ...
├── store/                  # Jotai atoms (theme, assign-test, ai-teacher, …)
├── hooks/                  # useSwitchSchool, useNotificationParent, …
├── lib/
│   └── datadog.ts          # trackPageView, trackUser, initDatadog
└── utils/

4Tầng API — 4 lớp song song

Khi nào dùng lớp nào — quy tắc thực tế

1. Ưu tiên GraphQL cho các query có nhiều mảnh dữ liệu liên quan (student profile + class + attempts), vì tránh N+1 request. Ví dụ useTeacherFeatureConfigs, GetViewerQuery.
2. REST v3 cho các flow legacy đã ổn định: auth, exam, checkpoint, tuition, wallet, package. 182 endpoint gần như bao trọn nghiệp vụ.
3. REST v4 chỉ cho module mới, cắt tách khỏi legacy: hiện chỉ có /library và toàn bộ /wisdom-stones/* (Đá Tri Thức). Đây là "template" để mở rộng backend Go tách trách nhiệm.
4. Không được gọi thẳng URL upstream — luôn dùng path /api/… để Next inject X-Session-Token và giữ cookie same-origin.

Auth injection tự động

// src/api/client.ts
apiClient.use({
  onRequest({ request }) {
    const token = getSessionToken()          // đọc từ ?sessTok= hoặc hash hand-off
    if (token) request.headers.set('X-Session-Token', token)
    return request
  },
})

Cookie credentials: 'include' là mặc định. Ngoài ra header device: WEB_TEACHER | WEB_PARENT được set theo hàm isPartner — backend dùng để phân tích device analytics.

Session-expired bus (global 401 handler)

// Bất kỳ 401 nào từ REST hoặc lỗi GraphQL với code = NOT_AUTHENTICATED
// đều publish qua sessionExpiredBus → hiện SessionExpiredModal ở root.
apiClient.use({
  async onResponse({ response }) {
    if (response.status === 401) notifySessionExpired()
    else {
      const body = await response.clone().json().catch(() => null)
      if (body?.code === 'NOT_AUTHENTICATED') notifySessionExpired()
    }
    return response
  },
})

5Auth & multi-tenant

Nguồn danh tính

1. Cookie phiên (HTTP-only, do backend set) — nguồn chính, gửi qua credentials: 'include'.
2. X-Session-Token — dùng khi hand-off cross-domain (ví dụ từ flyer.us → teacher.flyer.us qua query ?sessTok= hoặc hash). Được lưu tạm bằng sessionToken util và gắn cho mọi REST call.
3. Google OAuth — dùng cho login đầu tiên (nút LoginWithGoogleButton), sau đó backend cấp cookie.

Guard component

app/Guard.tsx chạy sau TeadoProvider, quyết định 3 việc mỗi khi route đổi:

1. Đã login chưa? Nếu chưa và route không nằm trong UNAUTHENTICATED_PATHS → redirect login.
2. Đã hoàn thành onboarding chưa? Nếu thiếu bước → getCompletedOnboardingRedirect(user) đưa về đúng bước dở dang.
3. School mismatch: nếu URL có ?schoolId=… khác currentSchool.schoolId → useSwitchSchool.switchSchool(newId).

Multi-tenant model

Hệ quả cho developer: mọi query danh sách phải luôn scope theo schoolId từ context (useAuth().currentSchool); nếu quên, sẽ leak data giữa trường — tuy backend cũng chặn nhưng đừng dựa vào đó.

6State management & provider tree

Ba nguồn state

Provider tree — thứ tự 14 tầng

<ConfigProvider antd>
 <ReactQueryProvider>                   // React Query cache
  <QueryParamProvider next-adapter>      // URL ↔ state
   <CacheProvider emotion>
    <ThemeConfigProvider>                // Custom theme (school branding)
     <TailwindThemeProvider>
      <RemoteConfigProvider>             // Feature flags từ backend
       <NotistackProvider>                // Snackbar
        <FlyerProvider typePolicies=…>   // ApolloProvider + AuthProvider + UserProvider
         <TeadoProvider>                 // Cross-domain session bootstrap
          <Guard>                        // 🔒 Auth + route decision
           <OnboardingUserProvider>
            <ContentPolicyGateProvider>  // Chặn content vi phạm chính sách
             <PreRouteProvider>          // Preload critical data
              <Routes>                   // routeConfig → layout theo pathname
               <DataProvider>            // Server-side hydrate cho data-heavy pages
                <BankAccountDataProvider>
                 <BankHubProvider>       // Payment integration
                  <RecapProvider>        // Modal recap tuần/tháng
                   <Component />         // 👈 page component

7Build, deploy & runtime

Pipeline hiện tại

# Build → Docker → K8s (thủ công qua scripts, chưa có GitHub Actions)
pnpm build-dev   → build .next standalone
                 → docker buildx build --push registry.flyer.vn/flyer/partner-web:dev
pnpm deploy-dev  → kubectl rollout restart deploy partner-web-dev -n development

pnpm build-prod  → docker build tag :main
pnpm deploy-prod → kubectl rollout restart deploy partner-web -n production

Runtime env injection — @beam-australia/react-env

Container entrypoint chạy react-env --env APP_ENV --prefix PUBLIC trước Next → sinh __ENV.js chứa toàn bộ biến PUBLIC_* tại thời điểm start pod. Nhờ vậy một image chung dùng được cho dev/staging/prod, chỉ đổi ConfigMap.

Dockerfile — điểm bất thường

ENTRYPOINT node ./slack/slack.mjs && \
  react-env --env APP_ENV --prefix PUBLIC -- node server.js

Slack side-car: mỗi lần pod khởi động, script slack.mjs post message vào Slack (deploy notification / rollback alert). Chạy nối tiếp qua && — nếu Slack fail, pod fail luôn. Đây là điểm phải chú ý khi Slack rate-limit.

8Observability & error surfaces

Datadog Browser SDK

• @datadog/browser-logs — initDatadog() gọi trong _app.tsx; forward console.error + custom log.
• @datadog/browser-rum — RUM session replay + performance.
• trackUser(user) chạy trong FlyerAuthProvider ngay khi Viewer resolve → gắn userId, schoolId cho toàn bộ session logs.
• clearUser() chạy khi logout.

Google tracking

GoogleAnalytics + GoogleTagManager load qua @next/third-parties/google ở root _app.tsx; page view emit qua router.events.on('routeChangeComplete', …).

User-facing errors

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

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

Đã nằm trong backlog

• v4-first cho module mới: mọi feature Sprint 108+ mặc định gọi REST v4 (teacher-api Go); GraphQL v1 chỉ giữ cho legacy. Đá Tri Thức đã đi theo pattern này.
• Consolidate UI kit: chốt FlyerComponentsV2 làm chuẩn, deprecate v1 và MUI override → giảm CSS trùng lặp.
• Thêm CI GitHub Actions: gate lint + type-check + Playwright smoke test trước merge dev.
• Bật TypeScript strict theo folder (bắt đầu từ src/api/ và src/providers/flyer/).

Chưa quyết

• Migrate Ứng dụng Router: đợi Next.js ổn định RSC + Suspense boundaries cho Ant Design (hiện có bug hydration).
• Tách parent-web khỏi partner-web: chỉ làm khi bundle vượt ngưỡng LCP; hiện shared code còn nhiều nên chưa cần.
• gRPC/tRPC nội bộ: từng bàn nhưng chưa có động lực thực sự — REST v4 + OpenAPI codegen đã đủ tốt.

Kỳ vọng đo được sau 1 sprint

• Bảng health: bundle size (bytes vendor + first load), TTI, số warning TS lúc build.
• Số module đã migrate sang v4 (baseline: 1 — Đá Tri Thức).
• Tỉ lệ page có CI check pass trước khi vào main.

← Danh mục PRD · Kiểm chứng số liệu production · Roadmap chính