Back to projects
Published

HNSync

HNSync là nền tảng hỗ trợ sinh viên UTH tự động đồng bộ lịch học, deadline Moodle và thông báo qua Telegram. Dự án được xây dựng theo kiến trúc fullstack với Next.js, NestJS, PostgreSQL, Redis, BullMQ và Python service, đồng thời hỗ trợ xuất lịch `.ics` để đồng bộ sang Google Calendar/iPhone Calendar. Ngoài bài toán đồng bộ dữ liệu học tập, hệ thống còn có dashboard quản trị, notification workflow, cơ chế bảo mật token và khả năng triển khai bằng Docker Compose.

Next.jsReactTypeScriptNestJSPostgreSQLPrismaRedisBullMQDockerPythonTelegram Bot APIPayOS
Live project
HNSync

Slug

hnsync

Reading time

6 min read

Created

5/2/2026

HNSync

Tổng quan

HNSync là một hệ thống hỗ trợ sinh viên UTH quản lý lịch học và deadline theo hướng tự động hóa tối đa. Thay vì phải liên tục kiểm tra cổng đào tạo hoặc Moodle, người dùng chỉ cần liên kết tài khoản một lần để hệ thống tự lấy dữ liệu, xử lý và đẩy thông báo qua Telegram.

Dự án được phát triển như một sản phẩm fullstack hoàn chỉnh, bao gồm frontend cho người dùng cuối, backend API phục vụ nghiệp vụ, hàng đợi xử lý nền, cơ sở dữ liệu, cache layer và một Python service phục vụ scraping/cross-check dữ liệu từ hệ thống trường.

Bài toán giải quyết

Sinh viên thường gặp ba vấn đề lặp lại:

  • Bỏ sót lịch học hoặc thay đổi lịch học trong tuần
  • Quên deadline bài tập trên Moodle
  • Khó tổng hợp lịch cá nhân từ nhiều nguồn khác nhau

HNSync giải quyết bài toán đó bằng cách xây dựng một luồng dữ liệu khép kín:

  1. Nhận thông tin xác thực và token đồng bộ của người dùng
  2. Thu thập dữ liệu từ hệ thống UTH/Moodle
  3. Chuẩn hóa và lưu dữ liệu vào hệ thống riêng
  4. Đồng bộ ra giao diện web, Telegram Bot và file lịch .ics
  5. Hỗ trợ nhắc việc và tra cứu lịch trống theo tuần

Tính năng nổi bật

1. Đồng bộ lịch học tự động

  • Lấy dữ liệu lịch học theo tuần/tháng từ hệ thống UTH
  • Chuẩn hóa thành các ClassSession để phục vụ hiển thị, phân tích và nhắc lịch
  • Hỗ trợ endpoint xuất file .ics theo syncToken để người dùng import vào Google Calendar, iPhone Calendar hoặc các ứng dụng lịch khác

2. Theo dõi deadline Moodle

  • Đồng bộ các đầu việc, hạn nộp và môn học liên quan từ Moodle
  • Lưu deadline theo từng người dùng để phục vụ truy vấn và nhắc nhở
  • Tạo nền tảng cho luồng nhắc deadline tự động qua bot

3. Tích hợp Telegram Bot

  • Sinh link kết nối bot trực tiếp từ giao diện web
  • Quản lý trạng thái liên kết bot của từng người dùng
  • Gửi thông báo học vụ, lịch học và nhắc deadline theo luồng tự động
  • Có thêm nhóm API/admin để theo dõi trạng thái bot, bật/tắt bot và gửi tin nhắn quản trị

4. Lịch rảnh theo tuần

  • Tính toán các khoảng thời gian FREE/BUSY theo buổi sáng, chiều, tối
  • Giúp sinh viên nhìn nhanh khung giờ trống để sắp xếp việc cá nhân
  • Hỗ trợ xuất ảnh lịch để lưu hoặc chia sẻ

5. Dashboard và trải nghiệm người dùng

  • Landing page giới thiệu rõ workflow: đăng nhập, đồng bộ dữ liệu, kết nối bot
  • Dashboard riêng cho người dùng sau xác thực
  • Các service tách biệt cho profile, lịch học, kết quả học tập, tiến độ học tập, subscription state và cài đặt người dùng
  • Có khu vực admin cho thống kê, quản lý user, orders, transactions, bot status và logs

