# azure/azure-cosmosdb-java architecture

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

- Interactive diagram: https://gitdiagram.com/azure/azure-cosmosdb-java
- Repository: https://github.com/azure/azure-cosmosdb-java

## Overview

##### Project Type and Purpose
- This is an open-source Java SDK (v2.x) for the SQL API of Azure Cosmos DB. It provides:
- A high-level async API (AsyncDocumentClient) for Java applications
- Two transport implementations (“gateway” over HTTP/HTTPS, “direct” over TCP with Rntbd)
- Shared domain/model classes, tools (benchmark, examples, test-utils)
- Samples and performance utilities

##### High-Level Module Breakdown (from the file tree)
- Parent pom.xml
- commons
- Core domain classes (Document, Database, PartitionKey, etc.)
- sdk
- Public async client (AsyncDocumentClient) and client implementation
- gateway
- GatewayStoreModel, HTTP retry policies, session token management, query engine
- direct-impl
- RntbdTransportClient, transport channel pool, health checks, TCP protocol codec
- commons-test-utils
- Test helpers and validators for all modules
- examples
- Standalone sample apps demonstrating usage
- benchmark
- Performance benchmark harness (sync/async mixed workloads)
- faq, changelog, security, CI config

##### Core Architectural Components
A. Public API Layer
- AsyncDocumentClient.Builder → builds AsyncDocumentClient instance
- Exposes RxJava Observable<ResourceResponse<T>> operations
B. Shared Domain Model
- Classes in commons define resources, exceptions, policies, serializers
C. Transport Abstraction
- IStoreClient / TransportClient interfaces
- Gateway HTTP layer (gateway module)
- Direct TCP layer (direct-impl module with Rntbd protocol)
D. Underlying Service
- Azure Cosmos DB service (external)
- Optional Cosmos DB Emulator (local)
E. Support Tools
- Examples project (usage patterns)
- Benchmark project (performance testing)
- Test utilities (commons-test-utils)

##### Interactions and Data Flow
1. Client code calls AsyncDocumentClient.<operation>()
2. AsyncDocumentClient checks ConnectionPolicy (Direct vs. Gateway mode)
3. Depending on mode:
– Gateway mode → RxGatewayStoreModel → HTTP over HTTPS → Cosmos DB Gateway endpoint
– Direct mode → RntbdTransportClient → TCP connections → Cosmos DB replica nodes
4. Response flows back through TransportClient → Observable pipeline → user code
5. Session tokens, consistency policies and retry logic applied in gateway/direct layers

