SurfSense/_bmad-output/planning-artifacts/detailed-feature-flows-extended.md

SurfSense: Sơ đồ chi tiết các Luồng Ẩn (Triển khai Sâu)

Dựa trên việc kiểm tra sâu cấu trúc database (db.py) và kiến trúc API, đây là các Luồng Vi mô (Micro Flows) diễn ra bên dưới bề nổi bổ sung thêm cho 4 luồng cơ bản ban đầu. Đây là các Flow cấu thành sức mạnh hệ sinh thái nền tảng của SurfSense.

---

5. Luồng Đồng bộ Thời gian thực & Local-first (RociCorp Zero)

Giao diện của SurfSense đạt được tốc độ phản hồi tính bằng mili-giây (Instant UI) nhờ vào công nghệ Local-first từ Zero.

sequenceDiagram
    participant User as Nguoi Dung
    participant NextJS as NextJS Client (Z-Store)
    participant Zero as Zero Cache Server
    participant Postgres as PostgreSQL DB

    %% Trang thai offline hoac low-latency
    User->>NextJS: Tao Search Space moi
    activate NextJS
    NextJS->>NextJS: Ghi vao IndexedDB (Local)
    NextJS-->>User: [UI] Cap nhat ngay lap tuc (0 latency)
    
    %% Dong bo background
    NextJS->>Zero: Day Mutator (Sync)
    deactivate NextJS
    
    activate Zero
    Zero->>Postgres: Luu thay đoi vao DB trung tam
    Postgres-->>Zero: Xac nhan luu thanh cong
    
    %% Nguoi dung khac trong cung Search Space
    Zero->>NextJS: Ban Replication Subscriptions (Socket)
    deactivate Zero
    activate NextJS
    NextJS->>NextJS: Cap nhat Z-Store cho User B
    deactivate NextJS

---

6. Luồng Uỷ quyền và Nuốt Dữ liệu từ App Thứ 3 (Third-Party Connectors)

Quy trình nhập liệu từ các nền tảng SaaS (Notion, Google Drive, Jira...) sử dụng Composio và Custom Extractors.

sequenceDiagram
    participant User as Nguoi Dung
    participant Web as Web UI
    participant Backend as FastAPI
    participant Auth as Composio OAuth
    participant 3rdParty as Notion/Drive/Jira
    participant Celery as ETL Celery Workers

    User->>Web: Bam ket noi "Notion"
    Web->>Backend: Yeu cau Authorization URL
    Backend->>Auth: Tao Phien ung dung (Session)
    Auth-->>User: Chuyen huong sang trang OAuth cua Notion
    
    User->>3rdParty: Dong y cap quyen đoc
    3rdParty-->>Backend: Callback Redirect voi Auth Code
    activate Backend
    Backend->>Auth: Đoi Code lay Access Token
    Auth-->>Backend: Tra ve Token
    Backend->>Backend: Luu vao Search Space DB
    deactivate Backend
    
    %% Kich hoat Ingestion
    Backend->>Celery: Giao nhiem vu Crawl API (Task)
    activate Celery
    Celery->>3rdParty: Pull hang loat Docs / Tickets
    3rdParty-->>Celery: Tra ve JSON data
    Celery->>Celery: Convert JSON -> Markdown -> Chunks
    Celery->>Celery: Luu VectorDB
    Celery-->>Web: Notification: "Dong bo Notion hoan tat"
    deactivate Celery

---

7. Luồng Giao tiếp Cộng tác & Bình luận (Collaboration / Chat Comments)

Mỗi Search Space trong SurfSense là một "Phòng làm việc chung". Các đoạn Chat AI có thể được bình luận, chia sẻ.

sequenceDiagram
    participant UserA as Nguoi Dung A
    participant Zero as Zero (Realtime)
    participant DB as Postgres (Chat_Comments)
    participant UserB as Nguoi Dung B

    UserA->>UserA: Mo đoan chat cua Assistant
    UserA->>Zero: Them Comment "@UserB cậu xem đoan nay"
    activate Zero
    Zero->>DB: Luu Comment vao NewChatMessage
    
    %% Tinh nang cap nhat tu đong cho UserB
    DB-->>Zero: State Changed
    Zero-->>UserB: Trigger Sync (Realtime) tang IndexedDB
    deactivate Zero
    
    activate UserB
    UserB->>UserB: Thay notification Mention tren UI
    UserB->>Zero: Reply lai Comment
    deactivate UserB

---

8. Luồng Phát sinh Nội dung Đa phương tiện từ RAG (Podcast / Video)

Trình độ tổng hợp kiến thức của SurfSense không dừng ở đoạn text, mà còn mở rộng ra Audio, Podcasts, Video Presentation dựa trên DB Models.

sequenceDiagram
    participant User as Nguoi Dung
    participant Web as Web UI
    participant API as FastAPI
    participant Celery as Celery Tasks
    participant GenAI as Audio/Video Gen AI
    participant DB as Postgres

    User->>Web: "Tao Podcast ve chu đe bao cao thang nay"
    activate Web
    Web->>API: POST /api/generate-podcast
    deactivate Web
    
    activate API
    API->>DB: Tao ban ghi PodcastStatus = PENDING
    API->>Celery: Send task `generate_podcast`
    API-->>Web: Tra ve Job ID
    deactivate API
    
    activate Celery
    Celery->>DB: Update PodcastStatus = GENERATING
    Celery->>GenAI: Truyen RAG content & Yeu cau sinh giong noi
    activate GenAI
    GenAI-->>Celery: Tra ve Stream/File URL (Media)
    deactivate GenAI
    
    Celery->>DB: Update PodcastStatus = READY & Luu Media Path
    deactivate Celery
    
    %% Cap nhat UI qua Zero
    DB-->>Zero: State Mutation
    Zero-->>Web: Giao dien hien thi Audio Player