# qdrant/qdrant-client architecture

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

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

## Overview

##### Main components
- Client API Layer: Two main flavors are offered – the synchronous API (QdrantClient) and asynchronous API (AsyncQdrantClient). Both interfaces expose similar functionality.
- API Communication Modules:
- HTTP API: Located under the “qdrant_client/http” directory with modules for API endpoints (collections, points, snapshots, service API, etc.), models, and exceptions.
- gRPC API: The “qdrant_client/grpc” directory holds the auto-generated gRPC modules, including service definitions and protocol buffers.
- Local Mode: Implemented in “qdrant_client/local” to simulate or run Qdrant API operations without requiring an external server. This module includes everything needed for persistence to disk or in-memory (":memory:") storage.
- Embedding Functionality: The “qdrant_client/embed” and “qdrant_client/fastembed_common.py” modules support FastEmbed which uses ONNX Runtime for CPU (or GPU) based vector embeddings.
- Authentication & Authorization: Modules in “qdrant_client/auth”, particularly for bearer authentication.
- Conversions and common utilities: Found in “qdrant_client/conversions” and “qdrant_client/common”.
- Tools & Code Generation: Located in the “tools” directory, these scripts help generate async clients, REST/gRPC clients, documentation, and also work with an inspection cache for embedding purposes.
- Tests and Continuous Integration: There is an extensive “tests” directory along with CI/CD configuration (GitHub workflows, pre-commit hooks, mypy, etc.) that ensures high test coverage and quality.

##### Relationships and interactions
- The client library (both sync and async) acts as a mediator between the user’s application and the Qdrant server (via HTTP or gRPC connections) or the local mode.
- A client instantiation may interact with authentication modules and connection modules to establish a session.
- When executing operations (create collection, upsert, query, etc.), the client calls the corresponding HTTP or gRPC API component.
- The FastEmbed integration is used when generating vector representations; this forms another sub-component fed into the upload and query paths.
- The conversion utilities help translate between Python objects and the protocol formats required for both HTTP and gRPC.
- The “tools” as well as documentation generators interact indirectly with the core modules to provide both client code generation and developer guidance.

##### Architectural patterns and design principles
- Modularity: The project is neatly organized into modules such as “http”, “grpc”, “local”, “auth”, and “conversions”, which helps in separating concerns.
- Dual Architecture: Both synchronous and asynchronous patterns are supported, implying a design that maximizes reuse of internal logic while providing two interface layers.
- Abstraction: The client abstracts underlying protocols (HTTP and gRPC) so that users can choose the desired mode seamlessly.
- Extensibility: With folder structures such as “embed”, “tools”, and “grpc” handling auto-generated code, the design anticipates further extension and integration with other services.

##### Final checklist for the principal software engineer
- Clearly delineate each major component (client APIs, communication protocols, embedding modules, local mode, tools).
- Be detailed – include auxiliary components like authentication, conversion, testing, and documentation generation tools.
- Both synchronous and asynchronous flows, showing how each mode interacts with HTTP/gRPC and local persistence.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client API Layer
    subgraph "Client API Layer"
        QC_sync["QdrantClient (Sync)"]:::client
        QC_async["QdrantClient (Async)"]:::client
    end

    %% API Communication Modules
    subgraph "API Communication Modules"
        HTTP["HTTP API Module"]:::http
        GRPC["gRPC API Module"]:::grpc
    end

    %% Other Components
    LM["Local Mode"]:::local
    EE["Embedding Engine (FastEmbed)"]:::embed
    Auth["Authentication & Authorization"]:::auth
    Conv["Conversion Utilities & Common"]:::conv
    Tools["Tools & Code Generation"]:::tools
    Tests["Tests & CI/CD"]:::tests
    Server["Qdrant Server (External)"]:::external

    %% Relationships from Client API Layer to Communication Modules
    QC_sync -->|"calls"| HTTP
    QC_sync -->|"calls"| GRPC
    QC_async -->|"calls"| HTTP
    QC_async -->|"calls"| GRPC

    %% Local Mode integration
    QC_sync -->|"local_mode?"| LM
    QC_async -->|"local_mode?"| LM

    %% Embedding integration into clients
    EE -->|"provides embeddings"| QC_sync
    EE -->|"provides embeddings"| QC_async

    %% Authentication integration
    QC_sync -->|"authenticates via"| Auth
    QC_async -->|"authenticates via"| Auth
    HTTP -->|"uses"| Auth
    GRPC -->|"uses"| Auth

    %% Conversion utilities integration
    HTTP -->|"converts data via"| Conv
    GRPC -->|"converts data via"| Conv

    %% API Modules interaction with External Qdrant Server
    HTTP -->|"REST calls"| Server
    GRPC -->|"gRPC calls"| Server

    %% Tools & Testing supporting modules
    Tools -->|"generates clients/docs"| QC_sync
    Tools -->|"generates clients/docs"| QC_async
    Tools -->|"assists with embedding"| EE
    Tests -->|"validates all modules"| QC_sync
    Tests -->|"validates all modules"| QC_async
    Tests -->|"validates"| HTTP
    Tests -->|"validates"| GRPC
    Tests -->|"validates"| LM

    %% Click Events for Component Mapping
    click QC_sync "https://github.com/qdrant/qdrant-client/blob/master/qdrant_client/qdrant_client.py"
    click QC_async "https://github.com/qdrant/qdrant-client/blob/master/qdrant_client/async_qdrant_client.py"
    click HTTP "https://github.com/qdrant/qdrant-client/tree/master/qdrant_client/http/"
    click GRPC "https://github.com/qdrant/qdrant-client/tree/master/qdrant_client/grpc/"
    click LM "https://github.com/qdrant/qdrant-client/tree/master/qdrant_client/local/"
    click EE "https://github.com/qdrant/qdrant-client/tree/master/qdrant_client/embed/"
    click Auth "https://github.com/qdrant/qdrant-client/blob/master/qdrant_client/auth/bearer_auth.py"
    click Conv "https://github.com/qdrant/qdrant-client/tree/master/qdrant_client/conversions/"
    click Tools "https://github.com/qdrant/qdrant-client/tree/master/tools/"
    click Tests "https://github.com/qdrant/qdrant-client/tree/master/tests/"

    %% Class Definitions for Colors
    classDef client fill:#ADF7B6,stroke:#333,stroke-width:2px;
    classDef http fill:#FFD591,stroke:#333,stroke-width:2px;
    classDef grpc fill:#FF9C9C,stroke:#333,stroke-width:2px;
    classDef local fill:#B5EAEA,stroke:#333,stroke-width:2px;
    classDef embed fill:#D6A4A4,stroke:#333,stroke-width:2px;
    classDef auth fill:#C3B1E1,stroke:#333,stroke-width:2px;
    classDef conv fill:#F3D19C,stroke:#333,stroke-width:2px;
    classDef tools fill:#C9E4C5,stroke:#333,stroke-width:2px;
    classDef tests fill:#E4C1F9,stroke:#333,stroke-width:2px;
    classDef external fill:#F7CADA,stroke:#333,stroke-width:2px;
```
