UI Style Guide
Hướng dẫn phát triển giao diện React + Vite, cấu trúc thư mục frontend và tích hợp Cloudflare cho EduOne
1. Frontend Technology Stack
Hệ thống giao diện của EduOne Adaptive Learning Engine được xây dựng trên nền tảng React hiện đại, tối ưu hiệu năng và khả năng mở rộng nhanh chóng trong môi trường Serverless:
text
Vite + React + TypeScript
Tailwind CSS
shadcn/ui
Motion for React (f.k.a Framer Motion)
React Router
TanStack Query (React Query)
TanStack Table
React Hook Form + Zod- Vite + React + TypeScript: Cung cấp môi trường phát triển cực nhanh (HMR), biên dịch tối ưu và kiểu dữ liệu an toàn (Type safety) cho toàn bộ ứng dụng.
- Tailwind CSS & shadcn/ui: Nền tảng thiết kế giao diện linh hoạt, tiện dụng, giúp xây dựng nhanh các component giao diện đẹp mắt mà không làm tăng kích thước bundle CSS.
- Motion for React: Thư viện xử lý hiệu ứng chuyển động và micro-animations mượt mà, tăng trải nghiệm tương tác của học sinh K-12.
- TanStack Query & Table: Quản lý state bất đồng bộ (server state caching) và xử lý hiển thị dữ liệu dạng bảng (thống kê lớp học, tiến trình học viên) tối ưu.
- React Hook Form + Zod: Xử lý và xác thực dữ liệu đầu vào của các form (nhập yêu cầu bài học, câu hỏi quiz, feedback của giáo viên) chặt chẽ cả ở client và server.
2. Front-to-Back Architecture
Ứng dụng UI chạy hoàn toàn tại mạng biên (Edge) thông qua Cloudflare Pages, kết nối trực tiếp đến hệ thống API Gateway chạy trên Cloudflare Workers:
text
Browser (Client UI)
│
▼
Cloudflare Pages (React + Vite SPA)
│
▼ (REST API calls / Server Sent Events)
Cloudflare API Gateway (Workers)
│
├── Workers Business APIs
├── Cloudflare Workflows (Long-running Jobs)
├── D1 Database (Relational Data)
├── R2 Storage (Large Files & Assets)
├── Vectorize Index (Semantic RAG Search)
├── Durable Objects (Real-time Sync States)
└── AI Gateway (Observability & Routing)- Cloudflare Pages: Chịu trách nhiệm phân phối file tĩnh (HTML, JS, CSS, Assets) cực nhanh từ vị trí biên gần nhất với học sinh.
- API Gateway (Workers): Điểm tiếp nhận duy nhất cho các request từ frontend, chịu trách nhiệm xác thực (JWT), định tuyến và rate limiting trước khi gọi đến các dịch vụ lưu trữ và AI phía sau.
3. Directory & Feature Architecture
Để tránh việc mã nguồn trở nên quá phức tạp khi hệ thống mở rộng, cấu trúc dự án frontend được tổ chức chặt chẽ theo Feature-Driven Development (phát triển hướng tính năng), thay vì gom tất cả components vào một thư mục khổng lồ:
text
src/
├── app/ # Global configurations
│ ├── router/ # React Router routing tables
│ ├── providers/ # Global context providers (QueryClient, Auth, Theme)
│ └── layouts/ # Base page templates (DashboardLayout, AuthLayout)
│
├── components/ # Reusable UI elements
│ ├── ui/ # Official shadcn/ui library components (buttons, dialogs)
│ ├── system/ # Generic custom system components (charts, modals)
│ └── ai/ # AI-native custom components (LLM output containers)
│
├── features/ # Modular business feature packages (Self-contained)
│ ├── learners/ # Learner Model state visualizers, mastery trackers
│ ├── assessments/ # Quiz engines, practice screens, activity controllers
│ ├── recommendations/ # Personalized list views, explanation widgets
│ ├── knowledge/ # Skill map builders, competency editors
│ ├── workflows/ # Visual flow checkers, action monitors
│ └── observability/ # AI cost dashboards, query traces, system analytics
│
├── pages/ # Route level page views (combining different features)
│ ├── presentation/ # Public landing pages
│ ├── dashboard/ # Student/Teacher console dashboards
│ └── system/ # Settings, admin utility screens
│
├── services/ # API clients & query configurations
│ ├── api/ # Axios/Fetch client setups
│ ├── auth/ # OAuth/JWT state storage
│ └── queries/ # Custom hooks for TanStack Query (mutations, fetches)
│
├── stores/ # Global state management (Zustand/Jotai)
├── schemas/ # Shared Zod validation schemas
├── hooks/ # Reusable custom React hooks
└── styles/ # Global CSS & Tailwind utilities4. Cloudflare Integration Methods
Có hai phương án triển khai ứng dụng trên hạ tầng Cloudflare, phụ thuộc vào quy mô và cấu trúc của dự án:
Frontend (4.1. Option 1: Separate Pages) & Workers (Backend) — Recommended
- Frontend: Deployed to Cloudflare Pages (SPA bundle from
/dist). - Backend: Deployed separately to Cloudflare Workers (API endpoints serving
api.eduone.ai). - Ưu điểm: Phân tách ranh giới an toàn (Security Boundary) rõ ràng, dễ phát triển độc lập theo đội ngũ (Frontend/Backend team), thuận tiện cho cấu hình WAF và tối ưu hóa CDN riêng cho từng phần.
4.2. Option 2: Full-Stack Cloudflare Pages with Functions
- Frontend + Backend: Một repository duy nhất chứa React Code và thư mục
/functions(Pages Functions). - Ứu điểm: Rất phù hợp cho quá trình làm Prototype Hackathon nhanh chóng, gọn nhẹ, không cần quản lý nhiều repository.
- Nhược điểm: Khó bảo trì khi logic nghiệp vụ phình to, đặc biệt là khi tích hợp nhiều phân hệ phức tạp như Workflows, Vectorize hay Durable Objects.
5. Component Development Standards
Khi phát triển giao diện, đội ngũ lập trình viên cần tuân thủ quy tắc: Sử dụng shadcn/ui làm nền tảng (Foundation), nhưng bắt buộc tự xây dựng các Component Nghiệp vụ (Business Components) đặc thù:
LearnerModelCard: Hiển thị trực quan trạng thái năng lực hiện tại của học viên, các chỉ số thành thạo (mastery) và xu hướng tiến bộ.EvidenceViewer: Trình xem chi tiết các bằng chứng học tập (lịch sử quiz, code submissions, thời gian làm bài) dùng làm đầu vào cho mô hình đề xuất.ConfidenceIndicator: Chỉ báo độ tin cậy của mô hình AI khi đưa ra đề xuất cho học viên.WorkflowTimeline: Dòng thời gian hiển thị quy trình tự động đang chạy (AI soạn thảo, chất lượng QA, chờ người duyệt duyệt bài).KnowledgePackageCard: Thẻ thông tin biểu diễn gói kiến thức/kỹ năng được đóng gói đầy đủ tài liệu bài giảng, bài đọc mở rộng.HumanReviewGate: Chốt chặn phê duyệt của con người đối với các nội dung do AI sinh ra trước khi đưa vào thư viện chính thức.
6. Environment Variables & Security Policies
Việc quản lý biến môi trường trên frontend cần tuyệt đối tuân thủ quy tắc bảo mật nghiêm ngặt của Vite và Cloudflare:
- Biến môi trường công khai (Client-Side Variables): Chỉ chứa các biến cấu hình công khai bắt đầu bằng tiền tố
VITE_(ví dụ:VITE_API_BASE_URL,VITE_APP_ENV). - Quy tắc bảo mật Secrets: Tuyệt đối không khai báo bất kỳ API Keys (OpenAI, Anthropic), mã token quản trị của Cloudflare hay database secrets trong code frontend.
- Cơ chế hoạt động an toàn: Mọi thao tác gọi mô hình AI hoặc truy vấn cơ sở dữ liệu D1 bắt buộc phải đi qua các endpoint trung gian của Cloudflare Workers. Các API Keys bí mật sẽ được tiêm an toàn từ xa qua biến môi trường phía server (Worker Secrets/Cloudflare Dashboard) và không bao giờ lộ dưới client.