# ydb-platform/ydb-cpp-sdk architecture

> Architecture diagram of the GitHub repository ydb-platform/ydb-cpp-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ydb-platform/ydb-cpp-sdk
- Repository: https://github.com/ydb-platform/ydb-cpp-sdk

## Overview

#### Purpose and consumption
This repository builds the YDB C++ SDK: a C++ client library for connecting applications to YDB over gRPC. It is not a standalone server or web application. Consumer entry points are the installed public headers and CMake targets, notably `include/ydb-cpp-sdk/client/driver/driver.h`, `include/ydb-cpp-sdk/client/table/table.h`, and `include/ydb-cpp-sdk/client/topic/client.h`. Runnable sample entry points live under `examples/`, e.g. `examples/basic_example/main.cpp`.

#### Build, packaging, and API generation
CMake is the composition boundary for SDK libraries, generated protobuf/grpc code, examples, and installable artifacts: `CMakeLists.txt`, `src/CMakeLists.txt`, and `cmake/protobuf.cmake`. Protocol contracts originate in YDB protobuf definitions such as `src/api/protos/ydb_table.proto` and gRPC service definitions such as `src/api/grpc/ydb_table_v1.proto`. Debian packaging publishes the core SDK plus optional IAM and OpenTelemetry plugins through `cmake/PackSDK.cmake` and `scripts/build_cpack_deb_packages.sh`.

#### Driver, discovery, and transport core
`TDriver` is the principal runtime root: applications configure it with endpoint/database/credentials, then construct service-specific clients. Its implementation is `src/client/driver/driver.cpp`, backed by shared client abstractions in `src/client/common_client/impl/client.cpp`. Driver state owns authentication, endpoint selection, and connection lifecycle in `src/client/impl/internal/db_driver_state/state.cpp`, `src/client/impl/internal/db_driver_state/endpoint_pool.cpp`, and `src/client/impl/internal/grpc_connections/grpc_connections.cpp`. This layer separates public client APIs from gRPC channels and discovered YDB endpoints.

#### Request execution, resilience, and concurrency
Service calls pass through common request construction and status conversion before reaching generated gRPC stubs: `src/client/impl/internal/make_request/make.cpp` and `src/client/impl/internal/plain_status/status.cpp`. Retry policy and retry state are centralized rather than embedded per service in `src/client/impl/internal/retry/retry.cpp` and `src/library/retry/retry.cpp`. Async execution and background work are provided through the SDK executor/thread-pool layers, including `src/client/impl/executor/executor_impl.cpp` and `src/client/impl/internal/thread_pool/pool.cpp`; public APIs expose futures, sessions, callbacks, or event streams as appropriate.

#### Data APIs: table/query and value boundaries
The table and query clients translate C++ values, parameters, transactions, sessions, and result rows to/from YDB protobuf payloads. Key boundaries are public value/result types in `include/ydb-cpp-sdk/client/value/value.h` and `include/ydb-cpp-sdk/client/result/result.h`, with implementations in `src/client/value/value.cpp` and `src/client/result/result.cpp`. Stateful table sessions, pooling, request migration, and transactions reside in `src/client/table/impl/table_client.cpp`, `src/client/table/impl/transaction.cpp`, and `src/client/impl/session/session_pool.cpp`. The newer query-service path has analogous session and execution handling in `src/client/query/impl/client_session.cpp` and `src/client/query/impl/exec_query.cpp`.

#### Streaming and control-plane clients
The SDK exposes separate clients for YDB services including scheme, coordination, discovery, import/export, monitoring, secrets, and rate limiting; representative implementations are `src/client/scheme/scheme.cpp`, `src/client/coordination/coordination.cpp`, and `src/client/discovery/discovery.cpp`. Topic messaging is a major asynchronous subsystem: read/write sessions, producer logic, event handling, offsets, deferred commits, and transactions are implemented under `src/client/topic/impl/read_session.cpp`, `src/client/topic/impl/write_session.cpp`, and `src/client/topic/impl/producer.cpp`. Federated Topic adds cross-endpoint observation and federated read/write coordination in `src/client/federated_topic/impl/federation_observer.cpp` and `src/client/federated_topic/impl/federated_topic_impl.cpp`.

#### Security and observability extensions
Credentials support is a pluggable boundary spanning standard credentials, login, IAM, and OAuth2/JWT token exchange: `src/client/types/credentials/credentials.cpp`, `src/client/iam/iam.cpp`, and `src/client/types/credentials/oauth2_token_exchange/credentials.cpp`. TLS trust resources ship with the SDK in `src/client/resources/ydb_root_ca.pem`. Core metrics/tracing abstractions are implemented in `src/client/impl/observability/metrics.cpp` and `src/client/impl/observability/span.cpp`; optional OpenTelemetry adapters are separately built plugins in `plugins/metrics/otel/metrics.cpp` and `plugins/trace/otel/trace.cpp`, using vendored OpenTelemetry sources.

