# mironathome/qdrant-client architecture

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

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

## Overview

##### Project type and purpose
- Type: Open-source Python client library / SDK
- Purpose: Provide a unified, typed, sync/async API to interact with the Qdrant vector search engine in three modes:
- Remote via REST
- Remote via gRPC
- Local (in-process)

##### File structure to uncover logical layers
- Top-level package: qdrant_client/
- Subpackages:
- async_* & client_base.py – Facade classes (QdrantClient, AsyncQdrantClient)
- connection.py – Strategy for HTTP vs gRPC vs local transport
- grpc/ – Auto-generated gRPC stubs & helpers
- http/ – REST API wrappers, models, configuration, exceptions
- local/ – In-process vector store, persistence, distance computations
- embed/ – Embedding framework (FastEmbed + ONNX runtime)
- auth/ – Bearer token support
- conversions/ – Serialization/deserialization (Python ↔ Protobuf/JSON)
- uploader/ – Chunked upload strategies for large payloads (gRPC & REST)
- hybrid/ – Hybrid search/reranking formulas
- migrate/ – Version-migration scripts
- Tools & docs: code generators (tools/async_client_generator), docs/, tests/

##### README for additional architectural hints
- Modes (host/port, URL, cloud_inference)
- Features: sync/async parity, type hints, minimal deps, local mode
- Inference API: local vs remote

##### Main components & their interactions
a. Facade layer:
- QdrantClient (sync) & AsyncQdrantClient (async)
- Exposes methods: create_collection, upsert, query_points, upload_collection, etc.
b. Transport layer (Strategy pattern):
- HTTP client (requests/urllib3) ↔ qdrant_client/http/api_client.py
- gRPC client (grpcio stubs in qdrant_client/grpc/)
- Local engine (qdrant_client/local/) implements same interface
c. API wrappers:
- HTTP/API modules (collections_api.py, points_api.py, …)
- gRPC wrappers (generated stubs + helper methods)
d. Serialization layer:
- conversion.py, common_types.py – map Python models to JSON/Protobuf
e. Embedding/inference subsystem:
- qdrant_client/embed/ – ONNX model loading, inference, caching
- Invoked by QdrantClient when Document(model=…) is passed
f. Uploader subsystem:
- grpc_uploader.py & rest_uploader.py – handle chunking, retries
g. Auth subsystem:
- bearer_auth.py – inject API keys into headers
h. Persistence / Local mode:
- qdrant_client/local/qdrant_local.py – file-based or in-memory store
- Implements distance calculations, indexing, filters
i. External systems:
- Qdrant server (REST/gRPC endpoint)
- ONNX Runtime (for fastembed)
- Qdrant Cloud (remote inference API)

##### Architectural patterns & design principles
- Facade: QdrantClient abstracts multiple transports & underlying API complexities
- Strategy: connection.py picks HTTP vs gRPC vs local at runtime
- Adapter: local modules adapt in-process storage to the same API contracts as remote
- Single Responsibility: separate packages for transport, serialization, embedding, uploading

