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ử:

• Tập trung vào React + Vite: Frontend hoàn toàn tĩnh (SPA) được phát triển độc lập, gọn nhẹ để deploy trực tiếp lên Cloudflare Workers (hoặc Pages). Điều này giảm thiểu tối đa các cơ chế Server-Side Rendering (SSR) phức tạp, giúp dễ dàng kiểm thử và sửa lỗi nhanh chóng.
• 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 LearnerAgent tươ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.