[Open Source] #189 - React Knowledge Graph (RKG): Hệ thống phân tích tri thức React với kiến trúc Neo4j, Local Embeddings và giao thức MCP cho AI Agents

Trong các dự án React quy mô lớn (Enterprise), việc nắm bắt cây phụ thuộc, hiểu rõ phạm vi ảnh hưởng của một thay đổi (Blast Radius) hay tìm kiếm các linh kiện (components) tương đồng là một thách thức cực lớn. RKG ra đời như một "bản đồ tri thức" sống động, kết hợp sức mạnh của cơ sở dữ liệu đồ thị (Graph Database) và trí tuệ nhân tạo (AI) để biến mã nguồn tĩnh thành một hệ sinh thái dữ liệu có thể truy vấn và suy luận.

Dưới góc độ kỹ thuật, RKG là một minh chứng xuất sắc về việc ứng dụng Static Analysis chuyên sâu, kỹ thuật Vector Search tại chỗ và giao thức MCP (Model Context Protocol) để "mở khóa" mã nguồn cho các mô hình ngôn ngữ lớn (LLM).

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

🛠️ 1. Nền tảng công nghệ: Phân tích AST và Graph Database

RKG không sử dụng Regex thô sơ để đọc code; nó thâm nhập vào cấu trúc sâu nhất của TypeScript:

• Deep Static Analysis (ts-morph): Sử dụng trình bao quanh TypeScript Compiler API để duyệt cây AST (Abstract Syntax Tree). Kỹ thuật này cho phép RKG hiểu chính xác các quan hệ Export/Import, bóc tách chi tiết từng Prop, Hook và định nghĩa Component với độ chính xác tuyệt đối.
• Graph Engine (Neo4j 5): Toàn bộ tri thức được lưu trữ trong Neo4j. Khác với SQL, Neo4j cho phép thực hiện các truy vấn đệ quy đa tầng để tìm kiếm các quan hệ phụ thuộc bắc cầu (Transitive dependencies) chỉ trong vài mili giây.
• Local AI Infrastructure: Tích hợp @xenova/transformers để chạy mô hình all-MiniLM-L6-v2 ngay tại máy khách. Điều này cho phép tạo ra các Vector Embedding 384 chiều cho từng linh kiện mà không cần gửi mã nguồn lên Cloud, đảm bảo an toàn thông tin tuyệt đối.
• AI Protocol (MCP): Hỗ trợ tiêu chuẩn Model Context Protocol của Anthropic, cho phép các AI trợ lý (như Claude, Cursor) trực tiếp gọi các công cụ của RKG để "thám hiểm" mã nguồn thông qua ngôn ngữ tự nhiên.

🏗️ 2. Trụ cột kiến trúc: Tri thức hóa mã nguồn (Source-to-Graph)

Kiến trúc của RKG được thiết kế theo mô hình đường ống (Pipeline) tinh vi:

• Atomic Design Classification: Hệ thống tự động phân loại các linh kiện vào các tầng: atom, molecule, organism, template, page. Việc phân loại dựa trên logic thư mục và đặc biệt là chỉ số Fan-out (số lượng linh kiện phụ thuộc phía dưới), giúp lập trình viên nhìn thấy rõ cấu trúc tầng bậc của dự án.
• Granular Node Schema: Trong đồ thị của RKG, Hook và Prop không phải là thuộc tính văn bản, mà là các Node độc lập. Điều này mở ra khả năng truy vấn cực kỳ mạnh mẽ: "Những linh kiện nào sử dụng chung Hook useAuth và có Prop tên là isAdmin?".
• Semantic Intelligence Layer: Bằng cách kết hợp Graph và Vector, RKG hỗ trợ Hybrid Search. Bạn có thể tìm một linh kiện bằng cách mô tả tính năng (vd: "linh kiện xử lý thanh toán có nút xác nhận") thay vì phải nhớ tên file chính xác.

🔄 3. Workflow: Từ Mã nguồn đến Trợ lý AI (Sequence Diagram)

Sơ đồ mô tả quy trình RKG "tiêu hóa" dự án và cung cấp tri thức cho AI Agent:

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

1. Blast Radius Analysis: Sử dụng thuật toán duyệt đồ thị đệ quy để tính toán bán kính ảnh hưởng. Đây là tính năng sống còn cho các tác vụ Refactoring, giúp lập trình viên tự tin thay đổi code lõi mà không sợ làm sập các trang ở tầng cao.
2. Duplicate Logic Detection: Thông qua so sánh độ tương đồng Vector giữa các linh kiện, RKG có thể cảnh báo lập trình viên khi họ chuẩn bị viết một linh kiện mới có chức năng gần như trùng lặp với linh kiện đã có trong dự án.
3. Cypher Tool for AI: Cung cấp công cụ execute_cypher (chế độ Read-only) cho AI. Điều này cho phép AI tự động viết các câu lệnh truy vấn đồ thị phức tạp để tự trả lời các câu hỏi về kiến trúc mà tác giả công cụ chưa định nghĩa sẵn.
4. Next.js App Router Awareness: RKG có bộ máy heuristics riêng để nhận diện các đặc tính của Next.js hiện đại, phân biệt rõ ràng giữa layout, page, và loading states, giúp bản đồ tri thức phản ánh đúng luồng vận hành của ứng dụng.

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

✅ Kết luận: Tại sao RKG là tương lai của Software Engineering?

RKG chứng minh rằng việc bảo trì mã nguồn không chỉ là đọc text, mà là quản trị tri thức. Bằng cách kết hợp cấu trúc chặt chẽ của Graph Database và tính linh hoạt của AI, dự án đã tạo ra một hạ tầng giúp lập trình viên "nói chuyện" trực tiếp với kiến trúc ứng dụng của mình.

Đối với các Architect và Senior Developer, nghiên cứu RKG mang lại giá trị về:

• Kỹ thuật xây dựng Knowledge Graph từ mã nguồn.
• Cách triển khai Local AI pipeline (WASM-based) hiệu quả.
• Tư duy thiết kế công cụ hỗ trợ AI-driven Development.