##### Detailed breakdown
- Layer 1 (Facade):
- QdrantClient / AsyncQdrantClient
- Layer 2 (Configuration & Auth):
- configuration.py (timeout, retries, grpc_port, prefer_grpc)
- bearer_auth.py → HTTP headers or gRPC metadata
- Layer 3 (Transport Strategy):
– HTTPTransport → HTTP API modules
– GRPCTransport → gRPC stubs
– LocalTransport → Local modules
- Layer 4a (HTTP Path):
- api_client.py → requests.Session
- http/api/*.py → JSON endpoints
- models/models.py → Pydantic models for request/response
- Layer 4b (gRPC Path):
- grpc/collections_pb2_grpc.py → gRPC stub class
- grpc/points_pb2_grpc.py → gRPC stub class
- Conversion layer wraps stubs in Pythonic methods
- Layer 4c (Local Path):
- local/qdrant_local.py → in-memory DB
- local/persistence.py → file-based persistence
- local/distances.py, local/geo.py → vector ops
- Layer 5 (Embedding):
- embed/embedder.py → ModelEmbedder + ONNX Runtime backend
- Called by Query/Upload flows when Document(text, model) is passed
- Layer 6 (Uploader):
- grpc_uploader.py / rest_uploader.py for bulk data
- External:
- Qdrant Server (HTTP / gRPC endpoints)
- ONNX Runtime (backend for embedding)
- Filesystem or memory for local mode

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Facade Layer
    subgraph "Facade Layer"
        QC["QdrantClient"]:::facade
        AQC["AsyncQdrantClient"]:::facade
    end

    %% Config & Auth
    subgraph "Configuration & Auth"
        CFG["configuration.py"]:::config
        AUTH["bearer_auth.py"]:::config
    end

    %% Transport Strategy
    subgraph "Transport Strategy"
        CONN["Connection Manager"]:::transport
        HTTPT["HTTPTransport"]:::transport
        GPRCT["GRPCTransport"]:::transport
        LOCT["LocalTransport"]:::transport
    end

    %% HTTP Path
    subgraph "HTTP Path"
        APIC["api_client.py"]:::http
        ENDPTS["collections_api.py"]:::http
        HTTPCFG["configuration.py"]:::http
        HTTPEX["exceptions.py"]:::http
        HTTPMDL["models/models.py"]:::http
    end

    %% gRPC Path
    subgraph "gRPC Path"
        GRPC1["collections_pb2_grpc.py"]:::grpc
        GRPC2["points_pb2_grpc.py"]:::grpc
        GRPC3["qdrant_pb2_grpc.py"]:::grpc
    end

    %% Local Path
    subgraph "Local Path"
        LCLMAIN["qdrant_local.py"]:::local
        LCLCOL["local_collection.py"]:::local
        LCLPST["persistence.py"]:::local
        LCLDST["distances.py"]:::local
        LCLMDST["multi_distances.py"]:::local
        LCLGEO["geo.py"]:::local
        LCLASY["async_qdrant_local.py"]:::local
    end

    %% Serialization
    subgraph "Serialization / Conversion"
        CTYPES["common_types.py"]:::conv
        CONV["conversion.py"]:::conv
    end

    %% Embedding Subsystem
    subgraph "Embedding Subsystem"
        EMB["embedder.py"]:::embed
        MODEL["model_embedder.py"]:::embed
        INSPECT["embed_inspector.py"]:::embed
        CACHE["_inspection_cache.py"]:::embed
        SCHEMA["schema_parser.py"]:::embed
        TYPEI["type_inspector.py"]:::embed
    end

    %% Uploader Subsystem
    subgraph "Uploader Subsystem"
        GRPCUP["grpc_uploader.py"]:::uploader
        RESTUP["rest_uploader.py"]:::uploader
        UPIF["uploader.py"]:::uploader
    end

    %% Hybrid Subsystem
    subgraph "Hybrid Subsystem"
        FORM["formula.py"]:::hybrid
        FUSN["fusion.py"]:::hybrid
    end

    %% Migration Scripts
    subgraph "Migration"
        MIG["migrate.py"]:::misc
    end

    %% Code Generation Tools
    subgraph "Codegen Tools"
        TOOLS["async_client_generator"]:::tools
    end

    %% External Services
    subgraph "External Services"
        QS["Qdrant Server"]:::external
        ONNX["ONNX Runtime"]:::external
        FS["Filesystem / Memory"]:::external
    end

    %% Connections
    User["User Code"]:::external
    User -->|"calls"| QC
    User -->|"calls"| AQC
    QC -->|"uses"| CFG
    QC -->|"uses"| AUTH
    AQC -->|"uses"| CFG
    AQC -->|"uses"| AUTH

    QC -->|"delegates to"| CONN
    AQC -->|"delegates to"| CONN

    CONN -->|"selects"| HTTPT
    CONN -->|"selects"| GPRCT
    CONN -->|"selects"| LOCT

    HTTPT -->|"HTTP/JSON"| APIC
    APIC -->|"endpoints"| ENDPTS
    APIC -->|"uses models"| HTTPMDL
    APIC -->|"config/exceptions"| HTTPCFG
    APIC -->|"config/exceptions"| HTTPEX
    ENDPTS -->|"serialize/deserialize"| CONV

    GPRCT -->|"gRPC/Protobuf"| GRPC1
    GPRCT -->|"gRPC/Protobuf"| GRPC2
    GPRCT -->|"gRPC/Protobuf"| GRPC3
    GRPC1 -->|"wraps stub"| CONV
    GRPC2 -->|"wraps stub"| CONV
    GRPC3 -->|"wraps stub"| CONV

    LOCT -->|"in-process API"| LCLMAIN
    LCLMAIN -->|"collection ops"| LCLCOL
    LCLMAIN -->|"persistence"| LCLPST
    LCLMAIN -->|"vector ops"| LCLDST
    LCLMAIN -->|"vector ops"| LCLMDST
    LCLMAIN -->|"geo ops"| LCLGEO
    LOCT -->|"async variant"| LCLASY

    QC -->|"embed when needed"| EMB
    EMB -->|"loads model"| MODEL
    MODEL -->|"inspects schema"| SCHEMA
    MODEL -->|"caches"| CACHE
    SCHEMA -->|"type introspection"| TYPEI
    EMB -->|"metadata"| INSPECT

    QC -->|"bulk upload"| UPIF
    UPIF -->|"uses REST"| RESTUP
    UPIF -->|"uses gRPC"| GRPCUP

    QC -->|"hybrid search"| FORM
    QC -->|"hybrid fusion"| FUSN

    QC -->|"migrations"| MIG

    QC -->|"codegen"| TOOLS

    HTTPT -->|"calls"| QS
    GPRCT -->|"calls"| QS
    LOCT -->|"stores to"| FS
    MODEL -->|"executes on"| ONNX

    %% Click Events
    click QC "https://github.com/mironathome/qdrant-client/blob/master/qdrant_client/qdrant_client.py"
    click AQC "https://github.com/mironathome/qdrant-client/blob/master/qdrant_client/async_qdrant_client.py"
    click CONN "https://github.com/mironathome/qdrant-client/blob/master/qdrant_client/connection.py"
    click APIC "https://github.com/mironathome/qdrant-client/blob/master/qdrant_client/http/api_client.py"
    click ENDPTS "https://github.com/mironathome/qdrant-client/blob/master/qdrant_client/http/api/collections_api.py"
    click HTTPCFG "https://github.com/mironathome/qdrant-client/blob/master/qdrant_client/http/configuration.py"
    click HTTPEX "https://github.com/mironathome/qdrant-client/blob/master/qdrant_client/http/exceptions.py"
    click HTTPMDL "https://github.com/mironathome/qdrant-client/blob/master/qdrant_client/http/models/models.py"
    click GRPC1 "https://github.com/mironathome/qdrant-client/blob/master/qdrant_client/grpc/collections_pb2_grpc.py"
    click GRPC2 "https://github.com/mironathome/qdrant-client/blob/master/qdrant_client/grpc/points_pb2_grpc.py"
    click GRPC3 "https://github.com/mironathome/qdrant-client/blob/master/qdrant_client/grpc/qdrant_pb2_grpc.py"
    click LCLMAIN "https://github.com/mironathome/qdrant-client/blob/master/qdrant_client/local/qdrant_local.py"
    click LCLCOL "https://github.com/mironathome/qdrant-client/blob/master/qdrant_client/local/local_collection.py"
    click LCLPST "https://github.com/mironathome/qdrant-client/blob/master/qdrant_client/local/persistence.py"
    click LCLDST "https://github.com/mironathome/qdrant-client/blob/master/qdrant_client/local/distances.py"
    click LCLMDST "https://github.com/mironathome/qdrant-client/blob/master/qdrant_client/local/multi_distances.py"
    click LCLGEO "https://github.com/mironathome/qdrant-client/blob/master/qdrant_client/local/geo.py"
    click LCLASY "https://github.com/mironathome/qdrant-client/blob/master/qdrant_client/local/async_qdrant_local.py"
    click CTYPES "https://github.com/mironathome/qdrant-client/blob/master/qdrant_client/conversions/common_types.py"
    click CONV "https://github.com/mironathome/qdrant-client/blob/master/qdrant_client/conversions/conversion.py"
    click AUTH "https://github.com/mironathome/qdrant-client/blob/master/qdrant_client/auth/bearer_auth.py"
    click EMB "https://github.com/mironathome/qdrant-client/blob/master/qdrant_client/embed/embedder.py"
    click MODEL "https://github.com/mironathome/qdrant-client/blob/master/qdrant_client/embed/model_embedder.py"
    click INSPECT "https://github.com/mironathome/qdrant-client/blob/master/qdrant_client/embed/embed_inspector.py"
    click CACHE "https://github.com/mironathome/qdrant-client/blob/master/qdrant_client/embed/_inspection_cache.py"
    click SCHEMA "https://github.com/mironathome/qdrant-client/blob/master/qdrant_client/embed/schema_parser.py"
    click TYPEI "https://github.com/mironathome/qdrant-client/blob/master/qdrant_client/embed/type_inspector.py"
    click GRPCUP "https://github.com/mironathome/qdrant-client/blob/master/qdrant_client/uploader/grpc_uploader.py"
    click RESTUP "https://github.com/mironathome/qdrant-client/blob/master/qdrant_client/uploader/rest_uploader.py"
    click UPIF "https://github.com/mironathome/qdrant-client/blob/master/qdrant_client/uploader/uploader.py"
    click FORM "https://github.com/mironathome/qdrant-client/blob/master/qdrant_client/hybrid/formula.py"
    click FUSN "https://github.com/mironathome/qdrant-client/blob/master/qdrant_client/hybrid/fusion.py"
    click MIG "https://github.com/mironathome/qdrant-client/blob/master/qdrant_client/migrate/migrate.py"
    click TOOLS "https://github.com/mironathome/qdrant-client/tree/master/tools/async_client_generator"

    %% Styles
    classDef facade fill:#E0F7FA,stroke:#006064,color:#006064
    classDef config fill:#E8F5E9,stroke:#1B5E20,color:#1B5E20
    classDef transport fill:#E8F5E9,stroke:#2E7D32,color:#2E7D32
    classDef http fill:#E3F2FD,stroke:#0D47A1,color:#0D47A1
    classDef grpc fill:#E3F2FD,stroke:#1A237E,color:#1A237E
    classDef local fill:#FFF3E0,stroke:#E65100,color:#E65100
    classDef conv fill:#F3E5F5,stroke:#6A1B9A,color:#6A1B9A
    classDef embed fill:#F3E5F5,stroke:#4A148C,color:#4A148C
    classDef uploader fill:#FFFDE7,stroke:#F57F17,color:#F57F17
    classDef hybrid fill:#FCE4EC,stroke:#880E4F,color:#880E4F
    classDef misc fill:#ECEFF1,stroke:#37474F,color:#37474F
    classDef tools fill:#E0F2F1,stroke:#004D40,color:#004D40
    classDef external fill:#CFD8DC,stroke:#455A64,color:#455A64
```
