BeGuru AI — Technical Docs: Design system & artifact trên đĩa

Tóm lược

• Dưới mỗi project FE sinh ra, thư mục design-system/ là nơi ghi SSOT cho token/thiết kế (MASTER.md), tiến độ (BUILD_STATE.md), phạm vi sản phẩm (PRODUCT_PLAN.md) và snapshot context (beguru_chat_context.json).
• ## BEGURU_FE_SPEC trong chat được Engineer dùng để đồng bộ với các file trên; thứ tự rails ghim cho PM (sau nén) gồm FE spec → BUILD_STATE → MASTER → … — chi tiết trong beguru-ai/docs/MEMORY_AND_CONTEXT_LAYERS.md.
• Quy ước output_path: segment đầu frontend_<slug> (React/Next) và backend_<slug> (Go) dưới projects_root_dir; không tự do đặt tên lệch quy ước nếu dùng pipeline chuẩn — xem API_SPEC.md.

Mục đích và phạm vi

Bài mô tả artifact trên đĩa mà Engineer đọc/ghi và cách chúng liên kết với handoff PM, không mô tả toàn bộ API (xem API_SPEC.md).

Vị trí file trong cây project

File / thư mục	Vai trò
design-system/MASTER.md	Token màu, typography, policy merge (merge / if_missing / always) — nguồn thiết kế rút gọn cho prompt Engineer
design-system/BUILD_STATE.md	Đã ship, checklist, focus/blockers; excerpt inject vào generate-code khi file tồn tại
design-system/PRODUCT_PLAN.md	Scope, user story, sơ đồ Mermaid do Engineer tạo/cập nhật
design-system/beguru_chat_context.json	user_info, kyb_data, project_context, software_type, … — merge từ init-project / chat
.guru/rules/*.md	Rule Next.js (template repo): auth mock, App Router, v.v. — load qua bundle engineer

Luồng từ spec trong chat xuống đĩa

beguru_chat_context.json được cập nhật qua init-project / merge từ chat; không vẽ vào sơ đồ trên để tránh nhầm với luồng generate-code.

MASTER.md

Chứa guideline thiết kế (ví dụ bảng token OKLCH). Engineer áp dụng theo policy đã định nghĩa trong pipeline (merge khi cập nhật, tránh drift giữa các lượt generate).

BUILD_STATE.md

• Ghi nhận mức độ hoàn thành theo user story / checklist.
• Khi file đã có, POST /api/freetext/generate-code inject excerpt CURRENT BUILD_STATE; Engineer trả block cập nhật full-file theo thứ tự quy định trong tài liệu API (code → PRODUCT_PLAN nếu có → BUILD_STATE cuối).

PRODUCT_PLAN.md

Tóm tắt phạm vi đã chốt và có thể kèm Mermaid mô tả luồng nghiệp vụ; là nguồn excerpt trong context pack (không thay thế toàn bộ spec trong chat).

beguru_chat_context.json

Cấu trúc tóm tắt (theo contract API): merge shallow với body chat; dùng cho PM pins ([PINNED_USER_INFO], [PINNED_KYB], [PINNED_PROJECT_CONTEXT], …). Có thể có backend_output_path trong project_context để excerpt CROSS_STACK khi khóa BackendSpec.

.guru/rules và bundle Engineer

Template Next.js ship kèm .guru/rules/; server load thứ tự cố định cùng bundles/engineer_nextjs/core.md (xem README trong template và ARCHITECTURE_RUNTIME.md mục Engineer Next.js).

Phụ thuộc đọc thêm

• Tổng quan kiến trúc — map hệ thống.
• Runtime — route generate-code, init-project.
• Memory & context — thứ tự ghim và context pack.

---