[Open Source] #129 - EventCatalog: Hệ thống quản trị tri thức kiến trúc Microservices với Astro 5, React Islands và tư duy Documentation-as-Code
Trong các hệ thống Microservices quy mô lớn, việc theo dõi xem dịch vụ nào phát (produce) sự kiện nào và dịch vụ nào đang tiêu thụ (consume) chúng là một "cơn ác mộng" về quản trị. Các tài liệu thường bị lỗi thời ngay khi vừa viết xong. EventCatalog ra đời để giải quyết bài toán này bằng cách biến tài liệu kiến trúc thành mã nguồn (Documentation-as-Code), tự động hóa việc vẽ sơ đồ luồng dữ liệu và tạo ra một "Single Source of Truth" cho toàn bộ hệ sinh thái hướng sự kiện (EDA) của doanh nghiệp.
Dưới góc độ kỹ thuật, EventCatalog là một minh chứng xuất sắc cho việc ứng dụng kiến trúc Island Architecture của Astro 5 để xây dựng một nền tảng quản trị tri thức (Knowledge Base) siêu nhanh và có khả năng mở rộng cao.
Github: https://github.com/eventcatalog/eventcatalog
🛠️ 1. Nền tảng công nghệ: Astro Islands và Trải nghiệm Content-centric
EventCatalog sử dụng một ngăn xếp công nghệ được tối ưu hóa cho việc xử lý hàng nghìn tài liệu mà vẫn đảm bảo tốc độ phản hồi tức thì:
- Core Framework (Astro 5.x): Tận dụng tối đa sức mạnh của Astro trong việc xử lý web tĩnh (Static Site Generation). Astro giúp giảm thiểu JavaScript gửi xuống trình duyệt, chỉ tải những gì thực sự cần thiết.
- React Islands: Các thành phần phức tạp như sơ đồ tương tác (Node Graph), trình xem Schema hay Chatbot AI được triển khai dưới dạng các "hòn đảo" React. Điều này giúp giữ cho trang web nhẹ nhàng nhưng vẫn có khả năng tương tác cao tại các vị trí cần thiết.
- Content Collections & Zod: Sử dụng hệ thống quản lý nội dung mạnh mẽ của Astro kết hợp với Zod để định nghĩa và kiểm chứng (validate) chặt chẽ dữ liệu từ các file Markdown/MDX. Điều này đảm bảo mọi sự kiện hay dịch vụ đều phải tuân thủ đúng cấu trúc trước khi được xuất bản.
- Nanostores: Thư viện quản lý trạng thái siêu nhẹ giúp đồng bộ dữ liệu giữa các "đảo" React mà không gây ra hiện tượng phình to kích thước bundle.
🏗️ 2. Trụ cột kiến trúc: Documentation-as-Code và Domain-Driven Design
Kiến trúc của EventCatalog không chỉ là một trang web, mà là một công cụ quản trị (Governance Tool):
- Documentation-as-Code: Toàn bộ thực thể (Events, Services, Domains) đều được lưu trữ dưới dạng file Markdown/MDX ngay trong repo mã nguồn. Kỹ thuật này giúp tài liệu được phiên bản hóa (versioning), kiểm duyệt (code review) và triển khai (CI/CD) song hành cùng với code thực tế.
- EDA Discovery Architecture: Hệ thống tập trung vào việc làm rõ mối quan hệ giữa Producers và Consumers. Bằng cách phân tích các tham chiếu chéo (cross-references), EventCatalog tự động xây dựng bản đồ phụ thuộc (Dependency Map) của toàn hệ thống.
- Domain-Driven Governance: Hỗ trợ phân cấp theo Domains và Subdomains. Kiến trúc này giúp các tổ chức lớn có thể chia nhỏ quyền quản lý tài liệu theo các đội nhóm nghiệp vụ (Bounded Contexts), phản ánh đúng cấu trúc của tổ chức.
🔄 3. Workflow: Từ Markdown đến Bản đồ Kiến trúc Động (Sequence Diagram)
Sơ đồ mô tả quy trình chuyển đổi dữ liệu thô thành tri thức kiến trúc:
⚡ 4. Các kỹ thuật "Pro-level" trong mã nguồn
- AI Architecture Understanding (MCP Server): EventCatalog tích hợp giao thức Model Context Protocol (MCP). Điều này cho phép các AI như Claude có thể truy cập trực tiếp vào "bộ não" kiến trúc của bạn để trả lời các câu hỏi như: "Dịch vụ thanh toán sẽ bị ảnh hưởng thế nào nếu tôi đổi schema của sự kiện UserRegistered?".
- Automatic Graph Layout (Elkjs/Dagre): Thay vì bắt người dùng vẽ tay, EventCatalog sử dụng các thuật toán bố trí đồ thị thông minh để tự động sắp xếp hàng trăm dịch vụ và sự kiện thành một bản đồ dễ đọc, tối ưu hóa các đường nối để tránh chồng chéo.
- Schema Versioning & Diffing: Hỗ trợ quản lý nhiều phiên bản của Schema (v1, v2) và cung cấp giao diện so sánh trực quan, giúp các đội nhóm nhận diện được các thay đổi gây phá vỡ (breaking changes) trước khi triển khai.
- Extensible Generator System: Cung cấp các plugin để tự động quét (scan) và tạo tài liệu từ các file OpenAPI, AsyncAPI hay thậm chí là từ code thực tế, giúp giảm thiểu tối đa việc nhập liệu thủ công.
⚖️ 5. So sánh chiến lược
| Tiêu chí | EventCatalog | Backstage (Spotify) | Confluence / Wiki |
|---|---|---|---|
| Mục tiêu chính | Kiến trúc EDA / Microservices | Platform Portal tổng thể | Tài liệu chung |
| Kiến trúc | SSG (Siêu nhanh, Island) | App (Nặng hơn) | CMS truyền thống |
| Tư duy dữ liệu | MDX / Code-centric | YAML / Plugin-centric | Văn bản thô |
| Vẽ sơ đồ | Tự động hoàn toàn | Phụ thuộc Plugin | Thủ công |
| Hỗ trợ AI | Rất cao (MCP Server) | Trung bình | Thấp |
✅ Kết luận: Tại sao EventCatalog là hình mẫu cho quản trị kiến trúc hiện đại?
EventCatalog chứng minh rằng tài liệu kiến trúc không nhất thiết phải là những trang văn bản khô khan và lỗi thời. Bằng cách kết hợp giữa tư duy Documentation-as-Code và công nghệ Astro Islands, dự án đã tạo ra một nền tảng mà ở đó kiến trúc hệ thống trở nên hữu hình, có thể tìm kiếm và có thể "nói chuyện" được với AI.
Đối với các kỹ sư Backend và Architect, nghiên cứu EventCatalog giúp bạn hiểu sâu về:
- Cách vận hành Astro Content Collections ở quy mô lớn.
- Kỹ thuật xây dựng Sơ đồ tương tác động từ dữ liệu Markdown.
- Tư duy quản trị Kiến trúc hướng sự kiện (EDA) một cách khoa học.
All rights reserved
