mirror of
https://github.com/MODSetter/SurfSense.git
synced 2026-04-27 01:36:30 +02:00
92 lines
4.6 KiB
Markdown
92 lines
4.6 KiB
Markdown
|
# SurfSense: Sơ đồ Macro User Flow Toàn Hệ Thống
|
||
|
|
|
||
|
|
Sau khi đào thật sâu vào toàn bộ source code của dự án, em phát hiện ra SurfSense không chỉ là một Web App đơn thuần. Đây là một **Hệ sinh thái đa nền tảng (Macro Ecosystem)** bao gồm 4 khối lớn làm việc chặt chẽ với nhau: `surfsense_web`, `surfsense_desktop`, `surfsense_browser_extension`, và `surfsense_backend`.
|
||
|
|
|
||
|
|
Đây là sự liên kết luồng thao tác của người dùng xuyên suốt toàn bộ các nền tảng của hệ thống:
|
||
|
|
|
||
|
|
```mermaid
|
||
|
|
graph TD
|
||
|
|
classDef web fill:#09090b,stroke:#a5b4fc,stroke-width:2px,color:#fff;
|
||
|
|
classDef desk fill:#1e1b4b,stroke:#8b5cf6,stroke-width:2px,color:#fff;
|
||
|
|
classDef ext fill:#18181b,stroke:#f472b6,stroke-width:2px,color:#fff;
|
||
|
|
classDef back fill:#27272a,stroke:#34d399,stroke-width:2px,color:#fff,stroke-dasharray: 5 5;
|
||
|
|
|
||
|
|
%% -------------------
|
||
|
|
%% 1. Web Flow (Surfsense_web)
|
||
|
|
%% -------------------
|
||
|
|
subgraph WebApp ["1. SurfSense Web (Next.js)"]
|
||
|
|
Login["Identity Provider (Auth/Callback)"]:::web
|
||
|
|
Dashboard["Dashboard & Search Spaces"]:::web
|
||
|
|
Connectors["Cloud Connectors (OAuth)"]:::web
|
||
|
|
Billing["Billing & Settings"]:::web
|
||
|
|
end
|
||
|
|
|
||
|
|
%% -------------------
|
||
|
|
%% 2. Desktop App Flow (Surfsense_desktop)
|
||
|
|
%% -------------------
|
||
|
|
subgraph DesktopApp ["2. SurfSense Desktop (Electron)"]
|
||
|
|
DLogin["Deep Link Login (Qua Web)"]:::desk
|
||
|
|
FolderWatcher["Folder Watcher (Dong bo file local)"]:::desk
|
||
|
|
QuickAsk["Quick Ask (Hoi nhanh kieu Spotlight)"]:::desk
|
||
|
|
Tray["System Tray & Phim Tat"]:::desk
|
||
|
|
end
|
||
|
|
|
||
|
|
%% -------------------
|
||
|
|
%% 3. Browser Extension Flow
|
||
|
|
%% -------------------
|
||
|
|
subgraph BrowserExt ["3. SurfSense Extension"]
|
||
|
|
ExtPopup["Popup UI & Auth"]:::ext
|
||
|
|
ExtCapture["Web Content Capture (Doc trang web)"]:::ext
|
||
|
|
end
|
||
|
|
|
||
|
|
%% -------------------
|
||
|
|
%% 4. Backend Core Flow
|
||
|
|
%% -------------------
|
||
|
|
subgraph Backend ["4. SurfSense Backend (FastAPI, Celery)"]
|
||
|
|
API["Core API Routes"]:::back
|
||
|
|
ETL["ETL & Indexing Pipeline (Xu ly Data)"]:::back
|
||
|
|
Agents["AI Agents (LLMs)"]:::back
|
||
|
|
Retriever["Vector Search / RAG"]:::back
|
||
|
|
end
|
||
|
|
|
||
|
|
%% --- Giao thiep Auth ---
|
||
|
|
DLogin -->|"Goi URL trinh duyet"| Login
|
||
|
|
ExtPopup -->|"Xac thuc session"| Login
|
||
|
|
Login --> Dashboard
|
||
|
|
|
||
|
|
%% --- Giao thiep Data (Ingestion) ---
|
||
|
|
FolderWatcher -->|"Lang nghe & ban file PDF/Doc"| API
|
||
|
|
ExtCapture -->|"Gửi the Tabs/HTML"| API
|
||
|
|
Connectors -->|"Trigger Cloud Sync"| API
|
||
|
|
|
||
|
|
API -->|"Jobs"| ETL
|
||
|
|
|
||
|
|
%% --- Giao thiep hoi dap (Chat) ---
|
||
|
|
Dashboard -->|"Gui Chat"| API
|
||
|
|
QuickAsk -->|"Spotlight Search"| API
|
||
|
|
|
||
|
|
API -->|"Retrieve Context"| Retriever
|
||
|
|
Retriever -->|"Context"| Agents
|
||
|
|
Agents -->|"Streaming Tra loi"| API
|
||
|
|
```
|
||
|
|
|
||
|
|
## Các phám phá cốt lõi (Deep Dive Findings)
|
||
|
|
|
||
|
|
1. **Local-First Synchronization với Desktop App (`surfsense_desktop`)**
|
||
|
|
- Ứng dụng Desktop không chỉ để dùng web. Nó chứa module `folder-watcher.ts` liên tục quét thư mục trên máy tính người dùng và tự động đẩy dữ liệu (PDF, Docs) lên hệ thống để AI đọc. Đây là luồng ingest data hoàn toàn ngầm mà user không cần thao tác upload thủ công trên giao diện web.
|
||
|
|
- Nó cũng chứa module `quick-ask.ts`, cho phép user dùng tổ hợp phím gợi Spotlight Bar để hỏi đáp AI nhanh mà không cần mở app.
|
||
|
|
|
||
|
|
2. **Cánh tay nối dài Browser Extension (`surfsense_browser_extension`)**
|
||
|
|
- Luồng lưu trữ nội dung web: User đọc bài báo ở các tab, bấm vào extension để Capture và đưa thẳng nội dung đó vào "Search Space".
|
||
|
|
|
||
|
|
3. **Backend Pipeline khổng lồ (`surfsense_backend`)**
|
||
|
|
- Đằng sau API là một dây chuyền công nghiệp: Nhận file -> `celery` chia việc -> `etl_pipeline` xử lý văn bản -> `indexing_pipeline` tự động cắt đoạn và lưu vector DB.
|
||
|
|
- Phần trả lời là do module `agents` và `retriever` đảm nhiệm (chuẩn RAG).
|
||
|
|
|
||
|
|
**Phân tích UX:**
|
||
|
|
Nhờ việc kiểm tra chéo này, em nhận ra UX của Web App không cần quá nhấn mạnh vào nút "Upload File" khổng lồ như các app khác, vì SurfSense đã giải quyết vấn đề nhập liệu ngầm thông qua **Desktop Folder Watcher** và **Browser Extension/Cloud Connectors**.
|
||
|
|
|
||
|
|
Do đó, UI Web app (`The Scholar` direction) chỉ cần tối tưu cho việc **Hiển thị, Tra cứu và Trí tuệ (Chat Layout)**.
|
||
|
|
|
||
|
|
Anh thấy sự móc nối sinh thái đa nền tảng này đã mô tả đúng tầm nhìn kiến trúc của SurfSense chưa ạ?
|