##### Detailed Elements
- API vs. Transport vs. External

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layers and components
    subgraph "Public API Layer"
        AsyncClient1["AsyncDocumentClient"]:::api
        RxImpl["RxDocumentClientImpl"]:::api
    end

    Mode{"ConnectionPolicy Decision"}:::model

    subgraph "Transport Abstraction"
        IStoreClient["IStoreClient Interfaces"]:::model
        TransportClient["TransportClient Interfaces"]:::model
    end

    subgraph "Gateway Transport"
        RxGateway["RxGatewayStoreModel"]:::gateway
        RetryPolicy["RetryPolicy"]:::gateway
        SessionContainer["SessionContainer"]:::gateway
        QueryEngine["Query Engine Components"]:::gateway
    end

    subgraph "Direct Transport"
        RntbdClient["RntbdTransportClient"]:::direct
        ChannelPool["RntbdClientChannelPool"]:::direct
        HealthChecker["RntbdClientChannelHealthChecker"]:::direct
        Codec["Rntbd Codec Classes"]:::direct
        StoreClient["StoreClient"]:::direct
        StoreFactory["StoreClientFactory"]:::direct
        ConsistencyReader["ConsistencyReader"]:::direct
        ConsistencyWriter["ConsistencyWriter"]:::direct
    end

    subgraph "Shared Domain Model"
        SharedDomain["commons (Document, Database, ... )"]:::model
    end

    subgraph "External Service"
        AzureService["Azure Cosmos DB Service"]:::external
        Emulator["Cosmos DB Emulator"]:::external
    end

    subgraph "Support Tools"
        Examples["Examples"]:::support
        Benchmark["Benchmark"]:::support
        TestUtils["Test Utilities"]:::support
    end

    %% Connections
    SharedDomain --> AsyncClient1
    SharedDomain --> RxGateway
    SharedDomain --> RntbdClient

    AsyncClient1 --> RxImpl
    AsyncClient1 --> Mode
    Mode -->|Gateway| RxGateway
    Mode -->|Direct| RntbdClient

    IStoreClient --> RntbdClient
    TransportClient --> RntbdClient

    RxGateway --> RetryPolicy
    RxGateway --> SessionContainer
    RxGateway --> QueryEngine

    RntbdClient --> ChannelPool
    RntbdClient --> HealthChecker
    RntbdClient --> Codec
    RntbdClient --> StoreClient
    RntbdClient --> StoreFactory
    RntbdClient --> ConsistencyReader
    RntbdClient --> ConsistencyWriter

    RxGateway -->|HTTP/HTTPS| AzureService
    RntbdClient -->|TCP| AzureService

    AzureService -.->|response| RxGateway
    AzureService -.->|response| RntbdClient
    RxGateway -.->|response| AsyncClient1
    RntbdClient -.->|response| AsyncClient1

    Examples --> AsyncClient1
    Benchmark --> AsyncClient1
    TestUtils --> AsyncClient1

    %% Click events
    click AsyncClient1 "https://github.com/azure/azure-cosmosdb-java/blob/master/sdk/src/main/java/com/microsoft/azure/cosmosdb/rx/AsyncDocumentClient.java"
    click RxImpl "https://github.com/azure/azure-cosmosdb-java/blob/master/sdk/src/main/java/com/microsoft/azure/cosmosdb/rx/internal/RxDocumentClientImpl.java"
    click IStoreClient "https://github.com/azure/azure-cosmosdb-java/blob/master/direct-impl/src/main/java/com/microsoft/azure/cosmosdb/internal/directconnectivity/IStoreClient.java"
    click TransportClient "https://github.com/azure/azure-cosmosdb-java/blob/master/direct-impl/src/main/java/com/microsoft/azure/cosmosdb/internal/directconnectivity/TransportClient.java"
    click RxGateway "https://github.com/azure/azure-cosmosdb-java/blob/master/gateway/src/main/java/com/microsoft/azure/cosmosdb/rx/internal/RxGatewayStoreModel.java"
    click RetryPolicy "https://github.com/azure/azure-cosmosdb-java/blob/master/gateway/src/main/java/com/microsoft/azure/cosmosdb/internal/RetryPolicy.java"
    click SessionContainer "https://github.com/azure/azure-cosmosdb-java/blob/master/gateway/src/main/java/com/microsoft/azure/cosmosdb/internal/SessionContainer.java"
    click QueryEngine "https://github.com/azure/azure-cosmosdb-java/tree/master/gateway/src/main/java/com/microsoft/azure/cosmosdb/internal/query/"
    click RntbdClient "https://github.com/azure/azure-cosmosdb-java/blob/master/direct-impl/src/main/java/com/microsoft/azure/cosmosdb/internal/directconnectivity/RntbdTransportClient.java"
    click ChannelPool "https://github.com/azure/azure-cosmosdb-java/blob/master/direct-impl/src/main/java/com/microsoft/azure/cosmosdb/internal/directconnectivity/rntbd/RntbdClientChannelPool.java"
    click HealthChecker "https://github.com/azure/azure-cosmosdb-java/blob/master/direct-impl/src/main/java/com/microsoft/azure/cosmosdb/internal/directconnectivity/rntbd/RntbdClientChannelHealthChecker.java"
    click Codec "https://github.com/azure/azure-cosmosdb-java/tree/master/direct-impl/src/main/java/com/microsoft/azure/cosmosdb/internal/directconnectivity/rntbd/"
    click StoreClient "https://github.com/azure/azure-cosmosdb-java/blob/master/direct-impl/src/main/java/com/microsoft/azure/cosmosdb/internal/directconnectivity/StoreClient.java"
    click StoreFactory "https://github.com/azure/azure-cosmosdb-java/blob/master/direct-impl/src/main/java/com/microsoft/azure/cosmosdb/internal/directconnectivity/StoreClientFactory.java"
    click SharedDomain "https://github.com/azure/azure-cosmosdb-java/tree/master/commons/src/main/java/com/microsoft/azure/cosmosdb/"
    click Examples "https://github.com/azure/azure-cosmosdb-java/tree/master/examples/src/main/java/com/microsoft/azure/cosmosdb/rx/examples/"
    click Benchmark "https://github.com/azure/azure-cosmosdb-java/tree/master/benchmark/src/main/java/com/microsoft/azure/cosmosdb/benchmark/"
    click TestUtils "https://github.com/azure/azure-cosmosdb-java/tree/master/commons-test-utils/src/main/java/com/microsoft/azure/cosmosdb/"

    %% Styles
    classDef api fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef model fill:#E6FFEA,stroke:#28A745,color:#28A745;
    classDef gateway fill:#FFF4E5,stroke:#D69E2E,color:#D69E2E;
    classDef direct fill:#F3E5FF,stroke:#6F42C1,color:#6F42C1;
    classDef external fill:#EDEDED,stroke:#6A737D,color:#6A737D;
    classDef support fill:#E5F6FF,stroke:#1F6FEB,color:#1F6FEB;
```
