# scylladb/alternator-client-rust architecture

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

- Interactive diagram: https://gitdiagram.com/scylladb/alternator-client-rust
- Repository: https://github.com/scylladb/alternator-client-rust

## Overview

This crate wraps the AWS DynamoDB Rust SDK to let applications issue DynamoDB-style operations against ScyllaDB Alternator, with client-side node discovery and request routing. The main path builds an Alternator client, discovers live nodes from configured seeds and routing scopes, selects a target per operation, then sends SDK traffic with optional affinity and HTTP optimizations. The README also documents authentication modes, fallback scopes, compression, and header handling. Unsampled modules are represented only where the tree and README establish their role; uncertain internal wiring is omitted.

Main entry points: [`src/interceptors.rs`](https://github.com/scylladb/alternator-client-rust/blob/main/src/interceptors.rs) (SDK Interceptors), [`src/client.rs`](https://github.com/scylladb/alternator-client-rust/blob/main/src/client.rs) (Alternator Client), [`src/config.rs`](https://github.com/scylladb/alternator-client-rust/blob/main/src/config.rs) (Client Config), [`src/live_nodes.rs`](https://github.com/scylladb/alternator-client-rust/blob/main/src/live_nodes.rs) (Node Discovery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client API"]
  node_config["Client Config<br/>[config.rs]"]
  node_client_api["Alternator Client<br/>[client.rs]"]
  node_customize["Operation Customization<br/>[customize.rs]"]
end

subgraph group_routing["Discovery Routing"]
  node_scope["Routing Scopes<br/>[routing_scope.rs]"]
  node_discovery["Node Discovery<br/>[live_nodes.rs]"]
  node_live_nodes[("Live Node State<br/>[live_nodes.rs]")]
  node_plan["Query Planning<br/>[query_plan.rs]"]
end

subgraph group_affinity["Key Affinity"]
  node_key_config["Affinity Config<br/>[affinity_config.rs]"]
  node_classifier["Operation Classifier<br/>[classifier.rs]"]
  node_resolver["Partition Key Resolver<br/>[resolver.rs]"]
  node_hasher["Key Hasher<br/>[hasher.rs]"]
  node_hash_impl["MurmurHash3<br/>[murmurhash3.rs]"]
  node_go_rand["Go-compatible RNG<br/>[go_rand.rs]"]
end

subgraph group_http["HTTP Features"]
  node_interceptors["SDK Interceptors<br/>[interceptors.rs]"]
  node_compression["Request Compression<br/>[compression.rs]"]
  node_decompression["Response Decompression<br/>[decompression.rs]"]
  node_headers["Header Optimization"]
  node_user_agent["User Agent<br/>[user_agent.rs]"]
end

node_application(("Application"))
node_alternator(("Alternator Cluster"))
node_sdk["AWS DynamoDB SDK"]

node_application -->|"configures"| node_config
node_config -->|"builds"| node_client_api
node_application -->|"uses"| node_client_api
node_client_api -->|"wraps"| node_sdk
node_client_api -->|"initializes"| node_discovery
node_config -->|"sets scope"| node_scope
node_discovery -->|"queries by"| node_scope
node_discovery -->|"fetches localnodes"| node_alternator
node_discovery -->|"updates"| node_live_nodes
node_client_api -->|"plans requests"| node_plan
node_plan -->|"reads nodes"| node_live_nodes
node_plan -->|"selects affinity"| node_go_rand
node_client_api -->|"dispatches operations"| node_sdk
node_sdk -->|"sends requests"| node_alternator
node_client_api -->|"configures"| node_interceptors
node_interceptors -->|"compresses request"| node_compression
node_interceptors -->|"decodes response"| node_decompression
node_interceptors -->|"strips headers"| node_headers
node_interceptors -->|"sets identity"| node_user_agent
node_customize -->|"overrides settings"| node_interceptors
node_config -->|"enables affinity"| node_key_config
node_interceptors -->|"classifies inputs"| node_classifier
node_classifier -->|"hashes keys"| node_hasher
node_hasher -->|"computes hash"| node_hash_impl
node_interceptors -->|"triggers discovery"| node_resolver
node_resolver -->|"discovers key schema"| node_sdk
node_resolver -->|"uses key hashing"| node_hasher
node_resolver -->|"builds affinity plan"| node_plan

click node_config "https://github.com/scylladb/alternator-client-rust/blob/main/src/config.rs"
click node_client_api "https://github.com/scylladb/alternator-client-rust/blob/main/src/client.rs"
click node_customize "https://github.com/scylladb/alternator-client-rust/blob/main/src/customize.rs"
click node_scope "https://github.com/scylladb/alternator-client-rust/blob/main/src/routing_scope.rs"
click node_discovery "https://github.com/scylladb/alternator-client-rust/blob/main/src/live_nodes.rs"
click node_live_nodes "https://github.com/scylladb/alternator-client-rust/blob/main/src/live_nodes.rs"
click node_plan "https://github.com/scylladb/alternator-client-rust/blob/main/src/query_plan.rs"
click node_key_config "https://github.com/scylladb/alternator-client-rust/blob/main/src/keyrouting/affinity_config.rs"
click node_classifier "https://github.com/scylladb/alternator-client-rust/blob/main/src/keyrouting/classifier.rs"
click node_resolver "https://github.com/scylladb/alternator-client-rust/blob/main/src/keyrouting/resolver.rs"
click node_hasher "https://github.com/scylladb/alternator-client-rust/blob/main/src/keyrouting/hasher.rs"
click node_hash_impl "https://github.com/scylladb/alternator-client-rust/blob/main/src/keyrouting/murmurhash3.rs"
click node_go_rand "https://github.com/scylladb/alternator-client-rust/blob/main/src/keyrouting/go_rand.rs"
click node_interceptors "https://github.com/scylladb/alternator-client-rust/blob/main/src/interceptors.rs"
click node_compression "https://github.com/scylladb/alternator-client-rust/blob/main/src/compression.rs"
click node_decompression "https://github.com/scylladb/alternator-client-rust/blob/main/src/decompression.rs"
click node_headers "https://github.com/scylladb/alternator-client-rust/blob/main/src/optimize_headers.rs"
click node_user_agent "https://github.com/scylladb/alternator-client-rust/blob/main/src/user_agent.rs"

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_config,node_client_api,node_customize toneBlue
class node_scope,node_discovery,node_live_nodes,node_plan toneAmber
class node_key_config,node_classifier,node_resolver,node_hasher,node_hash_impl,node_go_rand toneMint
class node_interceptors,node_compression,node_decompression,node_headers,node_user_agent toneRose
class node_application,node_alternator,node_sdk toneIndigo
```

## Components

### Client API

- [Client Config](https://github.com/scylladb/alternator-client-rust/blob/main/src/config.rs): `src/config.rs`
- [Alternator Client](https://github.com/scylladb/alternator-client-rust/blob/main/src/client.rs): `src/client.rs`
- [Operation Customization](https://github.com/scylladb/alternator-client-rust/blob/main/src/customize.rs): `src/customize.rs`

### Discovery Routing

- [Routing Scopes](https://github.com/scylladb/alternator-client-rust/blob/main/src/routing_scope.rs): `src/routing_scope.rs`
- [Node Discovery](https://github.com/scylladb/alternator-client-rust/blob/main/src/live_nodes.rs): `src/live_nodes.rs`
- [Live Node State](https://github.com/scylladb/alternator-client-rust/blob/main/src/live_nodes.rs): `src/live_nodes.rs`
- [Query Planning](https://github.com/scylladb/alternator-client-rust/blob/main/src/query_plan.rs): `src/query_plan.rs`

### Key Affinity

- [Affinity Config](https://github.com/scylladb/alternator-client-rust/blob/main/src/keyrouting/affinity_config.rs): `src/keyrouting/affinity_config.rs`
- [Operation Classifier](https://github.com/scylladb/alternator-client-rust/blob/main/src/keyrouting/classifier.rs): `src/keyrouting/classifier.rs`
- [Partition Key Resolver](https://github.com/scylladb/alternator-client-rust/blob/main/src/keyrouting/resolver.rs): `src/keyrouting/resolver.rs`
- [Key Hasher](https://github.com/scylladb/alternator-client-rust/blob/main/src/keyrouting/hasher.rs): `src/keyrouting/hasher.rs`
- [MurmurHash3](https://github.com/scylladb/alternator-client-rust/blob/main/src/keyrouting/murmurhash3.rs): `src/keyrouting/murmurhash3.rs`
- [Go-compatible RNG](https://github.com/scylladb/alternator-client-rust/blob/main/src/keyrouting/go_rand.rs): `src/keyrouting/go_rand.rs`

### HTTP Features

- [SDK Interceptors](https://github.com/scylladb/alternator-client-rust/blob/main/src/interceptors.rs): `src/interceptors.rs`
- [Request Compression](https://github.com/scylladb/alternator-client-rust/blob/main/src/compression.rs): `src/compression.rs`
- [Response Decompression](https://github.com/scylladb/alternator-client-rust/blob/main/src/decompression.rs): `src/decompression.rs`
- [Header Optimization](https://github.com/scylladb/alternator-client-rust/blob/main/src/optimize_headers.rs): `src/optimize_headers.rs`
- [User Agent](https://github.com/scylladb/alternator-client-rust/blob/main/src/user_agent.rs): `src/user_agent.rs`

### Other components

- **Application**
- **Alternator Cluster**
- **AWS DynamoDB SDK**

## Connections

- Application → Client Config: configures
- Client Config → Alternator Client: builds
- Application → Alternator Client: uses
- Alternator Client → AWS DynamoDB SDK: wraps
- Alternator Client → Node Discovery: initializes
- Client Config → Routing Scopes: sets scope
- Node Discovery → Routing Scopes: queries by
- Node Discovery → Alternator Cluster: fetches localnodes
- Node Discovery → Live Node State: updates
- Alternator Client → Query Planning: plans requests
- Query Planning → Live Node State: reads nodes
- Query Planning → Go-compatible RNG: selects affinity
- Alternator Client → AWS DynamoDB SDK: dispatches operations
- AWS DynamoDB SDK → Alternator Cluster: sends requests
- Alternator Client → SDK Interceptors: configures
- SDK Interceptors → Request Compression: compresses request
- SDK Interceptors → Response Decompression: decodes response
- SDK Interceptors → Header Optimization: strips headers
- SDK Interceptors → User Agent: sets identity
- Operation Customization → SDK Interceptors: overrides settings
- Client Config → Affinity Config: enables affinity
- SDK Interceptors → Operation Classifier: classifies inputs
- Operation Classifier → Key Hasher: hashes keys
- Key Hasher → MurmurHash3: computes hash
- SDK Interceptors → Partition Key Resolver: triggers discovery
- Partition Key Resolver → AWS DynamoDB SDK: discovers key schema
- Partition Key Resolver → Key Hasher: uses key hashing
- Partition Key Resolver → Query Planning: builds affinity plan