Goal

Sinh file sequence diagram Mermaid (.mermaid) chính xác từ mô tả luồng chức năng
trong vòng 1-2 phút, chỉ happy path, sẵn sàng import draw.io — thay vì user
phải tự viết syntax Mermaid thủ công mất 15-30 phút.

Instructions

1. Thu thập input — Đọc mô tả luồng chức năng user cung cấp (text, file tài liệu,
   hoặc Use Case). Xác định:

   • Tên chức năng (dùng đặt tên file output)
   • Danh sách actors/participants tham gia
   • Các bước tương tác giữa participants
   • Các giai đoạn (phases) chính của luồng

   Nếu user chưa cung cấp đủ → hỏi bổ sung:

   • "Luồng này có những bên nào tham gia?" (nếu thiếu participants)
   • "Có thể mô tả từng bước tương tác không?" (nếu thiếu chi tiết)

2. Xác định participants — Liệt kê tất cả thành phần tham gia:

   • Format: participant [Alias ngắn] as [Tên đầy đủ có ý nghĩa]
   • Sắp xếp theo thứ tự: User/KH → Client App → Backend → Database → External Systems
   • Alias ngắn gọn (2-6 ký tự), tên đầy đủ tiếng Việt hoặc English tùy context
   • Gộp internal components khi document là external-facing
     (ví dụ: Client + Server → "Hệ thống SME" nếu gửi cho đối tác)

3. Phân chia giai đoạn — Xác định các phase chính của luồng:

   • Dùng Note over [Participant đầu], [Participant cuối]: [TÊN GIAI ĐOẠN]
   • Tên giai đoạn: CHỮ HOA, ngắn gọn, mô tả đúng nghĩa
   • Thường 2-5 giai đoạn tùy độ phức tạp
   • Ví dụ: KHỞI TẠO, XÁC THỰC, XỬ LÝ NGHIỆP VỤ, CẬP NHẬT DỮ LIỆU, HOÀN TẤT

4. Viết sequence messages — Sinh từng bước tương tác:

   • Đánh số liên tục xuyên suốt diagram: 1. Mô tả, 2. Mô tả, ...
   • Request: A->>B: [Số]. [Mô tả hành động]
   • Response/Return: B-->>A: [Số]. [Mô tả dữ liệu trả về]
   • Internal processing: A->>A: [Mô tả xử lý nội bộ]
   • Mỗi message ≤60 ký tự, súc tích, dùng thuật ngữ nghiệp vụ
   • Hiển thị ĐẦY ĐỦ cả 2 chiều (request + response) cho mỗi tương tác
   • Phân biệt rõ: ->> (request/action) vs -->> (response/return data)

5. Lọc CHỈ happy path — Loại bỏ hoàn toàn:

   • ❌ Tất cả case lỗi, exception, error handling
   • ❌ Các khối alt/else cho negative flow
   • ❌ Retry logic, timeout, fallback
   • ✅ Giữ lại opt/loop CHỈ KHI là phần bắt buộc của happy path
     (ví dụ: loop qua danh sách items là happy path, nhưng retry khi lỗi thì không)

6. Tổ hợp và sinh file — Ghép tất cả thành file .mermaid hoàn chỉnh:

   • Bắt đầu bằng sequenceDiagram
   • Thứ tự: participants → giai đoạn 1 + messages → giai đoạn 2 + messages → ...
   • Indent 2 spaces cho tất cả dòng sau sequenceDiagram
   • Đặt tên file: [tên-chức-năng]-sequence.mermaid (kebab-case)
   • Lưu tại /mnt/user-data/outputs/

7. ✅ VERIFY trước khi output:

   • Syntax Mermaid hợp lệ (không lỗi parse)
   • Numbering liên tục, không nhảy số
   • Mỗi request có response tương ứng (trừ fire-and-forget)
   • Không có alt/else cho error case
   • Tên file đúng convention
   • Participants đúng thứ tự, alias không trùng
   • Message ≤60 ký tự
   • Có ít nhất 1 Note over phân chia giai đoạn

8. Present file — Dùng present_files tool để hiển thị file cho user download.
   Kèm tóm tắt ngắn: số participants, số bước, số giai đoạn.

Examples

📚 Xem ví dụ chi tiết trong examples/

Ví dụ 1: Luồng đăng nhập OTP — Happy path đơn giản

Context: User cần vẽ sequence diagram cho luồng đăng nhập bằng SMS OTP
trong app mobile banking.

Input:

Vẽ sequence diagram cho luồng đăng nhập bằng SMS OTP:
- Khách hàng nhập số điện thoại
- Hệ thống gửi OTP qua SMS
- Khách hàng nhập OTP
- Hệ thống xác thực và trả về token

Output:

