# qdrant/rust-client architecture

> Architecture diagram of the GitHub repository qdrant/rust-client, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/qdrant/rust-client
- Repository: https://github.com/qdrant/rust-client

## Overview

##### Project Type and Purpose
- This is an open-source Rust client library for the Qdrant vector-search engine.
- It provides high-level, type-safe Rust APIs that wrap gRPC calls to a Qdrant server.
- Key use cases: Create and manage collections, upsert/search points, snapshots, payload filters, etc.

##### File Structure Analysis
- Top-level:
- proto/ – Protocol Buffer definitions for Qdrant services.
- src/ – Library source code:
– src/qdrant.rs (tonic‐generated gRPC stubs)
– src/qdrant_client/… (high-level client module)
– src/client/… (deprecated or alternate client)
– src/builders/… (typed request builders for each API call)
– src/grpc_conversions/… (conversion logic between Rust types and protobuf)
– src/auth.rs, config.rs, error.rs, prelude.rs, payload.rs (support modules)
- examples/ – runnable Rust examples (deprecated_search.rs, search.rs)
- tests/ – integration tests, builder‐coverage, snippet tests
- tools/sync_proto.sh – regenerates Rust code from .proto files
- build.rs – build script to invoke tonic_build and protoc

##### README Insights
- Emphasizes gRPC via Tonic, async usage (Tokio), and Protobuf compilation.
- Shows end-to-end usage: Qdrant::from_url → builders → .await calls → JSON payloads.
- Mentions optional Qdrant Cloud integration with API key.

