[Open Source] #176 - HabitSync: Hệ thống quản trị và đồng bộ thói quen cộng tác với Spring Boot 3.4, React Native và kiến trúc xác thực đa nguồn OIDC

Trong phân khúc ứng dụng Productivity, phần lớn các công cụ theo dõi thói quen (Habit Trackers) hiện nay thường chỉ dừng lại ở quy mô cá nhân hoặc bị "khóa" trong các hệ sinh thái SaaS thu thập dữ liệu. HabitSync ra đời như một giải pháp tự lưu trữ (self-hosted) mạnh mẽ, kết hợp giữa khả năng quản trị thói quen chuyên sâu và tính năng xã hội (Social Habits). Dự án cho phép nhóm bạn bè hoặc gia đình cùng tham gia các thử thách hàng tháng, chia sẻ tiến độ và thúc đẩy động lực thông qua hệ thống thông báo đa kênh.

Dưới góc độ kỹ thuật, HabitSync là một Case Study mẫu mực về việc ứng dụng Java 21, kỹ thuật Caching chiến lược và khả năng xuất bản đa nền tảng (Android & PWA) từ một cơ sở mã duy nhất.

Github: https://github.com/v8u7/habitsync

🛠️ 1. Nền tảng công nghệ: Hiệu năng thực thi và Đa nền tảng

HabitSync tận dụng sức mạnh của những công nghệ mới nhất để đảm bảo tính ổn định và linh hoạt:

• Backend Core (Java 21 & Spring Boot 3.4): Tận dụng tối ưu hiệu năng của Virtual Threads giúp xử lý hàng nghìn yêu cầu đồng thời mà không tốn nhiều tài nguyên máy chủ.
• Persistent & Migration: Sử dụng PostgreSQL cho môi trường sản xuất và Flyway để quản lý phiên bản database, đảm bảo dữ liệu luôn nhất quán qua các bản cập nhật phần mềm.
• Cross-platform Frontend (React Native & Expo): Một sự lựa chọn kiến trúc thông minh giúp biên dịch ứng dụng đồng thời thành Android App và Web PWA. Việc sử dụng TypeScript đảm bảo tính an toàn kiểu dữ liệu xuyên suốt từ API đến UI.
• Notification Engine (Apprise): Tích hợp sẵn bộ máy Apprise, cho phép hệ thống gửi thông báo tới hơn 80 dịch vụ (Telegram, Discord, Gotify, Email) chỉ thông qua các cấu hình Webhook đơn giản.

🏗️ 2. Trụ cột kiến trúc: API-First và Social Orchestration

Kiến trúc của HabitSync được thiết kế để trở thành một "Trung tâm thói quen" linh hoạt:

• Social Connectivity Architecture: Hệ thống không chỉ lưu trữ bản ghi thói quen đơn thuần mà còn quản lý các quan hệ liên kết (SharedHabit). Kỹ thuật này cho phép nhiều người dùng kết nối các thói quen cá nhân khác nhau vào một mục tiêu chung để thi đua.
• Multi-Issuer OIDC Support: Một tính năng cấp độ doanh nghiệp cho phép server chấp nhận xác thực từ nhiều nguồn khác nhau (ví dụ: vừa dùng Authelia cho nội bộ, vừa dùng Google OAuth cho người dùng khách) thông qua luồng PKCE bảo mật.
• Modular Scheduling (Quartz): Sử dụng Quartz Scheduler để điều phối các logic phức tạp như: chọn thử thách cộng đồng dựa trên lượt vote của người dùng vào đầu mỗi tháng và tự động chốt bảng xếp hạng vào cuối tháng.

🔄 3. Workflow: Vòng đời của một Thử thách hàng tháng (Sequence Diagram)

Sơ đồ mô tả quy trình tự động hóa của hệ thống từ lúc đề xuất thử thách đến khi trao giải:

sequenceDiagram
    participant User as Người dùng (Mobile/Web)
    participant API as Spring Boot API
    participant Quartz as Quartz Scheduler
    participant DB as PostgreSQL
    participant Notify as Apprise Service

    Note over Quartz: Đầu tháng (01/MM)
    Quartz->>DB: Truy vấn Challenge có lượt Vote cao nhất
    DB-->>Quartz: Challenge: "Chạy bộ 50km"
    Quartz->>API: Kích hoạt Thử thách mới
    API->>Notify: Gửi thông báo tới toàn bộ Circle
    
    loop Trong tháng
        User->>API: Ghi nhận 5km (POST /records)
        API->>DB: Lưu bản ghi & Cập nhật Progress
        API->>DB: Invalidate Cache tiến độ
    end

    Note over Quartz: Cuối tháng (30/MM)
    Quartz->>API: Khởi tạo quy trình Tổng kết
    API->>API: Tính toán Rank & Placement
    API->>DB: Lưu ChallengeResult & Cấp Medals
    API->>Notify: Gửi bảng tổng sắp huy chương cuối tháng

⚡ 4. Các kỹ thuật "Pro-level" trong mã nguồn

1. Smart Evicting Cache: HabitSync sử dụng Spring Cache (@Cacheable) để tăng tốc các phép tính toán phần trăm hoàn thành phức tạp. Điểm tinh tế nằm ở cơ chế Event-driven Eviction: Cache chỉ bị xóa khi có một bản ghi mới được tạo, giúp cân bằng giữa hiệu suất đọc cực nhanh và tính chính xác của dữ liệu.
2. Negative Habit Logic: Thay vì chỉ tính toán tiến độ cộng dồn, hệ thống hỗ trợ thói quen "Âm" (ví dụ: bỏ thuốc lá). Logic tính toán được đảo ngược để theo dõi việc người dùng giữ được hành vi ở dưới ngưỡng giới hạn cho phép.
3. PUID/PGID Docker Orchestration: Để giải quyết vấn đề nan giải về phân quyền tệp tin khi gắn Volume vào NAS (Synology, Unraid), dự án sử dụng kỹ thuật ánh xạ ID người dùng trực tiếp trong script khởi chạy của container.
4. TanStack Query Integration: Phía Frontend sử dụng cơ chế Optimistic Updates. Khi người dùng tick hoàn thành thói quen, giao diện sẽ thay đổi ngay lập tức trước khi nhận được phản hồi từ server, mang lại trải nghiệm mượt mà không độ trễ.

⚖️ 5. So sánh chiến lược

✅ Kết luận: Tại sao HabitSync là hình mẫu cho ứng dụng Productivity?

HabitSync chứng minh rằng một ứng dụng thói quen có thể đạt được độ tin cậy của hạ tầng doanh nghiệp. Việc kết hợp giữa Backend Java 21 hiện đại và khả năng tiếp cận đa nền tảng của React Native đã tạo ra một công cụ không chỉ hữu ích cho cá nhân mà còn sẵn sàng cho các cộng đồng nhỏ muốn tự chủ dữ liệu.

Đối với các kỹ sư Backend, nghiên cứu HabitSync mang lại giá trị về:

• Kỹ thuật quản lý Spring Cache và DB Migration thực tế.
• Cách thiết kế hệ thống Xác thực hiện đại (OIDC/PKCE).
• Tư duy xây dựng Hệ thống thông báo phân tán thông qua Apprise.