SurfSense API Contracts

Tổng quan

SurfSense Backend cấu trúc hệ thống APIs thành các Routers chuẩn RESTful (thư mục api/routes). Toàn bộ API đều trả về type hints giúp FastAPI tự động serialize Pydantic ra Swagger UI và các Frontend Generator có thể tiêu thụ.

1. Nhóm API Quản Trị Hệ Thống / Tài Khoản

auth_routes.py: Quản lý OAuth/Login, Tokens, Session Refresh.
rbac_routes.py: Role-based Access Control API, lấy quyền truy cập Workspace/Search Spaces.
stripe_routes.py: Webhooks và API phục vụ payment/subscriptions nếu có.
logs_routes.py, notifications_routes.py: Đẩy Log errors, gửi các Notifications system.

2. Nhóm API Core Search & AI

search_spaces_routes.py: Tạo, cập nhật, xóa các Knowledge Bases cô lập.
new_chat_routes.py, public_chat_routes.py: Mọi call Stream SSE/WebSocket cho tin nhắn từ AI Agent, cũng như query dữ liệu Chat Threads cũ.
search_source_connectors_routes.py: Trung tâm điều hướng cấu hình các External Syncs. Thường làm việc chung với Backend Workers.

3. Nhóm Connectors Bên Thứ 3

Các Connectors này định nghĩa quá trình OAuth Consent hoặc Add Webhooks để cào dữ liệu:

google_drive_add_connector_route.py
slack_add_connector_route.py
notion_add_connector_route.py
confluence_add_connector_route.py, jira_add_connector_route.py
discord_add_connector_route.py (Và khoảng 10 nền tảng khác).

4. Nhóm AI Outputs Đa Phương Tiện

Mở rộng LLM capabilities beyond text:

image_generation_routes.py: Sinh hình ảnh từ context.
vision_llm_routes.py: Parse hình ảnh thành Text (OCR hoặc Context).
podcasts_routes.py: Sinh Audio / Deep Dive từ documents.
video_presentations_routes.py: Tạo video tổng hợp.
reports_routes.py, export_routes.py: Chuyển đổi Chat Output thành format Markdown, PDF.

Quy Chuẩn Tương Tác

Backend sử dụng chuẩn Pydantic Models (nằm ở surfsense_backend/app/schemas/) rải đều qua response response_model=....
Client gọi thông qua tanstack-query được define trong surfsense_web/api/. Riêng đối với dữ liệu Realtime, Client hoàn toàn bypass API POST/GET truyền thống mà dùng @rocicorp/zero để mutate trực tiếp vào Schema.

2.4 KiB Raw Blame History