SurfSense/docs/architecture-backend.md

Kiến Trúc Hệ Thống: Backend (surfsense_backend)

1. Tổng Quan

Backend của SurfSense (viết bằng Python 3.12) chịu trách nhiệm chính trong việc xử lý Data Ingestion, Indexing, LLM Orchestration và cung cấp REST APIs cho các Client.

2. Công Nghệ Cốt Lõi

• Môi trường Server: FastAPI, Uvicorn
• Database & ORM: PostgreSQL, SQLAlchemy, Alembic (Migration), pgvector (Vector DB)
• Task Queue & Background Jobs: Celery, Redis
• AI / LLM Framework: LangChain, LangGraph, LiteLLM
• Xử lý Dữ liệu: Unstructured, Docling, Playwright

3. Cấu Trúc Mã Nguồn (Directory Structure)

surfsense_backend/app/
├── agents/              # Định nghĩa LangGraph agents / chains để xử lý luồng AI
├── api/routes/          # Chứa các endpoint API (users, chat, documents...)
├── connectors/          # Logic kết nối bên thứ 3 (Google Drive, Slack, Composio)
├── db.py                # Điểm khai báo Core Models của SQLAlchemy
├── etl_pipeline/        # Pipeline trích xuất dữ liệu, chunking text, transform
├── indexing_pipeline/   # Chịu trách nhiệm tạo embedding và push vào VectorDB
├── prompts/             # Template lưu trữ prompt chuẩn cho các luồng LLM
├── schemas/             # Pydantic models (validation cho request/response)
├── services/            # Tầng Business Logic (CRUD, gọi API ngoài)
├── tasks/               # Các Celery task (Background jobs xử lý nặng)
└── utils/               # Các hàm tiện ích (helper functions, formats, parsing)

4. Pipeline Architecture & Search (Deep Dive)

4.1 ETL Pipeline (etl_pipeline/)

Chịu trách nhiệm trích xuất văn bản từ nhiều định dạng file khác nhau.

• Entry point: EtlPipelineService.extract() phân loại file (classify_file) thành các nhóm (PLAINTEXT, DIRECT_CONVERT, AUDIO, IMAGE, DOCUMENT).
• Parsers Tích Hợp:
  • docling: Xử lý PDF/tài liệu phức tạp (via parse_with_docling).
  • unstructured: Parser thay thế cho tài liệu chung.
  • llamacloud / Azure Document Intelligence: Dùng làm internal accelerator để tối ưu chi phí/tốc độ.
  • vision_llm: Fallback parse ảnh nếu model Vision có sẵn.
  • audio: Dùng model transcribe.

4.2 Indexing Pipeline (indexing_pipeline/)

Chịu trách nhiệm chunking, tính toán embedding, chống trùng lặp và lưu trữ vào Vector DB.

• State Feedback Tức Thì: create_placeholder_documents() tạo ra các Document "Pending" vào DB ngay khi upload, giúp đồng bộ Zero Sync hiển thị UI lập tức.
• Deduplication: Dựa vào compute_content_hash và compute_unique_identifier_hash để chống duplicate khi document đã tồn tại và không đổi.
• Chunking & Embedding: Chạy bất đồng bộ (asyncio.to_thread) với hàm chunk_text() (có hỗ trợ riêng cho code chunking) và embed_texts() (chạy qua LiteLLM/OpenAI).
• Concurrency Control: Hàm index_batch_parallel() dùng asyncio.Semaphore để giới hạn số luồng (mặc định 4) tránh rate-limit từ APIs.

4.3 Retriever & Hybrid Search (retriever/)

Kết hợp sức mạnh Full-text search của Postgres và Vector search của pgvector.

• Hybrid Search Flow (chunks_hybrid_search.py):
  • Tính toán tsvector/tsquery (Keyword Search) và L2 Distance / Cosine Similarity Chunk.embedding.op("<=>") (Semantic Search).
  • Sử dụng chung RRF (Reciprocal Rank Fusion) ở cấp database (bằng CTE) để cho điểm 1.0 / (k + rank).
  • Phân trang & giới hạn: Fetch một số chunk nhất định mỗi document bằng ROW_NUMBER() trong subquery, tăng performance khi đọc những file dài/nhiều chunk.

5. Patterns Hiện Có

• Tiêm Phụ Thuộc (Dependency Injection): Backend chia nhỏ logic theo các Service Class (services/, EtlPipelineService, IndexingPipelineService) sau đó inject vào Router thông qua Depends().
• Bất Đồng Bộ (Asynchronous Operations):
  • Database Call: Sử dụng asyncpg và session async từ SQLAlchemy.
  • Xử lý nặng (Compute-Bound): Offload qua asyncio.to_thread() (VD: chunking, embedding generation).
• Tách Biệt Task Queue: Các thao tác Indexing bulk hoặc crawl dữ liệu qua Playwright đều được push qua Redis để Celery worker processing.

6. Deployment Info

Dự án được triển khai bằng Docker (có docker-compose.yml đi kèm cho Dev Environment chạy đủ bộ FastAPI, Postgres (pg17 vector), Redis, Celery Worker, Zero-Cache cache sync daemon).