Để hoàn thành dự án “Notopia - Ứng dụng ghi chú thông minh hỗ trợ quản lý tri thức bằng biểu đồ quan hệ”, bên cạnh sự nỗ lực của các thành viên, chúng em đã may mắn nhận được sự đồng hành và chỉ dẫn vô cùng quý giá.

Đặc biệt, chúng em xin bày tỏ lòng tri ân sâu sắc nhất tới cô Trần Thị Hồng Yến. Không chỉ là người định hướng chuyên môn, cô còn dành tâm huyết để khích lệ, giúp chúng em tháo gỡ những nút thắt kỹ thuật và tư duy hệ thống trong suốt quá trình nghiên cứu. Những góp ý đầy tận tâm của cô chính là kim chỉ nam giúp Notopia hình thành và hoàn thiện như ngày hôm nay.

Đồng thời, nhóm xin gửi lời cảm ơn chân thành đến Khoa Công nghệ Phần mềm, trường Đại học Công nghệ Thông tin – ĐHQG TP.HCM. Cảm ơn Nhà trường đã tạo dựng một môi trường học tập hiện đại, cung cấp nền tảng tri thức và cơ sở vật chất tốt nhất để chúng em thực hiện đề tài này.

Mặc dù đã dồn hết tâm sức, song đồ án chắc chắn vẫn còn những điểm cần cải thiện. Chúng em rất mong nhận được sự chỉ dẫn và đóng góp từ quý thầy cô để nhóm có thể phát triển ứng dụng ngày một hoàn thiện hơn.

Đề tài tập trung nghiên cứu và xây dựng “Notopia - Ứng dụng ghi chú thông minh hỗ trợ quản lý tri thức bằng biểu đồ quan hệ”, với mục đích giúp người dùng quản lý tri thức cá nhân trên một nền tảng web trực quan, cộng tác theo thời gian thực. Đề tài không hướng đến việc giải quyết các nhược điểm của các nền tảng sẵn có trên thị trường, mà thay vào đó tập trung nghiên cứu kiến trúc, phương pháp phát triển phần mềm, triển khai hệ thống, khai thác và sử dụng các công nghệ hiện đại.

Báo cáo trình bày các nghiên cứu, quy trình thiết kế, cài đặt và triển khai hệ thống thông qua các chương sau:

• Chương 1. Giới thiệu đề tài – Giới thiệu về đề tài, mục tiêu nghiên cứu, phạm vi của báo cáo, các tính năng, công nghệ được sử dụng trong đề tài.
• Chương 2. Cơ sở lý thuyết – Cơ sở lý thuyết liên quan, các công nghệ và phương pháp phát triển phần mềm được sử dụng trong đề tài.
• Chương 3. Phân tích và thiết kế hệ thống – Mô tả kiến trúc hệ thống, các đặc tả use case, API, các thành phần chính của hệ thống, cơ sở dữ liệu, một số mô hình và logic của hệ thống.
• Chương 4. Xây dựng ứng dụng – Trình bày kết quả thực hiện giao diện, chức năng của Web App.
• Chương 5. Kết luận – Kết luận về kết quả đạt được, những thuận lợi, khó khăn, ưu điểm và hướng phát triển trong tương lai của đề tài.

Chương này trình bày bối cảnh thực tiễn và lý do lựa chọn đề tài, từ đó làm rõ mục tiêu, phạm vi và đối tượng nghiên cứu của dự án. Nội dung của chương nhằm giúp người đọc có cái nhìn toàn diện về định hướng nghiên cứu, cơ sở khoa học và giá trị ứng dụng thực tiễn của đề tài trước khi đi sâu vào các chương phân tích và thiết kế chi tiết ở các phần tiếp theo.

1.1. Lý do chọn đề tài

Trong kỷ nguyên bùng nổ thông tin, việc quản lý kiến thức cá nhân (Personal Knowledge Management - PKM) trở thành một kỹ năng thiết yếu. Các phương pháp ghi chú truyền thống theo dạng danh sách hoặc thư mục dần bộc lộ hạn chế trong việc kết nối các ý tưởng rời rạc. Lấy cảm hứng từ các ứng dụng như Notion, Obsidian, chúng em xây dựng nền tảng ghi chú hiện đại hỗ trợ liên kết hai chiều¹, kết hợp trực quan hóa kiến thức thành biểu đồ quan hệ.

1.2. Mục đích và mục tiêu nghiên cứu

1.2.1. Mục đích nghiên cứu

Xây dựng nền tảng web quản lý tri thức cá nhân, trực quan hoá bằng biểu đồ quan hệ (Graph View), cộng tác theo thời gian thực. Ứng dụng cung cấp các chức năng ghi chú cơ bản: tạo, sửa, xoá tạm thời, xoá vĩnh viễn, khôi phục, tìm kiếm toàn văn (full-text search) và phân quyền truy cập không gian làm việc (workspace).

1.2.2. Mục tiêu nghiên cứu

• Nghiên cứu các phương pháp tổ chức ghi chú dạng cấu trúc thư mục.
• Nghiên cứu cách thức liên kết các ghi chú với nhau để tạo thành mạng lưới tri thức.
• Tích hợp thư viện soạn thảo nội dung ghi chú (block-based editor) với cách quản lý đối tượng trong hệ thống.
• Nghiên cứu cách triển khai cộng tác theo thời gian thực.
• Định danh, phân quyền người dùng đối với không gian làm việc.
• Thiết kế kiến trúc hệ thống dễ mở rộng, bảo trì và có hiệu suất cao.

1.3. Đối tượng và phạm vi nghiên cứu

1.3.1. Đối tượng nghiên cứu

Đối tượng nghiên cứu về mặt nghiệp vụ

• Hệ thống quản lý tri thức cá nhân (Personal Knowledge Management - PKM): Nghiên cứu mô hình lưu trữ và kết nối các ý tưởng rời rạc thành mạng lưới tri thức.
• Cấu trúc dữ liệu ghi chú: Loại định dạng nội dung ghi chú Block-based với thư viện BlockNote.
• Luồng tương tác cộng tác: Cơ chế đồng bộ dữ liệu khi nhiều người cùng làm việc trên một tài liệu (CRDT) và không gian làm việc.

CRDT

Conflict-free Replicated Data Type, cấu trúc dữ liệu cho phép hợp nhất tự động các thay đổi từ nhiều người dùng mà không gây xung đột, phù hợp cho ứng dụng cộng tác thời gian thực.

Đối tượng nghiên cứu về mặt kỹ thuật

• Kiến trúc hệ thống: Áp dụng Microservices kết hợp Clean Architecture, Domain Driven Design, Event Driven Architecture cho domain phức tạp, đảm bảo tính mở rộng.
• Cơ chế liên kết và truy vấn dữ liệu: Cách thức triển khai liên kết hai chiều và truy vấn quan hệ giữa các ghi chú để tạo Graph View.
• Giao thức kết nối: Sử dụng Rest API để giao tiếp giữa Web App với API service, SSE để cập nhật thông tin thời gian thực², và gRPC để giao tiếp giữa các service trong hệ thống.
• Công nghệ tìm kiếm: Cách tích hợp Full-text search để hỗ trợ người dùng truy xuất thông tin.
• Hạ tầng và vận hành: Nghiên cứu việc triển khai hệ thống với Docker, quản lý định danh, phân quyền, giám sát hệ thống (Observation).

SSE

Server-Sent Events, công nghệ cho phép máy chủ gửi dữ liệu thời gian thực đến trình duyệt mà không cần WebSocket phức tạp.

1.3.2. Phạm vi nghiên cứu

Định danh người dùng (Identity)

Sử dụng dịch vụ thứ bên thứ 3 để quản lý đăng ký, đăng nhập, thông qua OAuth2/OpenID Connect, đảm bảo an toàn và dễ dàng tích hợp với các dịch vụ khác trong hệ thống.

Ghi chú (Note)

Quản lý không gian làm việc, sắp xếp các ghi chú theo cấu trúc thư mục, biểu diễn quan hệ giữa các ghi chú, hỗ trợ cộng tác theo thời gian thực ở góc độ lưu trữ và tổ chức thông tin.

Tài liệu (Document)

Nội dung ghi chú được lưu trữ dưới dạng tài liệu Block-based (BlockNote), cho phép trình bày và chỉnh sửa linh hoạt, đồng thời hỗ trợ cộng tác thời gian thực. Tệp tin đính kèm được lưu qua Object Storage.

Phân quyền (Authorization)

Quản lý quyền truy cập vào không gian làm việc. Không gian làm việc có thể chia sẻ với nhiều người dùng với quyền hạn khác nhau, đảm bảo an toàn và kiểm soát truy cập.

Tìm kiếm (Search)

Lắng nghe và đồng bộ nội dung ghi chú khi thay đổi đến dịch vụ tìm kiếm bên thứ ba.

Hạ tầng (Infrastructure)

• Thiết kế kiến trúc hệ thống theo mô hình Microservices, giao tiếp nội bộ qua gRPC và message broker cho tác vụ bất đồng bộ.
• Triển khai quy trình CI/CD, đóng gói ứng dụng vào container.
• API được thiết kế đứng sau một API Gateway.
• Xây dựng hệ thống giám sát để theo dõi vết (tracing), chỉ số đo lường (metric) và nhật ký hệ thống (logging) trong môi trường phân tán.

1.4. Phương pháp nghiên cứu

Dự án áp dụng phương pháp tiếp cận kỹ thuật hệ thống, kết hợp nghiên cứu lý thuyết quản lý tri thức và triển khai thực nghiệm công nghệ phần mềm.

Phương pháp thu thập và phân tích yêu cầu

Khảo sát các ứng dụng quản lý ghi chú hiện có (Notion, Obsidian, jackyzha0/quartz) để rút ra các tính năng cần thiết.

Phương pháp thiết kế và mô hình hoá hệ thống

Sử dụng UML cho sơ đồ lớp (class diagram) và sơ đồ tuần tự (sequence diagram). Dùng D2 cho sơ đồ triển khai (deployment diagram) và cơ sở dữ liệu quan hệ. Trong đó:

• Đối với sơ đồ tuần tự, chỉ đặc tả các use case quan trọng để làm rõ luồng tương tác giữa các thành phần chính của hệ thống.
• Đối với class diagram, chỉ tập trung vào các lớp cốt lõi liên quan đến nghiệp vụ chính của hệ thống, tránh mô hình hoá chi tiết quá mức làm rối sơ đồ.

Phương pháp phát triển API

