Frontend Architecture
Tài liệu này trình bày chi tiết về cấu trúc lựa chọn bộ công nghệ Frontend và cách thức tích hợp giao tiếp thời gian thực của ứng dụng Hanoi Agents.
1. SPA Architecture: React & Vite
Đối với dự án Hackathon hoặc giai đoạn xây dựng MVP của Startup, chúng tôi lựa chọn sự tối giản nhằm gia tăng tối đa tốc độ phát triển và kiểm thử:
- Không lạm dụng Next.js: Next.js là một công cụ tuyệt vời nhưng đi kèm quá nhiều cơ chế trừu tượng (như Server Actions, Server Components) và yêu cầu các adapter tương thích (như OpenNext) để chạy trên Cloudflare. Điều này làm tăng độ phức tạp và làm cho các AI Coding Agent khó tự động sửa lỗi.
- Tập trung vào React + Vite: Frontend hoàn toàn tĩnh (SPA) được deploy trực tiếp lên Cloudflare Workers (hoặc Pages). API giao tiếp thông qua Hono Serverless siêu nhẹ.
- Monorepo Structure: Frontend app và Backend code được cấu trúc trong cùng một repository giúp chia sẻ kiểu dữ liệu (Types) an toàn, dễ cấu hình và deploy.
2. Real-time Communication: WebSockets
Để đồng bộ giao diện người học tức thời mà không cần cơ chế Polling (liên tục gửi request kiểm tra), hệ thống thiết lập kết nối thời gian thực:
- Persistent WebSockets: Trình duyệt client duy trì kết nối persistent socket trực tiếp tới thực thể Durable Object của
LearnerAgenttương ứng. - Event Dispatching: Khi các quy trình Cloudflare Workflows nền hoàn tất chấm bài, nó thông báo kết quả về cho Learner Agent. Agent lập tức gửi một WebSocket message về Client để cập nhật giao diện (Ví dụ: Chuyển màu chỉ báo kỹ năng từ đỏ sang xanh ngay lập tức).
- State Sync: Đảm bảo trạng thái hiển thị của học viên luôn trùng khớp với trạng thái tính toán trong Learner Model tại backend.