flowchart LR
    Client[Ứng dụng khách]
    API[REST API EzyVector]
    Auth[Xác thực API key và IP]
    Validator[Kiểm tra request]
    Service[Dịch vụ vector]
    DB[(Cơ sở dữ liệu)]
    Raw[(Vector file store)]
    Memory[HNSW trong bộ nhớ]
    HNSW[(HNSW store)]
    Response[JSON response]

    Client --> API
    API --> Auth
    Auth --> Validator
    Validator --> Service

    Service --> DB
    Service --> Raw
    Service --> Memory
    Memory --> HNSW

    DB --> Service
    Raw --> Service
    HNSW --> Memory

    Service --> Response
    Response --> Client

sequenceDiagram
    participant C as Client
    participant A as REST API
    participant S as Vector service
    participant DB as Cơ sở dữ liệu
    participant FS as Vector file store
    participant H as HNSW store

    C->>A: PUT /collections/{name}
    A->>A: Kiểm tra API key, IP và request
    A->>S: Tạo collection nếu chưa tồn tại
    S->>DB: Tìm collection theo tên

    alt Collection chưa tồn tại
        S->>DB: Lưu metadata collection
    else Collection đã tồn tại
        S-->>S: Giữ nguyên cấu hình hiện tại
    end

    S->>DB: Đảm bảo có mutable segment
    S->>FS: Kiểm tra tiến độ backfill
    S->>H: Nạp hoặc khởi động build HNSW
    S-->>A: Hoàn tất
    A-->>C: result=true, status=ok

sequenceDiagram
    participant C as Client
    participant A as REST API
    participant S as Vector service
    participant DB as Cơ sở dữ liệu
    participant FS as Vector file store
    participant H as HNSW trong bộ nhớ
    participant HF as HNSW store

    C->>A: PUT /collections/{name}/points
    A->>A: Xác thực và kiểm tra danh sách point
    A->>S: Upsert points
    S->>DB: Lấy collection và kích thước vector

    loop Với từng point
        S->>DB: Tìm point theo collectionId và pointId
        alt Point chưa tồn tại
            S->>DB: Tạo point
        else Point đã tồn tại
            S->>DB: Cập nhật vector và payload
        end
    end

    S->>FS: Chuẩn hóa và ghi vector
    S->>H: Thêm hoặc thay thế node
    opt HNSW đã sẵn sàng
        H->>HF: Lưu lại chỉ mục
    end

    S-->>A: Hoàn tất
    A-->>C: result=true, status=ok

flowchart TD
    Request[POST points/search]
    Auth[Kiểm tra API key và IP]
    Validate[Kiểm tra vector và limit]
    Collection[Đọc collection từ database]
    Ready{HNSW đã sẵn sàng?}
    HnswSearch[Tìm kiếm gần đúng bằng HNSW]
    ExactSearch[Exact search trên vector file store]
    Metadata[Đọc point và payload từ database]
    Result[Trả id, score và payload]

    Request --> Auth
    Auth --> Validate
    Validate --> Collection
    Collection --> Ready

    Ready -->|Có| HnswSearch
    Ready -->|Chưa| ExactSearch

    HnswSearch --> Metadata
    ExactSearch --> Metadata
    Metadata --> Result