Thiết kế API theo chuẩn RESTful, sử dụng OpenAPI 3.0 để mô tả API giữa Web App và API service, Protocol Buffers 3 cho giao tiếp giữa các service nội bộ. Áp dụng hướng tiếp cận “Contract First”, đảm bảo tính nhất quán từ giai đoạn thiết kế đến triển khai.

Nhờ đặc tả này, có thể tự động sinh mã nguồn client và server, giảm lỗi và tăng tốc phát triển.

1.5. Chức năng

Notopia là nền tảng quản lý tri thức cá nhân, hỗ trợ người dùng tổ chức, kết nối và trực quan hóa kiến thức trên web với khả năng cộng tác thời gian thực. Các nhóm chức năng chính bao gồm:

Tạo và quản lý không gian làm việc

Người dùng có thể tạo các không gian làm việc riêng biệt, chia sẻ và quản lý quyền truy cập linh hoạt. Mỗi không gian là vùng lưu trữ độc lập cho ghi chú và dự án.

Tổ chức ghi chú theo cấu trúc thư mục

Người dùng sắp xếp ghi chú thành thư mục lồng nhau, tạo cấu trúc dữ liệu rõ ràng, giúp quản lý số lượng lớn ghi chú hiệu quả.

Tạo các liên kết hai chiều giữa ghi chú

Người dùng liên kết ghi chú qua cơ chế liên kết hai chiều, tạo mạng lưới tri thức động. Hệ thống tự động ghi nhận backlink, giúp hiểu rõ mối quan hệ giữa các ý tưởng.

Soạn thảo nội dung dạng block-based

Nội dung ghi chú được tổ chức thành các khối độc lập, cho phép linh hoạt xây dựng và chỉnh sửa tài liệu. Mỗi khối có thể là văn bản, hình ảnh, mã code hoặc loại nội dung khác.

Cộng tác theo thời gian thực

Nhiều người dùng có thể làm việc đồng thời trên cùng ghi chú. Hệ thống đồng bộ thay đổi tức thời và giải quyết xung đột tự động.

Trực quan hóa mối quan hệ bằng biểu đồ quan hệ

Người dùng xem mạng lưới tri thức dưới dạng biểu đồ quan hệ (Graph View), hiển thị liên kết và mối quan hệ giữa các ghi chú, trực quan hơn cách tổ chức tuyến tính truyền thống.

Tìm kiếm nhanh chóng

Hệ thống hỗ trợ tìm kiếm toàn văn trên mọi nội dung ghi chú, giúp người dùng nhanh chóng tìm ra thông tin cần thiết.

Quản lý quyền truy cập và phân quyền

Chủ sở hữu không gian làm việc quản lý quyền từng thành viên (xem, chỉnh sửa, xóa) với nhiều cấp độ quyền, đảm bảo an toàn và kiểm soát truy cập.

Quản lý vòng đời tài liệu

Ghi chú có thể xóa tạm thời (vào thùng rác) hoặc xóa vĩnh viễn. Người dùng có thể khôi phục ghi chú đã xóa tạm thời, tránh mất dữ liệu.

1.6. Công nghệ sử dụng

Notopia ứng dụng bộ công nghệ được lựa chọn kỹ lưỡng, đảm bảo mở rộng, hiệu suất cao và bảo trì dài hạn.

Web App

• Framework: Next.js (React), cung cấp server-side rendering và tối ưu hiệu suất.
• State Management: Redux Toolkit với DevTools và middleware mạnh mẽ.
• Styling: TailwindCSS, PostCSS và ShadcnUI.
• Editor Content: BlockNote (block-based, trên Tiptap) với tùy chỉnh cao.

Backend

• Identity service (Authentik): Identity provider mã nguồn mở hỗ trợ OAuth2/OIDC.
• document service: NestJS (TypeScript), kiến trúc mô-đun, build với Rspack.
• notes service: Go với SQLC cho raw SQL tối ưu, phù hợp truy vấn đồ thị phức tạp.
• authorization service: Go với Casbin (RBAC) cho quản lý quyền linh hoạt.
• search-worker: NestJS lắng nghe thay đổi dữ liệu và đồng bộ với Meilisearch.
• Search Service (Meilisearch): Search engine mã nguồn mở (Rust), tìm kiếm toàn văn nhanh và dễ triển khai.

Cơ sở dữ liệu

• PostgreSQL: Hệ quản trị cơ sở dữ liệu quan hệ mạnh mẽ, tuân thủ ACID transactions và hỗ trợ các tính năng nâng cao.
• ORM/Query Builder/Query codegen: TypeORM cho NestJS service, SQLC cho Go service để tối ưu hiệu suất.

Cộng tác theo thời gian thực

• yjs: Thư viện CRDT cho phép hợp nhất tự động các thay đổi từ nhiều người dùng mà không gây xung đột.
• Hocuspocus: Máy chủ WebSocket cho Yjs, abstract hóa yjs nên không cần quan tâm chi tiết triển khai.

Giao tiếp API

• REST API: Thiết kế theo OpenAPI 3.0 cho giao tiếp frontend-backend.
• gRPC: Framework RPC sử dụng Protocol Buffers, cung cấp hiệu suất cao cho giao tiếp giữa các dịch vụ nội bộ.

Bên cạnh đó, các dịch vụ không hỗ trợ gRPC có SDK hoặc REST API (ví dụ Authentik có SDK cho Go và NodeJS).

Kiến trúc sự kiện

• Watermill: Thư viện Go cho event-driven architecture, hỗ trợ nhiều message broker khác nhau.
• Redpanda: Message broker tương thích với Kafka, được sử dụng cho streaming sự kiện phân tán.

NestJS hỗ trợ sẵn event-driven architecture, không cần thư viện ngoài.

Giám sát

• OpenTelemetry: Tiêu chuẩn mã nguồn mở cho metrics, logs và traces.
• Grafana Stack: Prometheus (metrics), Loki (logs), Tempo (distributed tracing), Grafana (visualization). Alloy agent cho forwarding logs và metrics.

Hạ tầng

• Docker: Đóng gói ứng dụng, đảm bảo nhất quán giữa các môi trường.
• Traefik: API Gateway với routing, load balancing và auto-discovery.
• RustFS: Object storage mã nguồn mở cho tệp đính kèm trong ghi chú.

2.1. Tổng quan về Go (Golang)

2.1.1. Giới thiệu

Go (còn gọi là Golang) là ngôn ngữ lập trình mã nguồn mở được phát triển bởi Google vào năm 2007 và chính thức phát hành vào năm 2009. Được thiết kế bởi Robert Griesemer, Rob Pike và Ken Thompson, Go nhằm mục tiêu tạo ra một ngôn ngữ hiệu quả, dễ học, và phù hợp cho lập trình hệ thống quy mô lớn.

Dự án sử dụng Go cùng với công cụ goforj/wire, một fork của google/wire, giúp dependencies injection có hỗ trợ cache fast để tối ưu thời gian build.

2.1.2. Ưu điểm

Go mang lại nhiều lợi ích trong phát triển backend:

• Biên dịch native code, hiệu suất tương đương C/C++
• Goroutines và Channels xử lý đồng thời với chi phí thấp
• Single binary, không phụ thuộc thư viện ngoài
• Cross-compilation cho nhiều nền tảng từ một máy
• Được dùng trong Kubernetes, Docker, Terraform, Prometheus

2.1.3. Nhược điểm

Bên cạnh các ưu điểm, Go có một số hạn chế:

• Error handling dài dòng với if err != nil
• Thiếu Generics trước 1.18, không hỗ trợ generic method.³
• Không có inheritance, chỉ hỗ trợ composition
• Cần thời gian để hiểu interfaces và goroutines

2.2. Tổng quan về TypeScript

2.2.1. Giới thiệu