sequenceDiagram
  participant KH as Khách hàng
  participant App as Mobile App
  participant Server as Backend Server
  participant SMS as SMS Gateway

  Note over KH, SMS: KHỞI TẠO ĐĂNG NHẬP

  KH->>App: 1. Nhập số điện thoại
  App->>Server: 2. Gửi yêu cầu đăng nhập (phone)
  Server->>SMS: 3. Yêu cầu gửi OTP
  SMS-->>KH: 4. Gửi SMS chứa mã OTP

  Note over KH, SMS: XÁC THỰC OTP

  KH->>App: 5. Nhập mã OTP
  App->>Server: 6. Gửi OTP xác thực
  Server->>Server: 7. Xác thực OTP + tạo session token
  Server-->>App: 8. Trả về access token
  App->>App: 9. Lưu token + chuyển màn hình chính

Ví dụ 2: Luồng eKYC SDK — Nhiều participants, nhiều giai đoạn

Context: User cần vẽ luồng tích hợp eKYC SDK của ngân hàng đối tác,
có 5 actors, document gửi cho đối tác nên gộp internal components.

Input:

Vẽ sequence cho luồng thu thập sinh trắc học qua SDK eKYC:
- App gọi SDK eKYC của ngân hàng
- SDK thu thập ảnh CCCD + khuôn mặt
- SDK gửi lên eKYC Server xác thực
- Kết quả trả về App để lưu trữ

Output:

sequenceDiagram
  participant KH as Khách hàng
  participant App as Hệ thống App SME
  participant SDK as SDK eKYC đối tác
  participant eKYC as eKYC Server
  participant Core as CoreBanking

  Note over KH, Core: KHỞI TẠO THU THẬP STH

  KH->>App: 1. Chọn chức năng xác thực STH
  App->>App: 2. Chuẩn bị tham số gọi SDK
  App->>SDK: 3. Gọi SDK eKYC (clientId, config)
  SDK->>SDK: 4. Khởi tạo camera + UI thu thập

  Note over KH, Core: THU THẬP DỮ LIỆU SINH TRẮC HỌC

  SDK->>KH: 5. Hiển thị màn hình chụp CCCD mặt trước
  KH->>SDK: 6. Chụp ảnh CCCD mặt trước
  SDK->>KH: 7. Hiển thị màn hình chụp CCCD mặt sau
  KH->>SDK: 8. Chụp ảnh CCCD mặt sau
  SDK->>KH: 9. Hiển thị màn hình chụp khuôn mặt
  KH->>SDK: 10. Chụp ảnh selfie

  Note over KH, Core: XÁC THỰC VÀ TRẢ KẾT QUẢ

  SDK->>eKYC: 11. Gửi dữ liệu STH lên server
  eKYC->>eKYC: 12. OCR + đối chiếu khuôn mặt
  eKYC->>Core: 13. Truy vấn thông tin KH
  Core-->>eKYC: 14. Trả dữ liệu KH từ CoreBanking
  eKYC-->>SDK: 15. Trả kết quả xác thực
  SDK-->>App: 16. Callback kết quả (data STH)
  App->>App: 17. Lưu trữ dữ liệu STH vào hệ thống
  App-->>KH: 18. Hiển thị kết quả xác thực thành công

Constraints

• 🚫 KHÔNG ĐƯỢC vẽ bất kỳ error flow, exception, hay alt/else cho lỗi nào —
  chỉ happy path duy nhất. Lý do: diagram phục vụ mục đích truyền đạt luồng
  chính cho stakeholders, không phải tài liệu kỹ thuật chi tiết.

• 🚫 KHÔNG ĐƯỢC viết message dài quá 60 ký tự — diagram sẽ bị vỡ layout
  khi render hoặc import draw.io.

• 🚫 KHÔNG ĐƯỢC bỏ sót chiều response khi tương tác 2 chiều —
  mỗi request phải có return tương ứng (trừ fire-and-forget như gửi notification).

• ✅ LUÔN LUÔN đánh số liên tục từ 1 đến hết, không nhảy số, không reset
  numbering giữa các giai đoạn.

• ✅ LUÔN LUÔN có ít nhất 1 dòng Note over để phân chia giai đoạn,
  giúp người đọc nhanh chóng nắm được flow tổng quan.

• ✅ LUÔN LUÔN dùng -->> (nét đứt) cho response/return data và
  ->> (nét liền) cho request/action — giúp phân biệt chiều tương tác.

• ⚠️ CHÚ Ý: Khi vẽ cho tài liệu gửi đối tác bên ngoài, nên gộp
  Client + Server thành 1 participant duy nhất (ví dụ: "Hệ thống SME")
  để không lộ kiến trúc nội bộ. Hỏi user nếu chưa rõ audience.

• ⚠️ CHÚ Ý: Mô tả bước nên dùng thuật ngữ nghiệp vụ tiếng Việt
  (hoặc theo ngôn ngữ user yêu cầu), tránh thuật ngữ kỹ thuật low-level
  trừ khi cần thiết cho context.