#### Runtime and external dependencies
The material runtime stack is C++17 with gRPC/protobuf for YDB RPCs, OpenSSL for TLS/crypto, and compression libraries used by streaming/codecs. Build dependency discovery and compatibility logic is concentrated in `cmake/external_libs.cmake` and `cmake/FindBrotli.cmake`. YDB is the primary external service; IAM/OAuth endpoints may be contacted by credential providers, and optional observability can export through OpenTelemetry integrations.

Main entry points: [`include/ydb-cpp-sdk/client/driver/driver.h`](https://github.com/ydb-platform/ydb-cpp-sdk/blob/main/include/ydb-cpp-sdk/client/driver/driver.h) (Public SDK APIs), [`src/client/common_client/impl/client.cpp`](https://github.com/ydb-platform/ydb-cpp-sdk/blob/main/src/client/common_client/impl/client.cpp) (Common client layer), [`src/client/driver/driver.cpp`](https://github.com/ydb-platform/ydb-cpp-sdk/blob/main/src/client/driver/driver.cpp) (TDriver), [`CMakeLists.txt`](https://github.com/ydb-platform/ydb-cpp-sdk/blob/main/CMakeLists.txt) (CMake composition)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Build & distribution"]
  node_examples["Runnable examples<br/>C++ executable<br/>[main.cpp]"]
  node_cmake["CMake composition<br/>build system<br/>[CMakeLists.txt]"]
  node_proto_contracts["YDB protocol contracts<br/>protobuf + gRPC<br/>[ydb_table.proto]"]
  node_grpc_generation["Generated RPC code<br/>code generation<br/>[protobuf.cmake]"]
  node_packaging["Debian SDK packages<br/>distribution<br/>[PackSDK.cmake]"]
end

subgraph group_runtime["SDK runtime core"]
  node_driver{{"TDriver<br/>runtime root<br/>[driver.cpp]"}}
  node_client_common["Common client layer<br/>client abstraction<br/>[client.cpp]"]
  node_driver_state["Driver state &amp; endpoints<br/>connection lifecycle<br/>[state.cpp]"]
  node_grpc_transport["gRPC connections<br/>transport"]
  node_request_pipeline["Request &amp; status pipeline<br/>RPC execution<br/>[make.cpp]"]
  node_retry_executor["Retry &amp; async executor<br/>resilience/concurrency<br/>[executor_impl.cpp]"]
end

subgraph group_apis["Public APIs"]
  node_public_api["Public SDK APIs<br/>C++ headers<br/>[driver.h]"]
  node_table_query["Table &amp; query clients<br/>data API<br/>[table_client.cpp]"]
  node_values_results["Value &amp; result mapping<br/>data boundary<br/>[value.h]"]
  node_topic["Topic client<br/>streaming API<br/>[read_session.cpp]"]
  node_control_plane["Control-plane clients<br/>service APIs<br/>[scheme.cpp]"]
end

subgraph group_extensions["Extensions"]
  node_credentials["Credential providers<br/>security extension<br/>[credentials.cpp]"]
  node_observability["Observability core<br/>metrics and tracing<br/>[metrics.cpp]"]
  node_otel_plugins["OpenTelemetry plugins<br/>optional plugin<br/>[metrics.cpp]"]
end

node_consumer(("C++ applications<br/>consumer"))
node_ydb[("YDB service<br/>external database")]
node_iam_oauth(("IAM / OAuth endpoints<br/>external identity"))

node_consumer -->|"uses"| node_public_api
node_examples -->|"demonstrates"| node_public_api
node_cmake -->|"runs"| node_grpc_generation
node_proto_contracts -->|"generates from"| node_grpc_generation
node_grpc_generation -->|"compiled into SDK"| node_cmake
node_cmake -->|"produces"| node_packaging
node_public_api -->|"initializes"| node_driver
node_public_api -->|"exposes"| node_table_query
node_public_api -->|"exposes"| node_topic
node_driver -->|"backs clients"| node_client_common
node_driver -->|"owns"| node_driver_state
node_driver_state -->|"authenticates with"| node_credentials
node_driver_state -->|"selects channels"| node_grpc_transport
node_client_common -->|"executes calls"| node_request_pipeline
node_table_query -->|"maps payloads through"| node_values_results
node_table_query -->|"uses"| node_client_common
node_topic -->|"uses"| node_client_common
node_control_plane -->|"uses"| node_client_common
node_request_pipeline -->|"schedules and retries"| node_retry_executor
node_request_pipeline -->|"calls generated stubs"| node_grpc_transport
node_grpc_transport -->|"gRPC/TLS"| node_ydb
node_credentials -.->|"obtains tokens"| node_iam_oauth
node_observability -.->|"optional adapters"| node_otel_plugins
node_driver -.->|"emits telemetry"| node_observability

click node_public_api "https://github.com/ydb-platform/ydb-cpp-sdk/blob/main/include/ydb-cpp-sdk/client/driver/driver.h"
click node_examples "https://github.com/ydb-platform/ydb-cpp-sdk/blob/main/examples/basic_example/main.cpp"
click node_cmake "https://github.com/ydb-platform/ydb-cpp-sdk/blob/main/CMakeLists.txt"
click node_proto_contracts "https://github.com/ydb-platform/ydb-cpp-sdk/blob/main/src/api/protos/ydb_table.proto"
click node_grpc_generation "https://github.com/ydb-platform/ydb-cpp-sdk/blob/main/cmake/protobuf.cmake"
click node_packaging "https://github.com/ydb-platform/ydb-cpp-sdk/blob/main/cmake/PackSDK.cmake"
click node_driver "https://github.com/ydb-platform/ydb-cpp-sdk/blob/main/src/client/driver/driver.cpp"
click node_client_common "https://github.com/ydb-platform/ydb-cpp-sdk/blob/main/src/client/common_client/impl/client.cpp"
click node_driver_state "https://github.com/ydb-platform/ydb-cpp-sdk/blob/main/src/client/impl/internal/db_driver_state/state.cpp"
click node_grpc_transport "https://github.com/ydb-platform/ydb-cpp-sdk/blob/main/src/client/impl/internal/grpc_connections/grpc_connections.cpp"
click node_request_pipeline "https://github.com/ydb-platform/ydb-cpp-sdk/blob/main/src/client/impl/internal/make_request/make.cpp"
click node_retry_executor "https://github.com/ydb-platform/ydb-cpp-sdk/blob/main/src/client/impl/executor/executor_impl.cpp"
click node_table_query "https://github.com/ydb-platform/ydb-cpp-sdk/blob/main/src/client/table/impl/table_client.cpp"
click node_values_results "https://github.com/ydb-platform/ydb-cpp-sdk/blob/main/include/ydb-cpp-sdk/client/value/value.h"
click node_topic "https://github.com/ydb-platform/ydb-cpp-sdk/blob/main/src/client/topic/impl/read_session.cpp"
click node_control_plane "https://github.com/ydb-platform/ydb-cpp-sdk/blob/main/src/client/scheme/scheme.cpp"
click node_credentials "https://github.com/ydb-platform/ydb-cpp-sdk/blob/main/src/client/types/credentials/credentials.cpp"
click node_observability "https://github.com/ydb-platform/ydb-cpp-sdk/blob/main/src/client/impl/observability/metrics.cpp"
click node_otel_plugins "https://github.com/ydb-platform/ydb-cpp-sdk/blob/main/plugins/metrics/otel/metrics.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_examples,node_cmake,node_proto_contracts,node_grpc_generation,node_packaging toneBlue
class node_driver,node_client_common,node_driver_state,node_grpc_transport,node_request_pipeline,node_retry_executor toneAmber
class node_public_api,node_table_query,node_values_results,node_topic,node_control_plane toneMint
class node_credentials,node_observability,node_otel_plugins toneRose
class node_consumer,node_ydb,node_iam_oauth toneNeutral
```

## Components

### Build & distribution

- [Runnable examples](https://github.com/ydb-platform/ydb-cpp-sdk/blob/main/examples/basic_example/main.cpp): C++ executable · `examples/basic_example/main.cpp`
- [CMake composition](https://github.com/ydb-platform/ydb-cpp-sdk/blob/main/CMakeLists.txt): build system · Builds libraries, generated code, examples, and install artifacts. · `CMakeLists.txt`
- [YDB protocol contracts](https://github.com/ydb-platform/ydb-cpp-sdk/blob/main/src/api/protos/ydb_table.proto): protobuf + gRPC · `src/api/protos/ydb_table.proto`
- [Generated RPC code](https://github.com/ydb-platform/ydb-cpp-sdk/blob/main/cmake/protobuf.cmake): code generation · `cmake/protobuf.cmake`
- [Debian SDK packages](https://github.com/ydb-platform/ydb-cpp-sdk/blob/main/cmake/PackSDK.cmake): distribution · Packages core SDK and optional IAM and OpenTelemetry plugins. · `cmake/PackSDK.cmake`

### SDK runtime core

- [TDriver](https://github.com/ydb-platform/ydb-cpp-sdk/blob/main/src/client/driver/driver.cpp): runtime root · Configures credentials, endpoint, database, and service clients. · `src/client/driver/driver.cpp`
- [Common client layer](https://github.com/ydb-platform/ydb-cpp-sdk/blob/main/src/client/common_client/impl/client.cpp): client abstraction · `src/client/common_client/impl/client.cpp`
- [Driver state & endpoints](https://github.com/ydb-platform/ydb-cpp-sdk/blob/main/src/client/impl/internal/db_driver_state/state.cpp): connection lifecycle · Owns authentication, discovery, endpoint selection, and lifecycle. · `src/client/impl/internal/db_driver_state/state.cpp`
- [gRPC connections](https://github.com/ydb-platform/ydb-cpp-sdk/blob/main/src/client/impl/internal/grpc_connections/grpc_connections.cpp): transport · `src/client/impl/internal/grpc_connections/grpc_connections.cpp`
- [Request & status pipeline](https://github.com/ydb-platform/ydb-cpp-sdk/blob/main/src/client/impl/internal/make_request/make.cpp): RPC execution · Constructs requests, invokes stubs, and converts status. · `src/client/impl/internal/make_request/make.cpp`
- [Retry & async executor](https://github.com/ydb-platform/ydb-cpp-sdk/blob/main/src/client/impl/executor/executor_impl.cpp): resilience/concurrency · Central retry policy, futures, and background work. · `src/client/impl/executor/executor_impl.cpp`

### Public APIs

- [Public SDK APIs](https://github.com/ydb-platform/ydb-cpp-sdk/blob/main/include/ydb-cpp-sdk/client/driver/driver.h): C++ headers · Driver, table, topic, value, and result interfaces. · `include/ydb-cpp-sdk/client/driver/driver.h`
- [Table & query clients](https://github.com/ydb-platform/ydb-cpp-sdk/blob/main/src/client/table/impl/table_client.cpp): data API · Sessions, transactions, request migration, and query execution. · `src/client/table/impl/table_client.cpp`
- [Value & result mapping](https://github.com/ydb-platform/ydb-cpp-sdk/blob/main/include/ydb-cpp-sdk/client/value/value.h): data boundary · Maps C++ values and result rows to protobuf payloads. · `include/ydb-cpp-sdk/client/value/value.h`
- [Topic client](https://github.com/ydb-platform/ydb-cpp-sdk/blob/main/src/client/topic/impl/read_session.cpp): streaming API · Async read/write sessions, producers, offsets, commits, and transactions. · `src/client/topic/impl/read_session.cpp`
- [Control-plane clients](https://github.com/ydb-platform/ydb-cpp-sdk/blob/main/src/client/scheme/scheme.cpp): service APIs · Scheme, coordination, discovery, import/export, monitoring, secrets, and rate limits. · `src/client/scheme/scheme.cpp`

### Extensions

- [Credential providers](https://github.com/ydb-platform/ydb-cpp-sdk/blob/main/src/client/types/credentials/credentials.cpp): security extension · Standard, login, IAM, OAuth2, and JWT token exchange providers. · `src/client/types/credentials/credentials.cpp`
- [Observability core](https://github.com/ydb-platform/ydb-cpp-sdk/blob/main/src/client/impl/observability/metrics.cpp): metrics and tracing · `src/client/impl/observability/metrics.cpp`
- [OpenTelemetry plugins](https://github.com/ydb-platform/ydb-cpp-sdk/blob/main/plugins/metrics/otel/metrics.cpp): optional plugin · `plugins/metrics/otel/metrics.cpp`

### Other components

- **C++ applications**: consumer · Consume installed SDK headers and CMake targets.
- **YDB service**: external database · Primary RPC endpoint for SDK clients.
- **IAM / OAuth endpoints**: external identity

## Connections

- C++ applications → Public SDK APIs: uses
- Runnable examples → Public SDK APIs: demonstrates
- CMake composition → Generated RPC code: runs
- YDB protocol contracts → Generated RPC code: generates from
- Generated RPC code → CMake composition: compiled into SDK
- CMake composition → Debian SDK packages: produces
- Public SDK APIs → TDriver: initializes
- Public SDK APIs → Table & query clients: exposes
- Public SDK APIs → Topic client: exposes
- TDriver → Common client layer: backs clients
- TDriver → Driver state & endpoints: owns
- Driver state & endpoints → Credential providers: authenticates with
- Driver state & endpoints → gRPC connections: selects channels
- Common client layer → Request & status pipeline: executes calls
- Table & query clients → Value & result mapping: maps payloads through
- Table & query clients → Common client layer: uses
- Topic client → Common client layer: uses
- Control-plane clients → Common client layer: uses
- Request & status pipeline → Retry & async executor: schedules and retries
- Request & status pipeline → gRPC connections: calls generated stubs
- gRPC connections → YDB service: gRPC/TLS
- Credential providers → IAM / OAuth endpoints: obtains tokens
- Observability core → OpenTelemetry plugins: optional adapters
- TDriver → Observability core: emits telemetry