Kiến trúc hệ thống

Frontend

Frontend được xây dựng bằng Next.js 16 + React 19 + TypeScript, sử dụng App Router để tổ chức route rõ ràng giữa public và private area.

Các điểm chính:

  • HeroUI + Tailwind CSS v4 cho hệ thống giao diện
  • Zustand cho state management phía client
  • react-hook-form + zod cho form handling và validation
  • axios cho API layer
  • react-markdown / md-editor cho các nội dung có định dạng Markdown
  • framer-motion để tăng chất lượng tương tác UI

Backend

Backend sử dụng NestJS 11 theo mô hình module hóa, tách nghiệp vụ rõ thành các domain như:

  • auth
  • users
  • uth
  • moodle
  • sync
  • schedules
  • bots
  • payment
  • orders
  • subscription
  • admin

Một số điểm đáng chú ý:

  • Prisma + PostgreSQL cho mô hình dữ liệu
  • Redis + BullMQ để xử lý queue, cache và tác vụ nền
  • JWT + argon2 + encryption service cho xác thực và bảo vệ dữ liệu nhạy cảm
  • Swagger/Scalar API docs để kiểm thử và tài liệu hóa API

Python Service

Ngoài Node backend, hệ thống còn có một Python service riêng dùng cho các luồng scraping/tương tác với nguồn dữ liệu bên ngoài, đặc biệt hữu ích trong các tình huống cần xử lý truy cập phức tạp hơn như rào cản Cloudflare hoặc session-dependent fetch.

Triển khai và vận hành

Dự án có cấu hình Docker Compose để dựng toàn bộ môi trường phát triển/vận hành nhanh chóng với các service:

  • postgres
  • redis
  • backend-nestjs
  • python-service

Điều này giúp hệ thống dễ chạy local, tách biệt dependency rõ ràng và thuận lợi cho việc scale hoặc deploy theo service.

Mô hình dữ liệu và nghiệp vụ

Schema Prisma cho thấy hệ thống không chỉ dừng ở mức demo mà đã được thiết kế cho vận hành thực tế, bao gồm:

  • User
  • Bot
  • ClassSession
  • MoodleDeadline
  • Order
  • Subscription
  • Plan
  • Feedback
  • FeedbackVote
  • BotActionHistory

Điểm mình đánh giá cao ở dự án này là dữ liệu không bị gom chung một bảng, mà được tách theo nghiệp vụ rõ ràng để:

  • dễ bảo trì
  • dễ mở rộng
  • dễ tối ưu truy vấn bằng index/composite key

Điểm kỹ thuật đáng chú ý

  • Xuất lịch .ics theo syncToken, tạo cầu nối giữa hệ thống nội bộ và calendar ecosystem bên ngoài
  • Sử dụng queue/background processors cho các tác vụ đồng bộ và nhắc lịch
  • Tách riêng bot workflow thay vì nhúng logic nhắn tin trực tiếp vào request lifecycle
  • Có lớp bảo mật cho token và thông tin xác thực người dùng
  • Có hạ tầng cache và orchestration để phục vụ sản phẩm nhiều bước xử lý
  • Có tư duy product rõ ràng: từ landing page, dashboard, bot UX, analytics cho đến admin tools

Vai trò và giá trị dự án

Nếu đặt trong portfolio cá nhân, HNSync thể hiện khá rõ năng lực ở nhiều lớp:

  • Thiết kế kiến trúc fullstack thay vì chỉ làm giao diện
  • Xây dựng hệ thống có tích hợp với nền tảng thứ ba
  • Làm việc với async jobs, cache, bot, auth, payment và deployment
  • Biến một nhu cầu rất đời thường của sinh viên thành một sản phẩm có thể dùng thực tế

Đây không chỉ là một website giới thiệu thông tin, mà là một hệ thống đồng bộ học vụ có nghiệp vụ thật, dữ liệu thật và bài toán vận hành thật.