a. Main Components
1. Protobuf Definitions (proto/*.proto)
2. Code Generation Pipeline
- protoc + tonic_build (build.rs / tools/sync_proto.sh)
→ src/qdrant.rs & client stubs
3. Library Core
- Qdrant entrypoint (src/lib.rs → Qdrant struct)
- Builders Layer (src/builders/**/*_builder.rs)
- gRPC Conversion Layer (src/grpc_conversions)
- Error & Config (src/error.rs, src/client/config.rs)
4. External Dependencies
- Tonic (gRPC runtime)
- Tokio (async runtime)
- Serde (JSON payloads)
5. External Service
- Qdrant Server (HTTP/gRPC endpoint)
b. Relationships & Interactions
- Developer code → invokes Qdrant::from_url / Qdrant::with_api_key
→ selects builder (e.g., SearchPointsBuilder)
→ builds request object (typed Rust struct)
→ conversion layer transforms to protobuf request
→ Tonic gRPC client sends request → Qdrant server
→ Server responds with protobuf response
→ conversion layer maps to Rust domain types → returns to caller
c. Architectural Patterns
- Layered architecture: Builders → Conversion → Transport → Server
- Code generation (protoc + tonic_build) separates interface from implementation
- Modular crates: clear separation between generated stubs, client logic, and builders
d. Key Technologies & Frameworks
- Rust, Cargo, build.rs
- Protobuf & protoc
- Tonic (gRPC)
- Tokio (async)
- Serde (JSON serialization)
- GitHub Actions (lint/test/publish workflows)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build Pipeline
    subgraph "Build Pipeline"
        style BuildPipeline stroke-dasharray: 5 5
        ProtoDefs["Protobuf Definitions\n(proto/)"]:::codegen
        BuildRS["build.rs"]:::codegen
        SyncProto["tools/sync_proto.sh"]:::codegen
    end

    %% Code Generation
    subgraph "Code Generation"
        GenStubs["Generated gRPC Stubs\n(src/qdrant.rs)"]:::codegen
    end

    %% Library Core
    subgraph "Library Core"
        QdrantStruct["Qdrant Struct\n(src/lib.rs)"]:::logic
        subgraph "Request Builders"
            Builders["Builders Layer\n(src/builders/)"]:::logic
            QdrantClientBuilders["Qdrant-Client Builders\n(src/qdrant_client/builders/)"]:::logic
        end
        subgraph "Conversion Layer"
            Conv["gRPC Conversion Layer\n(src/grpc_conversions/)"]:::logic
            QdrantClientConv["Qdrant-Client Conversion\n(src/qdrant_client/conversions/)"]:::logic
        end
        ErrorModule["Error Handling\n(src/error.rs)"]:::logic
        ClientConfig["Core Client Config\n(src/client/config.rs)"]:::logic
        LegacyClient["Legacy Client API\n(src/client/)"]:::logic
        HighLevelClient["High-Level Qdrant Client\n(src/qdrant_client/)"]:::logic
        Auth["Authentication Support\n(src/auth.rs)"]:::logic
        Payload["Payload Types & Logic\n(src/payload.rs)"]:::logic
        Prelude["Prelude Exports\n(src/prelude.rs)"]:::logic
        QdrantClientError["Qdrant-Client Error\n(src/qdrant_client/error.rs)"]:::logic
    end

    %% Examples & Tests
    subgraph "Examples & Tests"
        Examples["examples/"]:::external
        Tests["tests/"]:::external
    end

    %% Runtime Dependencies
    subgraph "Runtime Dependencies"
        Tonic["Tonic (gRPC)"]:::runtime
        Tokio["Tokio (Async)"]:::runtime
        Serde["Serde (JSON)"]:::runtime
    end

    %% External Service
    QdrantServer["Qdrant Server\n(External)"]:::external

    %% Connections
    ProtoDefs -->|defines| GenStubs
    BuildRS -->|invokes protoc| GenStubs
    SyncProto -->|invokes protoc| GenStubs

    GenStubs -->|used by| QdrantStruct
    QdrantStruct -->|constructs| Builders
    QdrantStruct -->|calls| Conv
    Builders -->|creates requests| Conv
    Conv -->|generates protobuf| Tonic
    HighLevelClient -->|wraps| QdrantStruct
    HighLevelClient -->|uses| Builders
    HighLevelClient -->|uses| Conv
    HighLevelClient -->|handles errors via| QdrantClientError

    LegacyClient -->|alternate API| QdrantStruct
    ClientConfig -->|provides| QdrantStruct
    Auth -->|provides| QdrantStruct
    Payload -->|used by| Builders
    Prelude -->|exports| HighLevelClient

    Tonic -->|runs on| Tokio
    Tonic -->|sends requests to| QdrantServer
    Tokio -->|drives async code| QdrantStruct
    Serde -->|serializes JSON| Builders

    Examples -->|show usage| HighLevelClient
    Tests -->|validate| Builders

    %% Click Events
    click ProtoDefs "https://github.com/qdrant/rust-client/tree/master/proto/"
    click BuildRS "https://github.com/qdrant/rust-client/blob/master/build.rs"
    click SyncProto "https://github.com/qdrant/rust-client/blob/master/tools/sync_proto.sh"
    click GenStubs "https://github.com/qdrant/rust-client/blob/master/src/qdrant.rs"
    click QdrantStruct "https://github.com/qdrant/rust-client/blob/master/src/lib.rs"
    click Builders "https://github.com/qdrant/rust-client/tree/master/src/builders/"
    click Conv "https://github.com/qdrant/rust-client/tree/master/src/grpc_conversions/"
    click ErrorModule "https://github.com/qdrant/rust-client/blob/master/src/error.rs"
    click ClientConfig "https://github.com/qdrant/rust-client/blob/master/src/client/config.rs"
    click LegacyClient "https://github.com/qdrant/rust-client/tree/master/src/client/"
    click HighLevelClient "https://github.com/qdrant/rust-client/tree/master/src/qdrant_client/"
    click QdrantClientBuilders "https://github.com/qdrant/rust-client/tree/master/src/qdrant_client/builders/"
    click QdrantClientConv "https://github.com/qdrant/rust-client/tree/master/src/qdrant_client/conversions/"
    click QdrantClientError "https://github.com/qdrant/rust-client/blob/master/src/qdrant_client/error.rs"
    click Auth "https://github.com/qdrant/rust-client/blob/master/src/auth.rs"
    click Payload "https://github.com/qdrant/rust-client/blob/master/src/payload.rs"
    click Prelude "https://github.com/qdrant/rust-client/blob/master/src/prelude.rs"

    %% Styles
    classDef codegen fill:#D0E8FF,stroke:#0366D6
    classDef logic fill:#E6FFDD,stroke:#28A745
    classDef runtime fill:#FFF5CC,stroke:#FFDF00
    classDef external fill:#FFE5D9,stroke:#FF5722
```