TypeScript là một ngôn ngữ lập trình mã nguồn mở được phát triển và duy trì bởi Microsoft. TypeScript là một superset của JavaScript, nghĩa là mọi code JavaScript hợp lệ đều là code TypeScript hợp lệ. Được ra mắt lần đầu vào năm 2012 bởi Anders Hejlsberg (người thiết kế C#), TypeScript bổ sung hệ thống kiểu dữ liệu tĩnh trên nền tảng JavaScript để tăng độ tin cậy và khả năng duy trì của code.

TypeScript hoạt động thông qua một bước biên dịch: mã TypeScript được biên dịch thành mã JavaScript, sau đó được chạy trên JavaScript runtime (trình duyệt hoặc Node.js).

2.2.2. Ưu điểm

TypeScript mang lại nhiều lợi ích khi phát triển ứng dụng JavaScript:

• Phát hiện lỗi compile-time, giảm bugs
• Types tự động document code
• Tương thích mọi thư viện JavaScript

2.2.3. Nhược điểm

Bên cạnh các ưu điểm, TypeScript có một số hạn chế:

• Cần học type system và features như decorators, generics
• Cần biên dịch, tăng thời gian build
• Bước compile/transpile được thực hiện bằng nhiều công cụ

2.2.4. Hệ sinh thái và công cụ

Dự án microsoft/typescript-go đang phát triển một implementation của TypeScript được viết hoàn toàn bằng Go, thay vì TypeScript hiện tại được viết bằng TypeScript. Dự án này hướng tới việc cải thiện hiệu suất.

Dự án được thiết lập với monorepo, các package được chia build riêng biệt (SWC, Rspack, tsgo, vite) để tăng tốc thời gian build, Oxlint thay cho ESLint, Oxfmt thay cho Prettier để tăng tốc độ linting và formatting, CI, ngoại trừ web vì sử dụng NextJS.

2.3. Tổng quan về React và NextJS

2.3.1. Giới thiệu

Frontend của dự án được xây dựng với React, một thư viện JavaScript cho xây dựng user interfaces với component-based architecture. Next.js được sử dụng như một framework trên React, cung cấp server-side rendering, static generation, và routing tích hợp.

2.3.2. React

React là thư viện JavaScript mã nguồn mở từ Meta (Facebook) cho xây dựng user interfaces. React sử dụng virtual DOM để tối ưu rendering, component-based architecture cho reusability, và declarative syntax làm cho code dễ đọc hơn.

2.3.3. Next.js

Next.js là framework React được phát triển bởi Vercel, cung cấp Server-Side Rendering (SSR), Static Site Generation (SSG), Incremental Static Regeneration (ISR), và API routes tích hợp. Next.js giúp tối ưu hiệu suất và SEO mà không cần setup phức tạp.

2.3.4. Ưu điểm

React và NextJS mang lại nhiều lợi ích cho phát triển frontend:

• React: Component-based, tái sử dụng code, hệ sinh thái phong phú
• NextJS: Tối ưu sẵn có, zero-config, SEO tốt, API routes tích hợp

2.3.5. Nhược điểm

Bên cạnh các ưu điểm, các công nghệ frontend này có một số hạn chế:

• React: Learning curve cao, quản lý state phức tạp
• NextJS: Routing đôi khi không trực quan, SSR thêm độ phức tạp

2.4. Tổng quan về NestJS

2.4.1. Giới thiệu

NestJS là một framework progressive Node.js được xây dựng để phát triển các ứng dụng server-side hiệu quả, đáng tin cậy và có khả năng mở rộng cao. Được phát triển bởi Kamil Myśliwiec và ra mắt lần đầu vào năm 2017, NestJS kết hợp các khái niệm từ Angular, Spring Framework và các framework hiện đại khác.

NestJS được xây dựng trên nền tảng Express.js (hoặc Fastify) và sử dụng TypeScript làm ngôn ngữ chính. Framework này tổ chức code theo mô hình kiến trúc mô-đun rõ ràng, bao gồm controllers, services, middleware, guards, interceptors, và pipes, tương tự như Spring Framework của Java.

Trong dự án này, NestJS được xây dựng với:

• Rspack là bundler mới được hỗ trợ, với SWC cho quá trình transpile nhanh, đảm bảo thời gian build tối ưu

2.4.2. Ưu điểm

NestJS mang lại nhiều lợi ích cho phát triển backend:

• TypeScript đầy đủ, type-safety từ đầu
• Module-based, dễ tổ chức và bảo trì
• DI mạnh mẽ, dễ dàng testing
• Hỗ trợ unit test và e2e test sẵn có
• Nhiều packages chính thức (GraphQL, WebSockets, Microservices)
• Phù hợp microservices và monolithic

2.4.3. Nhược điểm

Bên cạnh các ưu điểm, NestJS có một số hạn chế:

• Cần học nhiều concepts (DI, decorators, modules, providers)
• Boilerplate code (decorators, providers, controllers, services)
• Abstraction layers ảnh hưởng hiệu suất nhẹ

2.5. Tổng quan về PostgreSQL

2.5.1. Giới thiệu

PostgreSQL (còn gọi là Postgres) là một hệ quản trị cơ sở dữ liệu quan hệ đối tượng (ORDBMS) mã nguồn mở, mạnh mẽ và tiên tiến. PostgreSQL được phát triển từ dự án POSTGRES tại Đại học California, Berkeley vào năm 1986 và đã phát triển hơn 35 năm với cộng đồng đóng góp tích cực.

PostgreSQL nổi tiếng vì sự tuân thủ nghiêm ngặt các chuẩn SQL, hỗ trợ ACID transactions đầy đủ, và khả năng mở rộng cao thông qua các kiểu dữ liệu tùy chỉnh và extensions như PostGIS, pgcrypto, và full-text search.

2.5.2. Ưu điểm

PostgreSQL mang lại nhiều lợi ích cho phát triển ứng dụng:

• ACID đầy đủ, đảm bảo toàn vẹn dữ liệu
• Hỗ trợ JSON/JSONB, arrays, custom types, geometric data
• Mở rộng qua extensions (PostGIS, pgcrypto, uuid-ossp)
• Full-text search tích hợp sẵn
• MVCC cho đọc/ghi đồng thời không cần locks
• Tuân thủ SQL chuẩn, hỗ trợ window functions, CTEs, lateral joins
• Mã nguồn mở, miễn phí, cộng đồng lớn

2.5.3. Nhược điểm

Bên cạnh các ưu điểm, PostgreSQL có một số hạn chế:

• Hiệu năng thấp hơn MySQL trong một số tác vụ, replication phức tạp hơn
• Nhiều features nâng cao cần thời gian thành thạo

2.6. Tổng quan về giải pháp chỉnh sửa cộng tác

2.6.1. Giới thiệu

Trong các ứng dụng cho phép nhiều người dùng cùng chỉnh sửa một tài liệu đồng thời, vấn đề cốt lõi là làm thế nào để đảm bảo tính nhất quán dữ liệu khi các thay đổi xảy ra song song từ nhiều nguồn khác nhau. Đây là bài toán đã được nghiên cứu sâu rộng trong lĩnh vực hệ thống phân tán và là nền tảng cho mọi công cụ cộng tác thời gian thực hiện đại.

Hiện nay có hai trường phái giải pháp được nghiên cứu và ứng dụng phổ biến nhất: Operational Transformation (OT) và Conflict-free Replicated Data Type (CRDT). Mỗi phương pháp tiếp cận bài toán theo một hướng khác nhau, với những đánh đổi riêng về độ phức tạp, hiệu suất và khả năng mở rộng.

2.6.2. Operational Transformation

Lịch sử

Operational Transformation được giới thiệu lần đầu vào năm 1989 bởi C. Ellis và S. Gibbs trong bài báo “Concurrency Control in Groupware Systems”. Bước ngoặt lớn đến vào năm 2009, khi Google công bố Google Wave và Google Docs sử dụng OT ở quy mô hàng triệu người dùng, đưa công nghệ này từ lý thuyết vào sản phẩm thương mại đại trà.

Nguyên lý hoạt động

Operational Transformation giải quyết xung đột bằng cách biến đổi các thao tác chỉnh sửa trước khi áp dụng chúng, sao cho kết quả cuối cùng luôn nhất quán bất kể thứ tự nhận được.

Khi người dùng A thực hiện thao tác X và người dùng B đồng thời thực hiện thao tác Y, hệ thống OT sẽ tính toán một phiên bản biến đổi X’ sao cho việc áp dụng X’ sau Y cho ra kết quả tương đương với việc áp dụng Y’ sau X. Quá trình biến đổi này thường được điều phối qua một máy chủ trung tâm đóng vai trò trọng tài, đảm bảo thứ tự các thao tác được xác định nhất quán trên tất cả các phiên làm việc.

Quay lại ví dụ trên, tài liệu đang có nội dung “Hello”. Người dùng A xóa ký tự tại vị trí 0, người dùng B chèn “!” vào vị trí 5. Khi máy chủ nhận được cả hai thao tác, nó nhận ra rằng xóa ký tự đầu đã thay đổi toàn bộ chỉ số vị trí, do đó sẽ biến đổi thao tác của B thành “chèn ‘!’ vào vị trí 4”. Kết quả cuối cùng trên cả hai phía là “ello!”, nhất quán và đúng đắn.

Ưu điểm

• Hiệu quả và tiết kiệm bộ nhớ trong các kịch bản ít xung đột, phù hợp với môi trường chỉnh sửa văn bản thông thường
• Biểu diễn dữ liệu gọn nhẹ, không cần lưu trữ metadata hay lịch sử thao tác dài hạn tại phía người dùng
• Đã được kiểm chứng qua hơn ba thập kỷ nghiên cứu và triển khai thực tế ở quy mô lớn
• Phản hồi tức thời với người dùng nhờ áp dụng thao tác ngay lập tức tại máy cục bộ trước khi đồng bộ

Nhược điểm

• Yêu cầu máy chủ trung tâm luôn sẵn sàng để điều phối và thực hiện các phép biến đổi, tạo ra điểm lỗi đơn
• Thuật toán biến đổi trở nên cực kỳ phức tạp khi mở rộng ra ngoài văn bản thuần túy, đặc biệt khi xử lý nhiều loại thao tác và nhiều người dùng đồng thời
• Không hỗ trợ làm việc ngoại tuyến một cách tự nhiên, người dùng thường bị chặn hoặc mất thay đổi khi mất kết nối
• Khó triển khai chính xác, nhiều cài đặt OT trong thực tế từng gặp lỗi tinh vi khi có từ ba người dùng trở lên chỉnh sửa đồng thời

2.6.3. CRDT

Lịch sử

Conflict-free Replicated Data Type được định nghĩa chính thức vào năm 2011 bởi Marc Shapiro, Nuno Preguiça, Carlos Baquero và Marek Zawirski tại INRIA. Ý tưởng khởi nguồn từ nhu cầu điện toán phân tán và di động, nơi kết nối mạng không ổn định. Khác với OT, CRDT thiết kế cấu trúc dữ liệu sao cho mọi cách kết hợp thay đổi đều cho ra cùng một kết quả, đảm bảo về mặt toán học thay vì thông qua điều phối tập trung.

Nguyên lý hoạt động

CRDT giải quyết bài toán xung đột theo hướng hoàn toàn khác: thay vì biến đổi thao tác sau khi xung đột xảy ra, CRDT thiết kế cấu trúc dữ liệu sao cho xung đột không bao giờ thực sự tồn tại.

Nguyên tắc cốt lõi là mỗi phần tử dữ liệu được gán một định danh duy nhất và bất biến, thường kết hợp giữa mã định danh của thiết bị và dấu thời gian logic (logical clock). Khi hai người dùng chèn nội dung vào cùng một vị trí, thay vì phải quyết định ai ưu tiên hơn, hệ thống sử dụng thứ tự toàn phần dựa trên các định danh này để sắp xếp chúng theo một thứ tự xác định và có thể tái lập lại trên mọi thiết bị. Kết quả là tất cả các bản sao sẽ tự động hội tụ về cùng trạng thái mà không cần bất kỳ sự điều phối trung tâm nào.

Có hai nhánh chính của CRDT:

• CRDT dựa trên trạng thái (state-based): đồng bộ bằng cách truyền toàn bộ trạng thái và thực hiện phép hợp nhất tại điểm nhận, đơn giản nhưng tốn băng thông hơn
• CRDT dựa trên thao tác (operation-based): đồng bộ bằng cách truyền các thao tác đã được thiết kế để có tính giao hoán, hiệu quả hơn nhưng yêu cầu đảm bảo thứ tự phân phối

Ưu điểm

• Hỗ trợ làm việc ngoại tuyến hoàn toàn tự nhiên, dữ liệu tự động hội tụ khi kết nối được khôi phục
• Không phụ thuộc vào máy chủ trung tâm, có thể hoạt động theo mô hình ngang hàng giữa các thiết bị
• Đảm bảo tính hội tụ về mặt toán học, loại bỏ hoàn toàn các trường hợp phân kỳ dữ liệu
• Phù hợp với các cấu trúc dữ liệu phức tạp như cây lồng nhau, danh sách, tập hợp và đồ thị

Nhược điểm

• Tiêu thụ bộ nhớ lớn hơn do phải lưu trữ metadata và thông tin định danh cho từng phần tử
• Có thể tạo ra lưu lượng mạng lớn hơn, đặc biệt với cách tiếp cận dựa trên trạng thái
• Độ phức tạp khái niệm cao, đòi hỏi sự hiểu biết sâu về lý thuyết để thiết kế và tối ưu đúng cách
• Một số thao tác như xóa đồng thời với thao tác khác tại cùng vị trí cần xử lý cẩn thận để tránh các kết quả bất ngờ

2.6.4. So sánh

Có thể tham khảo thêm video “CRDTs: The Hard Parts” của Martin Kleppmann [2] và “How Collaborative Text Editors Don’t Break” của PawelCodeStuff [3] để có cái nhìn sâu hơn về các khía cạnh kỹ thuật và thực tiễn của hai phương pháp này.

2.6.5. Ứng dụng trong thực tế

Trong thực tế, các sản phẩm lớn đưa ra những lựa chọn khác nhau dựa trên yêu cầu cụ thể của từng trường hợp sử dụng.

Google Docs sử dụng OT với kiến trúc tập trung, phù hợp với văn bản thuần túy. Figma ban đầu dùng OT nhưng chuyển sang CRDT vào năm 2019 vì thiết kế đồ họa có cấu trúc phức tạp hơn. Notion và Linear áp dụng cách tiếp cận kết hợp: CRDT cho cấu trúc tài liệu và OT cho nội dung văn bản bên trong mỗi khối.

2.6.6. Lý do lựa chọn CRDT cho dự án

Dự án lựa chọn CRDT thông qua thư viện Yjs (Chương 2.7) dựa trên một số yêu cầu cụ thể của ứng dụng ghi chú cộng tác.

Trước tiên, khả năng làm việc ngoại tuyến là yêu cầu quan trọng với người dùng ghi chú. Khác với Google Docs vốn luôn yêu cầu kết nối ổn định, người dùng cần tiếp tục ghi chú ngay cả khi mất mạng và dữ liệu phải đồng bộ tự động khi kết nối được khôi phục, không cần thao tác thủ công.

Tiếp theo, BlockNote (Chương 2.11), thư viện soạn thảo được lựa chọn cho dự án, có tích hợp sẵn với Yjs, giúp giảm đáng kể công sức triển khai tính năng cộng tác mà không cần xây dựng lại từ đầu.

Cuối cùng, kiến trúc không phụ thuộc vào một máy chủ điều phối duy nhất mang lại khả năng mở rộng và khả năng chịu lỗi tốt hơn so với kiến trúc OT truyền thống, đặc biệt khi số lượng người dùng đồng thời trên một tài liệu tăng cao.

2.7. Tổng quan về Yjs

2.7.1. Giới thiệu

Yjs là thư viện CRDT (Conflict-free Replicated Data Type) viết bằng JavaScript, hỗ trợ real-time collaboration [4]. CRDT cho phép thay đổi từ nhiều người dùng tự động hợp nhất mà không cần xử lý xung đột thủ công.

2.7.2. Kiến trúc

Yjs được tổ chức xoay quanh các khái niệm chính sau:

• Y.Doc: đơn vị trung tâm đại diện cho tài liệu collaborative, chứa shared data types và quản lý đồng bộ giữa các peer. Mỗi Y.Doc có clientID duy nhất để phân biệt thay đổi từ những người dùng khác nhau.

• Shared Data Types: kiểu dữ liệu đặc biệt tự động đồng bộ giữa các peer, hoạt động tương tự kiểu JavaScript nhưng hợp nhất xung đột không cần máy chủ trung tâm và hỗ trợ observe thay đổi.

• Provider: kết nối Y.Doc với peer khác qua các giao thức mạng, từ WebSocket đến WebRTC peer-to-peer hoặc dịch vụ đám mây.

• Editor Binding: cầu nối đồng bộ shared types với editor phổ biến, biến editor thông thường thành collaborative editor.

2.7.3. Shared Data Types

Yjs cung cấp sáu shared data types, mỗi loại phục vụ mục đích khác nhau. Có thể lấy từ Y.Doc qua getter hoặc khởi tạo trực tiếp làm nested types.

Mỗi shared type hỗ trợ observe để theo dõi thay đổi:

• observe(): lắng nghe thay đổi trực tiếp trên type, trả về delta (Y.Array, Y.Text) hoặc key change (Y.Map)
• observeDeep(): lắng nghe thay đổi trên toàn bộ cây shared types, gồm nested types

2.7.4. Editor Bindings

Yjs không đi kèm editor riêng mà tích hợp với editor phổ biến qua binding. Editor binding là cầu nối giữa Y.Text/Y.XmlFragment và editor, tự động đồng bộ nội dung và con trỏ.

2.7.5. Connection Providers

Provider truyền tải thay đổi của Y.Doc giữa các peer, từ giao thức peer-to-peer đến dịch vụ đám mây có quản lý.

Dự án chọn Hocuspocus [5] làm provider chính nhờ khả năng mở rộng và tích hợp sâu với Tiptap/BlockNote.

2.7.6. Undo/Redo Manager

Yjs cung cấp Y.UndoManager cho undo/redo trên shared types. Hỗ trợ scoped tracking (chỉ undo thay đổi từ nguồn cụ thể), capture timeout (gộp thay đổi trong 500ms), và metadata (ví dụ vị trí con trỏ).

2.7.7. Awareness

Awareness chia sẻ thông tin trạng thái tạm thời giữa người dùng (con trỏ, vùng chọn, tên, màu sắc) thông qua CRDT riêng trong y-protocols. Dữ liệu tự động xóa khi người dùng ngắt kết nối, client không gửi tín hiệu trong 30 giây bị đánh dấu offline.

2.7.8. Ưu điểm

Yjs mang lại nhiều lợi ích:

• CRDT-Based Merging: xung đột tự động giải quyết, không cần quản lý thủ công
• Offline-First: làm việc offline, đồng bộ khi quay lại online
• Framework Agnostic: độc lập UI framework, tích hợp với bất kỳ framework nào
• Hiệu suất cao: tối ưu xử lý thay đổi lớn hiệu quả
• Hệ sinh thái phong phú: nhiều editor binding và connection provider

2.7.9. Nhược điểm

Yjs có một số hạn chế:

• Complexity: CRDT phức tạp, cần hiểu rõ để tối ưu hiệu suất
• Memory Usage: lưu trữ lịch sử thay đổi tiêu thụ bộ nhớ đáng kể với tài liệu lớn và nhiều người dùng
• Network Bandwidth: đồng bộ tạo lưu lượng lớn với thay đổi tần suất cao, đặc biệt với state-based CRDT
• Learning Curve: cần thời gian để hiểu cách sử dụng và tích hợp
• UndoManager với nhiều nguồn: khó undo chỉ thay đổi của user cụ thể nếu thiếu cấu hình trackedOrigins phù hợp

2.8. Tổng quan về ProseMirror

2.8.1. Giới thiệu

ProseMirror là toolkit xây dựng rich text editor trên nền tảng web, phát triển bởi Marijn Haverbeke [6]. Không giống editor truyền thống cung cấp sẵn giao diện soạn thảo, ProseMirror cung cấp các viên gạch nền tảng để tự xây dựng editor phù hợp.

ProseMirror sử dụng document model có cấu trúc chặt chẽ thay vì xử lý HTML tự do, cho phép kiểm soát chính xác nội dung và hỗ trợ các tính năng nâng cao như collaborative editing, schema validation và transform recording.

2.8.2. Kiến trúc

2.8.3. ProseMirror như một Editor Binding cho Yjs

Trong dự án, ProseMirror đóng vai trò editor binding cho Yjs qua y-prosemirror:

• Yjs quản lý trạng thái cộng tác qua shared types (Chương 2.7), đảm bảo dữ liệu hội tụ giữa các client mà không cần authority tập trung
• ProseMirror cung cấp document model có cấu trúc và transform để ánh xạ từ Y.XmlFragment hoặc Y.Text thành tài liệu editor
• y-prosemirror kết nối hai hệ thống, tạo collaborative editor hoàn chỉnh

2.8.4. Vai trò so với Tiptap

ProseMirror là nền tảng cấp thấp xây dựng editor. Trong dự án, BlockNote sử dụng Tiptap làm lớp trung gian trên ProseMirror. Như vậy, ProseMirror là lõi hệ thống editor nhưng không dùng trực tiếp mà qua Tiptap.

2.9. Tổng quan về Tiptap

2.9.1. Giới thiệu

Tiptap là headless rich text editor framework trên nền tảng ProseMirror [7], thuộc tổ chức ueberdosis (Tiptap Collective), cùng tổ chức phát triển Hocuspocus.

Khác biệt cốt lõi với ProseMirror là mức độ trừu tượng: ProseMirror là toolkit cấp thấp cung cấp công cụ nền tảng, Tiptap là framework hoàn chỉnh với API thân thiện, kiến trúc extension linh hoạt và tích hợp sẵn nhiều UI framework.

2.9.2. Kiến trúc

Tiptap được thiết kế theo ba trụ cột chính:

• Extensions: đơn vị chức năng cơ bản, định nghĩa node, mark hoặc chức năng (placeholder, collaboration, undo/redo). Cho phép lắp ráp editor từ module nhỏ.
• Commands: hàm thao tác editor, có thể xích chuỗi, mỗi command trả về true nếu thành công.
• Events: hệ thống sự kiện vòng đời, can thiệp vào quá trình xử lý từ tạo tài liệu đến focus/blur.

2.9.3. So sánh với ProseMirror

Bảng dưới đây phân biệt rõ vai trò của ProseMirror và Tiptap trong hệ sinh thái:

2.9.4. Tích hợp Yjs và Cộng tác

Tiptap cung cấp extension @tiptap/extension-collaboration tích hợp Yjs (Chương 2.7):

• Đồng bộ nội dung editor với Y.Text/Y.XmlFragment qua y-prosemirror
• Tích hợp UndoManager của Yjs, thay thế undo/redo mặc định
• Hỗ trợ awareness hiển thị con trỏ cộng tác viên

Kết hợp với Hocuspocus (Chương 2.10), Tiptap trở thành collaborative editor hoàn chỉnh với máy chủ đồng bộ qua WebSocket.

2.9.5. Vai trò với BlockNote

BlockNote (Chương 2.11) xây dựng trên Tiptap và ProseMirror: ProseMirror là động cơ (document model, transform, state management), Tiptap là khung gầm (extension system, commands, events), BlockNote là thân xe hoàn chỉnh (block component cho soạn thảo block-based).

2.10. Tổng quan về Hocuspocus

2.10.1. Giới thiệu

Hocuspocus là server WebSocket chuyên dụng cho Yjs, phát triển bởi Tiptap Collective (ueberdosis) [5] – cùng tổ chức đứng sau Tiptap, thiết kế làm backend collaboration cho editor dựa trên ProseMirror và Tiptap.

Hocuspocus đóng vai trò trung gian giữa các client, nhận và phân phối cập nhật Yjs document qua WebSocket, đồng thời quản lý persistence, authentication, awareness và cung cấp hệ thống extension.

2.10.2. Kiến trúc

Hocuspocus được thiết kế theo kiến trúc server-client đơn giản:

• Hocuspocus Server: tiến trình server, quản lý kết nối WebSocket, đồng bộ Yjs documents và phân phối cập nhật đến client trong cùng phòng (room).

• Hocuspocus Provider: thư viện client (@hocuspocus/provider), kết nối server qua WebSocket, đồng bộ Y.Doc, quản lý vòng đời kết nối, xác thực và awareness.

Mỗi tài liệu xác định bởi tên phòng (room name). Client kết nối cùng phòng tự động đồng bộ tài liệu Yjs tương ứng.

Luồng hoạt động:

1. Client khởi tạo HocuspocusProvider với WebSocket server, tên phòng và Y.Doc
2. Provider kết nối server qua WebSocket, kèm token xác thực (nếu cấu hình)
3. Server xác thực qua hook onAuthenticate, nếu thành công mở phiên làm việc
4. Server tải tài liệu từ persistence (nếu có) và đồng bộ với client
5. Client thay đổi, Yjs update gửi lên server và phân phối đến client khác
6. Server định kỳ lưu tài liệu xuống persistence qua extension

2.10.3. Extension System

Hocuspocus có hệ thống extension mở rộng chức năng server qua hook vòng đời:

• Persistence: lưu trữ tài liệu. Extension có sẵn:

  1. @hocuspocus/extension-sqlite: SQLite
  2. @hocuspocus/extension-postgresql: PostgreSQL
  3. @hocuspocus/extension-s3: S3-compatible storage
  4. @hocuspocus/extension-redis: đồng bộ nhiều instance server

• Authentication: xác thực qua hook onAuthenticate, kiểm tra token, API key

• Lifecycle Hooks: onConnect, onLoadDocument, onChange, onStoreDocument, onDisconnect

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

Tính năng chính:

• Real-time đồng bộ: WebSocket truyền tải Yjs updates độ trễ thấp
• Persistence tự động: lưu trữ và khôi phục khi server khởi động lại
• Horizontal scaling: Redis extension đồng bộ giữa nhiều instance server
• Awareness: quản lý trạng thái trực tuyến qua awareness CRDT của Yjs
• Direct Connection API: REST API thao tác trực tiếp Y.Doc, hỗ trợ ghi nội dung từ server hoặc batch jobs
• Stateless Messages: gửi thông điệp tùy chỉnh giữa client, không lưu trong Y.Doc

2.10.5. Vai trò trong dự án

Trong dự án, Hocuspocus là provider chính cho Yjs (Chương 2.7) vì:

• Tích hợp sâu với Tiptap và BlockNote (cùng hệ sinh thái)
• Extension system tùy chỉnh persistence, authentication và hook xử lý
• Mở rộng ngang qua Redis, phù hợp khi số lượng người dùng tăng cao
• Mã nguồn mở, tự triển khai hoặc dùng bản đám mây

2.11. Tổng quan về BlockNote

2.11.1. Giới thiệu

BlockNote là một thư viện editor được xây dựng trên nền tảng Tiptap và ProseMirror [8]. BlockNote cung cấp một công cụ soạn thảo văn bản phong phú với kiến trúc block-based tương tự như Notion, cho phép người dùng xây dựng các khối nội dung một cách linh hoạt.

BlockNote được thiết kế để dễ tích hợp vào các ứng dụng React (Chương 2.3.2), với API rõ ràng và khả năng tùy chỉnh cao, tương thích với màu sắc của shadcnui . Thư viện này hoạt động dựa trên ProseMirror, một editor framework mạnh mẽ và có cấu trúc rõ ràng. Có thể hình dung ProseMirror như một bộ công cụ xây dựng editor, trong khi BlockNote là một implementation cụ thể, dễ dàng sử dụng nhanh.

BlockNote là một hệ sinh thái mã nguồn mở hoàn toàn, miễn phí sử dụng công cộng. Chỉ riêng các gói thư viện @blocknote/xl-* có giấy phép copyleft, yêu cầu mua giấy phép nếu sử dụng trong sản phẩm mã nguồn đóng, hoặc thương mại.

2.11.2. Model dữ liệu của BlockNote

Model dữ liệu của BlockNote được tổ chức thành các block, mỗi block đại diện cho một phần nội dung riêng biệt, như đoạn văn, hình ảnh, bảng,… Mỗi block có một cấu trúc dữ liệu riêng, bao gồm loại block, nội dung và các thuộc tính liên quan (xem thêm về cấu trúc dữ liệu của block trong BlockNote tại Phụ lục A.1).

2.11.3. Ưu điểm

BlockNote mang lại nhiều lợi ích cho phát triển editor:

• Kiến trúc block-based, tổ chức nội dung thành khối độc lập
• Xây dựng trên Tiptap, kế thừa toàn bộ tính năng
• Dễ thêm/xoá tính năng qua extension
• Thiết kế tối ưu cho React với hooks và component API
• Tích hợp Yjs và CRDT cho cộng tác thời gian thực
• Hỗ trợ text, image, video, code blocks, tables,…

2.11.4. Nhược điểm

Bên cạnh các ưu điểm, BlockNote có một số hạn chế:

• Cần thời gian để hiểu kiến trúc block-based và cách tùy chỉnh
• Một số tính năng yêu cầu trình duyệt hiện đại

2.12. Tổng quan về OpenAPI

2.12.1. Giới thiệu

OpenAPI là một specification cho mô tả HTTP APIs theo cách chuẩn hóa. OpenAPI cho phép sinh code từ contracts, tạo điều kiện cho contract-first development, và tự động tạo documentation.

OpenAPI (trước đây được gọi là Swagger) là một format standardized cho mô tả RESTful APIs. OpenAPI specification định nghĩa endpoints, parameters, request/response schemas, và error codes theo cách machine-readable.

2.12.2. Tooling Ecosystem

• Redocly: Tool cho OpenAPI specification, trong dự án sử dụng làm language server, linter, bundle các file nhỏ thành một file lớn
• Scalar: Tool cho OpenAPI specification, tương đối giống redocly, trong dự án sử dụng để render website documentation từ OpenAPI spec
• heyapi/openapi-ts [9] sinh TypeScript types từ OpenAPI spec
• oapi-codegen [10] sinh Go code từ OpenAPI spec, hỗ trợ HTTP API generation
• OpenAPI Generator [11]: Tool đa ngôn ngữ cho code generation từ OpenAPI spec, hỗ trợ nhiều languages và frameworks, trong dự án sử dụng generator typescript-nestjs-server [12]

2.12.3. Contract-First Development

Contract-first approach định nghĩa API contracts trước khi implement logic, đảm bảo tính consistency, tạo điều kiện cho parallel development, và giảm integration issues.

2.12.4. Ưu điểm

• API contracts rõ ràng trước implementation
• Frontend và backend phát triển song song
• Code generation tạo type-safe clients và servers
• Tự động documentation từ contracts
• Rộng rãi tooling hỗ trợ

2.12.5. Nhược điểm

• Cần cập nhật spec khi API thay đổi
• Code generation pipeline cần cấu hình
• Cần học OpenAPI specification
• Cần maintain generation scripts và tooling

2.13. Tổng quan về Casbin

2.13.1. Giới thiệu

Casbin là một framework authorization mã nguồn mở mạnh mẽ và linh hoạt, hiện thuộc Apache Software Foundation. Casbin hỗ trợ các mô hình kiểm soát truy cập như ACL, RBAC, ABAC, và các biến thể khác. Framework này cho phép định nghĩa các rule authorization một cách khai báo thông qua cấu hình, thay vì hardcode logic kiểm soát.

Casbin được thiết kế để hoạt động với nhiều ngôn ngữ lập trình, bao gồm Go, Java, Python, Node.js và hơn thế nữa, giúp đảm bảo tính nhất quán trong authorization logic trên toàn bộ hệ sinh thái.

So với các giải pháp authorization khác như OPA, SpiceDB (Google Zanzibar opensource), Casbin tập trung vào sự đơn giản và hiệu quả, cung cấp một cách tiếp cận.

2.13.2. Ưu điểm

Casbin mang lại nhiều lợi ích cho phát triển authorization:

• Cùng một biểu diễn hỗ trợ nhiều mô hình từ ACL đến ABAC
• Định nghĩa rules qua file cấu hình thay vì code
• Implementation cho nhiều ngôn ngữ
• Xử lý nhanh và kiểm tra permission hiệu quả
• Lưu trữ policies trong database hoặc file
• Custom matcher và effect cho phép mở rộng chức năng

2.13.3. Nhược điểm

Bên cạnh các ưu điểm, Casbin có một số hạn chế:

• Cần thời gian để hiểu RBAC, ABAC và cách cấu hình
• Use case phức tạp dẫn đến cấu hình khó hiểu
• Khó debug khi policy không hoạt động như mong đợi
• Không dễ scale so với các giải pháp chuyên biệt như OPA hoặc SpiceDB

Chương 3 trình bày quá trình phân tích và thiết kế hệ thống nhằm xác định rõ cấu trúc và cách thức hoạt động của hệ thống. Nội dung chương bao gồm khảo sát hiện trạng, xác định yêu cầu chức năng và phi chức năng, từ đó xây dựng kiến trúc hệ thống và mô tả các thành phần chính. Bên cạnh đó, chương sử dụng các sơ đồ UML để mô hình hóa hành vi, luồng xử lý và mối quan hệ giữa các đối tượng trong hệ thống, thiết kế dữ liệu thông qua các bảng cơ sở dữ liệu. Hệ thống cũng phân tích BlockNote schema tuỳ chỉnh, và mô hình thư viện Casbin của hệ thống.

3.1. Khảo sát hiện trạng

3.1.1. Các hệ thống hiện có

Hiện nay có nhiều hệ thống quản lý kiến thức cá nhân khác nhau, mỗi hệ thống đều có những ưu điểm và nhược điểm riêng. Dưới đây là một số hệ thống phổ biến mà nhóm đã khảo sát.

Notion

Notion là một nền tảng làm việc tích hợp được ra mắt vào năm 2013, kết hợp tài liệu, cơ sở dữ liệu, wiki và quản lý dự án trong một nền tảng duy nhất. Với hơn 30 triệu người dùng toàn cầu, Notion đã phát triển từ một ứng dụng ghi chú đơn giản thành một hệ thống kiến thức toàn diện.

Lịch sử phát triển của Notion bắt đầu với phiên bản 1.0 tập trung vào hợp tác tài liệu thời gian thực và tổ chức tài liệu phong cách wiki. Điểm đột phá lớn nhất đến với phiên bản 2.0 vào tháng 3 năm 2018 khi giới thiệu tính năng Database, nâng cấp Notion lên một tầm cao mới và cho phép tạo ra các công cụ ứng dụng. Hiện tại, Notion liên tục được cập nhật với các tính năng mới như AI agents, hệ thống tự động hóa hoàn chỉnh và nhiều loại giao diện cơ sở dữ liệu mới.

Các tính năng chính bao gồm editor module hóa với các khối có thể sắp xếp linh hoạt, cơ sở dữ liệu đa dạng (bảng, Kanban, lịch trình, gallery), khả năng hợp tác thời gian thực, và tích hợp AI. Giao diện của Notion được đánh giá cao về tính thẩm mỹ và sự linh hoạt, cho phép người dùng tùy chỉnh không gian làm việc theo nhu cầu riêng.

Tuy nhiên, Notion cũng có những hạn chế nhất định, điển hình như không hỗ trợ graph view một cách trực quan.

Obsidian

Obsidian là một ứng dụng ghi chú và quản lý kiến thức dựa trên tệp Markdown, được phát triển bởi Shida Li và Erica Xu và ra mắt vào năm 2020. Với triết lý “local-first”, Obsidian đảm bảo dữ liệu của người dùng luôn nằm trên thiết bị của họ, mang lại quyền sở hữu và tính linh hoạt tối đa.

Obsidian hoạt động với một “vault” chứa các tài liệu văn bản, mỗi ghi chú mới tạo ra một tệp Markdown riêng. Điểm mạnh nổi bật nhất của Obsidian là khả năng liên kết hai chiều và chế độ xem graph giúp người dùng hình dung mối quan hệ giữa các ghi chú. Người dùng có thể tạo liên kết nội dung bằng Wikilinks hoặc liên kết Markdown thông thường, và tất cả các liên kết này đều được hiển thị trong graph view tương tác.

Các tính năng chính bao gồm chế độ xem graph giúp phân tích mối quan hệ giữa các ghi chú, Canvas cho phép sắp xếp ghi chú trực quan không giới hạn, hệ thống plugin mở rộng do cộng đồng phát triển, và khả năng tích hợp với nhiều công cụ khác. Obsidian cũng hỗ trợ chế độ chỉnh sửa song song giữa Source Mode và Live Preview, cùng với đầy đủ các công cụ tìm kiếm và tổ chức. Obsidian còn chính hỗ trợ vim motion cho những người dùng yêu thích trải nghiệm chỉnh sửa văn bản nâng cao.

Mặc dù mạnh mẽ, Obsidian cũng có những thách thức. Learning curve khá cao, đặc biệt với người mới bắt đầu. Thiếu tính năng hợp tác thời gian thực là một hạn chế quan trọng. Giao diện mặc định có thể trông đơn giản so với các đối thủ cạnh tranh. Obsidian phù hợp nhất với các nhà nghiên cứu, nhà văn, lập trình viên và người làm việc kiến thức muốn kiểm soát sâu sắc ghi chú của mình.

jackyzha0/quartz

Quartz là một static-site generator nhanh, được thiết kế để biến nội dung Markdown thành các website hoàn toàn chức năng. Được phát triển bởi jackyzha0, Quartz hoạt động như một giải pháp self-hosted thay thế cho Obsidian Publish, cho phép người dùng xuất bản ghi chú và digital gardens của mình lên web một cách dễ dàng.

Quartz tương thích hoàn toàn với Obsidian, hỗ trợ đầy đủ các tính năng như wikilinks, backlinks, transclusions, graph view và full-text search. Nó được xây dựng trên công nghệ TypeScript và cung cấp khả năng tùy chỉnh cao thông qua JSX layouts và page components. Một trong những điểm mạnh của Quartz là tốc độ tải trang cực nhanh và kích thước bundle nhỏ.

Các tính năng chính bao gồm hỗ trợ LaTeX, Mermaid diagrams, dark mode, breadcrumbs, popover previews, internationalization, và hệ thống comments. Quartz cũng hỗ trợ Docker, RSS feeds, và có hệ thống plugin mở rộng. Nó đặc biệt phù hợp cho các cá nhân muốn chia sẻ kiến thức của mình dưới dạng website công khai hoặc digital garden.

Mặc dù mạnh mẽ, Quartz cũng có những hạn chế. Nó yêu cầu kiến thức kỹ thuật về Git và hosting để thiết lập. Không có tính năng hợp tác thời gian thực như Notion. Giao diện quản lý nội dung không trực quan bằng các ứng dụng desktop. Quartz phù hợp nhất với các nhà phát triển, sinh viên, và giáo viên muốn xuất bản ghi chú của mình dưới dạng website.

3.1.2. So sánh các hệ thống hiện có

Đặc tính	Notion	Obsidian	Quartz
Loại	Nền tảng làm việc	Ứng dụng ghi chú desktop	Static site generator
Nền tảng hỗ trợ	Web, Desktop, Mobile	Desktop, Mobile	CLI
Hợp tác thời gian thực	Có	Không	Không
Graph View	Không	Có	Có
Liên kết hai chiều	Có	Có	Có
Markdown gốc	Không (block-based)	Có	Có
Hệ thống Plugin	Có (kho mẫu, AI)	Có (cộng đồng)	Có
Lưu trữ	Đám mây	Local-first	Git-based
Self-hosted	Không	Không	Có
Mã nguồn mở	Không	Không	Có (MIT)
Xuất bản web	Có (Notion Sites)	Có (Obsidian Publish)	Có (tính năng chính)

Xuất phát từ đó, nhóm đã xác định được những điểm mạnh và hạn chế của từng hệ thống, từ đó rút ra những bài học quan trọng để áp dụng vào thiết kế hệ thống của mình. Nhưng cũng cần nhấn mạnh rằng Notopia không nhằm mục đích thay thế hoàn toàn các hệ thống hiện có, mà chỉ thực hiện một số chức năng nhất định, mang tính chất nghiên cứu, học tập, áp dụng công nghệ và quy trình phát triển phần mềm.

3.2. Kiến trúc hệ thống

Dự án được chia thành nhiều service khác nhau, bao gồm note service, document service, authorization service, search-worker worker, và các thành phần tái sử dụng từ các dịch vụ sẵn có. Mỗi service có trách nhiệm riêng biệt và giao tiếp với nhau thông qua API và message queue để đảm bảo tính modular và dễ bảo trì.

3.2.1. Sơ đồ kiến trúc tổng quan

Dưới đây là sơ đồ kiến trúc tổng quan của hệ thống.

Trong đó, các thành phần chính bao gồm:

Chi tiết về các thành phần chính:

Gateway

Gateway là điểm vào chính của hệ thống, chịu trách nhiệm định tuyến các yêu cầu từ người dùng đến các service phù hợp. Nó cũng thực hiện các chức năng như xác thực, và cân bằng tải để đảm bảo hiệu suất và bảo mật của hệ thống.

Hệ thống sử dụng Traefik làm API Gateway, với đặc điểm gọn nhẹ và dễ cấu hình, tương thích tốt với docker compose. Sử dụng agilezebra/jwt-middleware [13] để xử lý xác thực JWT, chuyển hoá OIDC claim thành header HTTP, giúp các service phía sau có thể dễ dàng xác định người dùng, không cần phải tích hợp trực tiếp với Identity Provider.

Web App

Web App là giao diện người dùng chính, cho phép người dùng tạo, chỉnh sửa và quản lý ghi chú. Ứng dụng được xây dựng với React và NextJS (Chương 2.3).

Note Service

Note Service (note service), viết bằng Go, chịu trách nhiệm quản lý metadata và logic liên quan đến không gian làm việc và ghi chú. Dịch vụ này cung cấp API để Web App có thể tương tác với không gian làm việc và ghi chú, đồng thời tích hợp với Authorization Service để kiểm tra quyền truy cập của người dùng trước khi thực hiện các hành động liên quan đến thư mục, ghi chú.

Document Service

Document Service (document service), viết bằng Typescript và NestJS framework, chịu trách nhiệm quản lý nội dung của các ghi chú, bao gồm lưu trữ và truy xuất dữ liệu. Nó cung cấp API để Web App có thể tương tác với nội dung ghi chú, tích hợp với Object Storage để lưu trữ các tệp liên quan, và sử dụng Hocuspocus (Chương 2.7) để hỗ trợ cộng tác thời gian thực trên nội dung ghi chú.

Authorization Service

Authorization Service (authorization service), viết bằng Go, sử dụng thư viên Casbin (Chương 2.13) để quản lý quyền truy cập của người dùng đối với không gian làm việc và ghi chú. Dịch vụ này cung cấp API để các service khác có thể kiểm tra quyền truy cập của người dùng trước khi thực hiện các hành động liên quan đến thư mục, ghi chú.

Identity Provider

Identity Provider chịu trách nhiệm xác thực người dùng và quản lý thông tin tài khoản. Hệ thống sử dụng Authentik là giải pháp xác thực, cung cấp các tính năng như đăng nhập một lần (SSO), quản lý người dùng, và hỗ trợ nhiều phương thức xác thực. Hệ thống sử dụng OpenID Connect (OIDC) để tích hợp giữa Gateway, Web App với Identity Provider, giúp đơn giản hóa quá trình xác thực và quản lý người dùng.

Object Storage

Object Storage được sử dụng để lưu trữ các tệp liên quan đến ghi chú, như hình ảnh và tài liệu. Hệ thống sử dụng RustFS, một giải pháp lưu trữ đối tượng nhẹ và hiệu quả, cung cấp API tương thích với S3 để dễ dàng tích hợp với các service khác.

Search Service

Search Service (Meilisearch), viết bằng Rust, cung cấp khả năng tìm kiếm nội dung trong ghi chú. Trong đó, search-worker worker chịu trách nhiệm đồng bộ dữ liệu đến Search Service để đảm bảo dữ liệu tìm kiếm luôn được cập nhật.

Event Bus

Event Bus là hệ thống message queue được sử dụng để giao tiếp giữa các service, đảm bảo tính modular và giảm sự phụ thuộc trực tiếp giữa các service. Hệ thống sử dụng Redpanda, một giải pháp message queue hiệu suất cao, tương thích với Kafka API, giúp dễ dàng tích hợp với các service khác.

Monitoring

Monitoring là thành phần quan trọng để giám sát hiệu suất và trạng thái của hệ thống. Hệ thống sử dụng Grafana Stack và Prometheus để thu thập và hiển thị các chỉ số về hiệu suất.

3.2.2. Kiến trúc note service

Là thành phần trung tâm trong hệ thống, note service chịu trách nhiệm quản lý metadata và logic liên quan đến ghi chú. Dịch vụ này được thiết kế theo kiến trúc Clean Architecture, Domain Driven Design, và Event-Driven Architecture để đảm bảo tính modular, dễ bảo trì, và khả năng mở rộng trong tương lai⁴. Dưới đây là sơ đồ kiến trúc chi tiết của note service.

3.2.3. Kiến trúc document service

document service áp dụng kiến trúc theo NestJS, với các module được tổ chức theo chức năng. Dưới đây là sơ đồ kiến trúc chi tiết của document service, mô tả đến cấp độ module.

3.2.4. Kiến trúc authorization service

authorization service được thiết kế theo kiến trúc Layered Architecture, với tầng logic không phân tách rõ vì tính đặc thù của thư viện Casbin. Dưới đây là sơ đồ kiến trúc của authorization service.

3.2.5. Kiến trúc search-worker worker

search-worker worker được thiết kế theo kiến trúc đơn giản, sử dụng trên 1 module chính của NestJS, không chia thành nhiều module nhỏ. Dưới đây là sơ đồ kiến trúc của search-worker worker.

3.3. Mô tả các Use Case

Nhóm chỉ xác định một vài use case phức tạp, có nhiều luồng, tác động đến nhiều dịch vụ.

3.3.1. Mô tả use case Create Note

3.3.2. Mô tả use case Get Note

3.3.3. Mô tả use case Commit Document

3.4. Sơ đồ lớp (Class Diagram)

Dưới đây là sơ đồ lớp cho các service trong hệ thống, bao gồm note service và document service, không bao gồm authorization service vì tính đặc thù của service không thể biểu diễn một cách dễ dàng, và search-worker vì xử lý dữ liệu không phức tạp. Sơ đồ lớp giúp minh họa cấu trúc của các lớp, các thuộc tính và phương thức của chúng, cũng như mối quan hệ giữa các lớp.

3.4.1. Sơ đồ lớp cho note service

Sơ đồ lớp cho note service được chia thành hai phần: tầng application và tầng domain. Tầng application tập trung vào các lớp mô hình dữ liệu và interface của service, trong khi tầng domain tập trung vào các lớp đại diện cho các aggregate và logic nghiệp vụ.

Sơ đồ lớp tầng application

Tầng application bao gồm các lớp mô hình dữ liệu (model) cho việc read (theo CQRS) và các interface của service. Các lớp mô hình dữ liệu đại diện cho các thực thể trong hệ thống như Note, Folder, Workspace, v.v. Các interface của service định nghĩa các phương thức mà tầng infrastructure sẽ triển khai.

Sơ đồ lớp tầng domain

Tầng domain, áp dụng Domain Driven Design Pattern, bao gồm các lớp đại diện cho các aggregate như Note, Folder, Workspace, v.v. Các lớp này chứa các thuộc tính và phương thức liên quan đến logic nghiệp vụ của chúng. Ngoài ra, tầng domain cũng bao gồm các interface của repository để truy cập dữ liệu. Tuy nhiên, tầng domain không được trực tiếp gọi service được định nghĩa hay repository interface được khai báo.

3.4.2. Sơ đồ lớp cho document service

Sơ đồ tinh gọn cho document service, bao gồm các thực thể, services, và đối tượng liên quan. Ở thiết kế này không bao gồm repository vì đã được TypeORM abstract đi, tức, service sẽ trực tiếp gọi các phương thức của TypeORM để truy cập dữ liệu.

3.5. Thiết kế cơ sở dữ liệu

Các service trong hệ thống sẽ sử dụng cơ sở dữ liệu PostgreSQL để lưu trữ và quản lý dữ liệu. Dưới đây là thiết kế cơ sở dữ liệu cho các service, bao gồm các bảng chính và mối quan hệ giữa chúng.

3.5.1. Cơ sở dữ liệu cho note service

Bảng workspaces

Bảng folders

Bảng notes

Bảng note_links

3.5.2. Cơ sở dữ liệu cho document service

Bảng documents

Bảng Revisions

3.5.3. Cơ sở dữ liệu cho authorization service

Vì tính đặc thù của thư viện Casbin, bảng dữ liệu của service này không thuộc phạm vi quản lý của hệ thống, mà sẽ được Casbin tự động tạo ra và quản lý.

Bảng casbin_rules

3.6. Mô hình BlockNote tuỳ chỉnh trong hệ thống

BlockNote bao gồm nhiều schema nhiều schema, có thể xem tại Chương 2.11. Tuy nhiên, để có thể liên kết các ghi chú với nhau, cũng như hỗ trợ liên kết thông qua tag, hệ thống cần tuỳ chỉnh thêm hai config schema cho BlockNote, là reference và tag. Tham khảo từ tài liệu schema tuỳ chỉnh của BlockNote [16], hai config này sẽ được định nghĩa như sau.

3.6.1. Mô hình BlockNote Reference tuỳ chỉnh

Một khối reference sẽ chứa một thuộc tính noteId để xác định ghi chú mà nó đang tham chiếu đến. Khi người dùng chèn một khối reference vào ghi chú, họ sẽ có thể chọn một ghi chú khác trong hệ thống để liên kết đến. Điều này cho phép tạo ra các mối quan hệ giữa các ghi chú.

3.6.2. Mô hình BlockNote Tag tuỳ chỉnh

Khối tag sẽ chứa một thuộc tính tag để lưu trữ tên của tag. Người dùng có thể chèn một khối tag vào ghi chú và gán cho nó một tên tag cụ thể.

3.7. Mô hình Casbin trong hệ thống

Casbin hỗ trợ biểu diễn nhiều mô hình kiểm soát truy cập khác nhau, chi tiết xem tại Chương 2.13. Trong đó, hệ thống tập trung sử dụng mô hình RBAC để quản lý quyền truy cập dựa trên vai trò (role) của người dùng, trong mỗi không gian làm việc. Đối với Casbin, workspace được xem như một domain.

3.7.1. Mô hình Casbin trong hệ thống

Trong đó, các phần được định nghĩa như sau:

• request_definition định nghĩa cấu trúc của một yêu cầu truy cập, bao gồm người dùng (sub), không gian làm việc (dom), đối tượng (obj) và hành động (act)
• policy_definition định nghĩa cấu trúc của một chính sách, bao gồm vai trò (sub), đối tượng (obj) và hành động (act)
• role_definition định nghĩa cách thức xác định vai trò của người dùng trong một không gian làm việc (g) và cách thức xác định mối quan hệ giữa đối tượng và chính sách (g2)
• policy_effect định nghĩa hiệu ứng của chính sách, trong trường hợp này là cho phép truy cập nếu có ít nhất một chính sách cho phép
• matchers định nghĩa cách thức so khớp giữa yêu cầu truy cập và chính sách, trong đó yêu cầu truy cập sẽ được phép nếu người dùng có vai trò phù hợp trong không gian làm việc, đối tượng phù hợp với chính sách và hành động phù hợp với chính sách

3.7.2. Chính sách Casbin trong hệ thống

Trong đó, các chính sách được định nghĩa như sau:

• Vai trò owner có quyền đọc, chỉnh sửa và xóa trên không gian làm việc và các mục trong không gian làm việc
• Vai trò editor có quyền đọc trên không gian làm việc và quyền đọc, chỉnh sửa và xóa trên các mục trong không gian làm việc
• Vai trò viewer chỉ có quyền đọc trên không gian làm việc và các mục trong không gian làm việc
• Các đối tượng note và folder được xác định là các mục trong không gian làm việc thông qua mối quan hệ g2

Ví dụ minh hoạ cụ thể về yêu cầu truy cập và quá trình so khớp chính sách có thể xem tại Phụ lục B.1.

3.8. Thiết kế health check ở các service

3.8.1. Mục tiêu của health check endpoint

Health check endpoint là cơ chế tự kiểm tra giúp hệ thống giám sát phát hiện sớm sự cố (lỗi kết nối DB, rò rỉ bộ nhớ, thành phần phụ thuộc sập). Từ đó, Kubernetes có thể tự động khởi động lại container hoặc ngừng gửi traffic đến service lỗi.

Có 3 loại probe theo Kubernetes:

• Startup probe: kiểm tra service đã khởi động xong chưa, thất bại → restart
• Liveness probe: kiểm tra service còn sống không, thất bại → restart
• Readiness probe: kiểm tra service sẵn sàng nhận traffic chưa, thất bại → ngừng gửi traffic

Bảng dưới đây tóm tắt trạng thái triển khai health check. Do thời gian có hạn, nhóm chỉ triển khai đầy đủ cho các Go service; các service còn lại sẽ bổ sung sau.

Ví dụ chi tiết payload response của từng loại probe trên note service có thể xem tại Phụ lục C.1.

3.8.2. Health check ở các Go service

Sử dụng thư viện github.com/alexliesenfeld/health [17]. Thư viện hỗ trợ kiểm tra đồng bộ và bất đồng bộ (chạy tác vụ nặng trong nền theo chu kỳ, trả về kết quả từ cache), cấu hình TTL cho cache để giảm tải hạ tầng, và bọc tích hợp với các thư viện health check phổ biến khác (health-go, etherlabsio/healthcheck, heptiolabs/healthcheck, InVisionApp/go-health).

3.9. Hạn chế CI của Nx và giải pháp custom cache

Nx hướng developer dùng Nx Cloud cho CI, nhưng nhóm đã tự xây dựng giải pháp cache riêng cho GitHub Actions: KevinNitroG/nx-cache-action [18]. Script lấy cảm hứng từ raegen/nx [19] (đã deprecated), nhưng cơ chế khác biệt: khởi động NodeJS ExpressJS server implement OpenAPI Spec của Nx [20], forward lệnh Nx cho child process, server nhận request cache và giao tiếp với GitHub Actions cache API qua actions/toolkit/cache [21].

Vấn đề: Nx lưu cache task khoảng một tháng kể từ lần cuối sử dụng. Không dùng nx-cache-action, cache được lưu toàn bộ project task cache ( 5GB/lần). 10 commit thay đổi source code tạo 10 cache ( 50GB), vượt giới hạn 10GB của GitHub Actions. Chưa kể còn phải cache node modules, Go packages, system dependencies.

Với nx-cache-action, cache lưu theo từng project nhỏ (vài trăm KB đến hơn 10MB/task), chỉ tạo cache mới khi project đó thay đổi. Điều này tối ưu dung lượng, tránh vượt giới hạn GitHub Actions, tăng cache hit.

Nhược điểm: cache phải download qua actions/toolkit/cache rồi pipe vào lại Nx process qua HTTP, thay vì giao tiếp trực tiếp với GitHub Actions cache Rest API. Đây là cách dễ dàng nhất để triển khai.

Chương trình bày kết quả xây dựng Web App, bao gồm giao diện, các thành phần giao diện, và mô tả chức năng của từng thành phần.

4.1. Landing page

4.2. Màn hình đăng nhập

4.3. Màn hình chọn không gian làm việc

4.4. Màn hình tổng quan không gian làm việc

4.5. Màn hình soạn thảo ghi chú

4.6. Màn hình đồ thị không gian làm việc

4.7. Màn hình đồ thị ghi chú

4.8. Màn hình cài đặt không gian làm việc

4.9. Màn hình thùng rác

4.10. Màn hình lỗi / 404

Chương này trình bày phần kết luận của đồ án, nhằm tổng hợp và đánh giá các kết quả đạt được trong quá trình nghiên cứu, phân tích, thiết kế và xây dựng hệ thống. Nội dung chương tập trung vào việc đánh giá sản phẩm đã triển khai, nhận xét những thuận lợi, khó khăn, ưu điểm và hạn chế của hệ thống, đồng thời đề xuất các hướng phát triển trong tương lai nhằm nâng cao tính hoàn thiện và khả năng ứng dụng thực tế.

5.1. Kết quả đạt được

5.1.1. Về sản phẩm

Nhóm đã hoàn thiện hệ thống ghi chú với các tính năng:

• Ứng dụng Web cho người dùng cuối, quản lý và tổ chức ghi chú.
• Hỗ trợ cộng tác thời gian thực với phân quyền.
• Tích hợp tìm kiếm ghi chú.
• Backend API microservices, hiệu suất cao.
• Source code tại https://github.com/notopia-uit/notopia.
• Document website tại https://notopia-uit.github.io/notopia.

5.1.2. Về công nghệ

Dự án áp dụng các công nghệ hiện đại:

• BlockNote (block-based editor), Yjs (CRDT), Hocuspocus (cộng tác) (Chương 2.11, Chương 3.6, Chương 2.7).
• React, NextJS, TypeScript, TailwindCSS, Shadcnui cho frontend.
• Go (Chương 2.1) và NestJS (Chương 2.4) cho backend.
• Phân quyền với Casbin (Chương 2.13, Chương 3.7).
• Xác thực OAuth2/OIDC với Authentik.
• gRPC cho inter-service communication.
• Traefik cho API gateway, Docker containerization, CI/CD với GitHub Actions.
• Meilisearch cho tìm kiếm.
• Database: SQL thuần và ORM.
• Monorepo với Nx, cache từng project – dependency graph tại Phụ lục D.
• Contract First: OpenAPI spec, mock API, phát triển song song frontend/backend.
• SQLC Dynamic Filter: Plugin vtuanjs/sqlc-gen-go [22] cho dynamic WHERE conditions.
• Observability: Grafana, Prometheus, Loki, Tempo, Alloy – xem tại Phụ lục E.

5.2. Nhận xét

5.2.1. Thuận lợi

• Được giảng viên hướng dẫn tận tình, giúp định hướng rõ ràng, tránh dùng công nghệ không cần thiết (như Neo4j, thay bằng SQL Recursive CTE).
• BlockNote giúp xây dựng editor nhanh, tập trung phát triển tính năng đặc thù.
• Các công nghệ hiện đại (React, NextJS, NestJS, Go, gRPC, Traefik, Casbin, Authentik, Meilisearch) tăng tốc phát triển và đảm bảo hiệu suất.
• Cộng tác nhóm hiệu quả nhờ Contract First (OpenAPI, Protobuf), giảm xung đột code.

5.2.2. Khó khăn

• Dữ liệu mẫu từ Obsidian Vault (TrshPuppy/obsidian-notes [23]) không chuẩn xác do parse bằng text, code block chứa #/#! bị parse thành tag. Hệ thống không support nested tags như Obsidian.
• Việc học nhiều công nghệ mới cùng lúc tạo learning curve dốc, dù đã có kinh nghiệm với OAuth2/OIDC, SQLC.
• Kiến trúc microservices đòi hỏi quản lý nhiều service, đảm bảo communication, xử lý distributed systems issues (latency, fault tolerance).
• Casbin có learning curve cao, cần hiểu rõ RBAC để thiết kế policy phù hợp.
• Các khái niệm event bus, command bus từ Watermill và Event-Driven Architecture nói chung đòi hỏi hiểu rõ để triển khai đúng.
• Thiết lập monorepo TypeScript/JavaScript phức tạp, tốn thời gian cấu hình.
• RustFS chưa stable, gặp vấn đề rustfs/rustfs/issues/2587 [24] do thành viên nhóm phát hiện.

5.2.3. Ưu điểm

• Trải nghiệm người dùng trực quan, giao diện hiện đại, thống nhất.
• Xử lý graph nhanh nhờ Go, hạn chế con trỏ và đối tượng heap khi Read.
• Kiến trúc microservices dễ mở rộng, maintainability cao nhờ Clean Architecture, DDD, CQRS cho service note.
• DevOps tốt với CI/CD nhanh nhờ Nx: 30 giây (cache hit), 10 phút (ignore cache).
• Các service Go (note, authorization) có health check endpoint đầy đủ.

5.2.4. Nhược điểm

• Microservices architecture có độ phức tạp cao.
• Tốn tài nguyên infrastructure: tổng RAM  2.5GB khi chạy toàn bộ, riêng Authentik  1.5GB (chấp nhận đánh đổi lấy enterprise ready, feature rich).
• Các service JS chưa cấu hình được telemetry và health check endpoint.
• Xử lý lỗi async event còn hạn chế: chưa có retry và dead letter queue cho tất cả service (hiện chỉ có service note).

5.3. Hướng phát triển

• Tính năng subscription: thương mại hóa sản phẩm dưới dạng SaaS.
• Tích hợp AI: @blocknote/xl-ai [25], hybrid search với Meilisearch [26], tool thông qua API hệ thống.
• Deploy: thiết lập quy trình release container, sẵn sàng triển khai.
• Sử dụng Istio Gateway thay Traefik trên môi trường deploy (service mesh, auth, retry tại gateway) phù hợp Kubernetes.

5.4. Lời kết

Dự án đã đạt được mục tiêu đề ra và mang lại nhiều bài học quý giá cho nhóm phát triển. Hệ thống “Notopia - Ứng dụng ghi chú thông minh hỗ trợ quản lý tri thức bằng biểu đồ quan hệ” không chỉ là sản phẩm hoàn chỉnh mà còn là nền tảng để tiếp tục nghiên cứu và phát triển trong tương lai.

Phụ lục A. BLOCKNOTE

A.1 BlockNote Model

Dưới đây là ví dụ về cấu trúc dữ liệu của một block trong BlockNote:

Phụ lục B. CASBIN

B.1 Ví dụ minh hoạ quy tắc Casbin trong hệ thống

Giả sử ta có ba người dùng: 110, 111 và 112, với các vai trò và quyền truy cập như sau:

Trong đó:

• Người dùng 111 là chủ sở hữu (owner) của không gian làm việc 111
• Người dùng 112 là biên tập viên (editor) của không gian làm việc 111 và chủ sở hữu của không gian làm việc 112
• Người dùng 110 là người xem (viewer) của không gian làm việc 111 và chủ sở hữu của không gian làm việc 110

B.1.1 Giải thích cho yêu cầu truy cập đầu tiên

Người dùng 111 yêu cầu đọc không gian làm việc 111. Kết quả là true vì người dùng 111 có vai trò owner trong không gian làm việc 111 và có chính sách cho phép đọc không gian làm việc. Các bước suy luận dựa trên matcher m:

1. Người dùng 111 có vai trò owner trong không gian làm việc 111 thông qua chính sách g. Ta có thể xác định rằng g(user:111, owner, workspace:111) là true.
2. Đối tượng workspace cũng chứa trong workspace

   (

   )

   thông qua chính sách g2. Ta có thể xác định rằng g2(workspace, workspace) là true.
3. Hành động read phù hợp với chính sách read của vai trò owner trên không gian làm việc. Ta có thể xác định rằng read == read là true.

B.1.2 Giải thích cho yêu cầu truy cập thứ ba

Người dùng 112 yêu cầu xóa không gian làm việc 111. Kết quả là false vì người dùng 112 chỉ có vai trò editor trong không gian làm việc 111 và không có chính sách nào cho phép editor xóa không gian làm việc. Các bước suy luận:

1. Người dùng 112 có vai trò editor trong không gian làm việc 111 thông qua chính sách g. Ta có thể xác định rằng g(user:112, editor, workspace:111) là true.
2. Đối tượng workspace cũng chứa trong workspace

   (

   )

   thông qua chính sách g2. Ta có thể xác định rằng g2(workspace, workspace) là true.
3. Hành động delete không phù hợp với chính sách delete của vai trò editor trên không gian làm việc. Ta có thể xác định rằng delete == delete là true, nhưng vì không có chính sách nào cho phép editor xóa không gian làm việc, nên yêu cầu truy cập này bị từ chối.

Tương tự, các yêu cầu truy cập khác cũng được đánh giá dựa trên vai trò của người dùng trong không gian làm việc và các chính sách đã định nghĩa. Kết quả của mỗi yêu cầu sẽ cho biết liệu yêu cầu đó có được phép hay không, cùng với lý do dựa trên chính sách nào đã cho phép hoặc từ chối yêu cầu đó. Chi tiết có thể xem tại website playground của Casbin cho ví dụ trên tại https://editor.casbin.org/#E7VKBXR2T.

Phụ lục C. HEALTH CHECK

C.1 Ví dụ payload health check của note service

C.1.1 Startup

C.1.2 Liveness

C.1.3 Readiness

Phụ lục D. NX

Hình D.1 dưới đây thể hiện dependency graph của monorepo được sinh bởi Nx.

Phụ lục E. OBSERVABILITY

E.1 Log xem từ Grafana

Hình E.1 dưới đây thể hiện log từ hệ thống được xem qua Grafana.