# couchbase/couchbase-net-client architecture

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

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

## Overview

##### Project type and purpose
- This is an open-source .NET client SDK for Couchbase Server (and Protostellar).
- Purpose: provide a rich, extensible API surface for accessing Couchbase services (Key-Value, Queries, Search, Analytics, Transactions) from .NET apps, with pluggable DI, telemetry, retry, circuit-breaker, and code-generation support.

##### File structure
- Top-level “src” contains multiple .NET projects, each one a component/extension:
– Couchbase (core client)
– Couchbase.Extensions.DependencyInjection (DI integration)
– Couchbase.Extensions.OpenTelemetry (metrics/tracing)
– Couchbase.Transactions (distributed-transaction support)
– Couchbase.Stellar.CodeGen (gRPC proxy generator)
– Couchbase.Stellar.* (runtime Protostellar client)
- “tests” holds unit, integration, load, combination test suites mapped one-to-one with src projects.
- “examples” demonstrates basic usage.
- “doc” contains DocFX site setup.
- Solution files (.sln) orchestrate build of all projects.

##### README for additional insights
- Confirms this is the official Couchbase .NET SDK.
- Points to online docs, explains how to run tests, how to generate gRPC stubs (Protostellar).

##### Main components and their interactions
a. Core Client (src/Couchbase)
– Responsible for cluster bootstrap, node management, connection pools, IO/operations, serialization, retry, circuit breakers, rate-limiting, and service-specific clients (KV, Query, Search, Analytics, Views, Management, Eventing).
b. Dependency‐Injection Extensions
– Plugs Core Client into Microsoft.Extensions.DependencyInjection (IServiceCollection) via builder patterns.
c. OpenTelemetry Extensions
– Hooks into Core Client’s diagnostics to emit metrics and traces to OpenTelemetry.
d. Transactions
– Layered on Core Client to coordinate multi-operation, ACID-style transactions; includes data models, repositories for ATR (Active Transaction Record), cleanup, error handling, configurable retry.
e. Stellar (Protostellar)
– gRPC code generation + runtime adapter that lets the SDK talk to Protostellar (a lightweight gRPC‐based gateway).
f. External Couchbase Server / Protostellar
– Actual servers; Core Client uses binary memcached protocol via I/O layer; Stellar uses gRPC.

##### Architectural patterns and design principles
- Modular design: each area in its own project/namespace.
- Dependency injection & builder pattern to configure cluster, buckets, telemetry, and transactions.
- Factory and proxy generation (e.g., proxy builders for named bucket contexts).
- Resilience patterns: retry orchestration, circuit breakers, backoff calculators.
- Separation of concerns: I/O, serialization, diagnostics, and service logic are distinct layers.
- Code generation for gRPC stubs to avoid handwritten client boilerplate.

- Use clear labels on each module.
- Related namespaces or projects in containers (e.g., a “Transactions” container grouping config, dataaccess, cleanup, error).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Application Entry
    App["Application"]:::app

    %% External Systems
    subgraph "External Systems"
        CouchbaseServer["Couchbase Server\n(Memcached Binary)"]:::external
        Protostellar["Protostellar gRPC Gateway"]:::external
    end

    %% SDK Core
    subgraph "SDK Core"
        Cluster["ClusterContext & Connection Pool"]:::internal
        IO["I/O Operations"]:::internal
        Serial["Serialization / Transcoding"]:::internal
        Retry["Retry & Circuit Breakers"]:::internal
        Services["Service Clients\n(KV, Query, Search, Analytics, Views, Management, Eventing)"]:::internal
    end

    %% Extensions
    subgraph "Extensions"
        DI["DI Extensions\n(IServiceCollection Integration, Proxy Builders)"]:::extension
        Telemetry["OpenTelemetry Extensions\n(Metrics & Tracing Hooks)"]:::extension
    end

    %% Transactions
    subgraph "Transactions Module"
        Txn["Transactions Module\n(ATR, DataAccess, Cleanup, Config, ErrorHandling)"]:::extension
    end

    %% Stellar
    subgraph "Stellar"
        CodeGen["Stellar CodeGen\n(gRPC Stub Generator)"]:::extension
        Runtime["Stellar Runtime\n(Protostellar gRPC Adapter & Clients)"]:::extension
    end

    %% Examples & Documentation
    subgraph "Examples & Documentation"
        Examples["Examples\n(SDK Usage Samples)"]:::example
        Docs["Documentation Site\n(DocFX)"]:::doc
    end

    %% Tests
    subgraph "Tests"
        CoreTests["Core Unit & Integration Tests"]:::test
        DITests["DI Extensions Unit Tests"]:::test
        TelemetryTestsUnit["OpenTelemetry Unit Tests"]:::test
        TelemetryTestsInt["OpenTelemetry Integration Tests"]:::test
        TxnTestsUnit["Transactions Unit Tests"]:::test
        TxnTestsInt["Transactions Integration Tests"]:::test
        StellarTests["Stellar Combination Tests"]:::test
        LoadTests["Load & Concurrency Tests"]:::test
        ConcurrencyTests["Concurrency Tests"]:::test
    end

    %% Data Flows
    App -->|"configures"| DI
    DI -->|"builds Cluster"| Cluster
    App -->|"invokes"| Txn
    Txn -->|"calls KV/Query Clients"| Services
    App -->|"calls Stellar API"| Runtime
    Runtime -->|"gRPC"| Protostellar
    Protostellar -->|"forwards to"| CouchbaseServer
    Services -->|"Memcached Binary"| CouchbaseServer
    Cluster --> IO
    IO --> Serial
    Serial --> Retry
    Retry --> Services
    Retry -->|"emits diagnostics"| Telemetry
    IO -->|"emits diagnostics"| Telemetry
    App --> Examples
    Docs -.-> App

    %% Tests flows
    CoreTests -.-> Cluster
    CoreTests -.-> Services
    LoadTests -.-> IO
    ConcurrencyTests -.-> IO
    DITests -.-> DI
    TelemetryTestsUnit -.-> Telemetry
    TelemetryTestsInt -.-> Telemetry
    TxnTestsUnit -.-> Txn
    TxnTestsInt -.-> Txn
    StellarTests -.-> Runtime

    %% Click Events
    click Cluster "https://github.com/couchbase/couchbase-net-client/tree/master/src/Couchbase"
    click DI "https://github.com/couchbase/couchbase-net-client/blob/master/src/Couchbase.Extensions.DependencyInjection"
    click Telemetry "https://github.com/couchbase/couchbase-net-client/blob/master/src/Couchbase.Extensions.OpenTelemetry"
    click Txn "https://github.com/couchbase/couchbase-net-client/blob/master/src/Couchbase.Transactions"
    click CodeGen "https://github.com/couchbase/couchbase-net-client/blob/master/src/Couchbase.Stellar.CodeGen"
    click Runtime "https://github.com/couchbase/couchbase-net-client/blob/master/src/Couchbase.Stellar"
    click Examples "https://github.com/couchbase/couchbase-net-client/blob/master/examples/Couchbase.SDK3.0.Examples"
    click Docs "https://github.com/couchbase/couchbase-net-client/tree/master/doc/CouchbaseNetClientDocs"
    click CoreTests "https://github.com/couchbase/couchbase-net-client/blob/master/tests/Couchbase.UnitTests"
    click CoreTests "https://github.com/couchbase/couchbase-net-client/blob/master/tests/Couchbase.IntegrationTests"
    click DITests "https://github.com/couchbase/couchbase-net-client/blob/master/tests/Couchbase.Extensions.DependencyInjection.UnitTests"
    click TelemetryTestsUnit "https://github.com/couchbase/couchbase-net-client/blob/master/tests/Couchbase.Extensions.OpenTelemetry.UnitTests"
    click TelemetryTestsInt "https://github.com/couchbase/couchbase-net-client/blob/master/tests/Couchbase.Extensions.OpenTelemetry.IntegrationTests"
    click TxnTestsUnit "https://github.com/couchbase/couchbase-net-client/blob/master/tests/Couchbase.Transactions.Tests.UnitTests"
    click TxnTestsInt "https://github.com/couchbase/couchbase-net-client/blob/master/tests/Couchbase.Transactions.Tests.IntegrationTests"
    click StellarTests "https://github.com/couchbase/couchbase-net-client/blob/master/tests/Couchbase.Stellar.CombinationTests"
    click LoadTests "https://github.com/couchbase/couchbase-net-client/blob/master/tests/Couchbase.LoadTests"
    click ConcurrencyTests "https://github.com/couchbase/couchbase-net-client/blob/master/tests/Couchbase.ConcurrencyTests"

    %% Styles
    classDef app fill:#f9f,stroke:#333,stroke-width:1px
    classDef internal fill:#bbf,stroke:#333,stroke-width:1px
    classDef extension fill:#bfb,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef external fill:#fbb,stroke:#333,stroke-width:1px,shape:cylinder
    classDef example fill:#ffeb99,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef doc fill:#eee,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2
    classDef test fill:#ddd,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2
```
