# couchbase/spymemcached architecture

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

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

## Overview

Spymemcached is a Java client library for issuing asynchronous and synchronous cache operations against Memcached-compatible servers. Applications call the client API; it constructs operations, routes them through a managed connection to server nodes, and exposes completion/results through futures and callbacks. The code also supports serialization, authentication, TAP streaming, and metrics. The README focuses on building and testing and does not document product behavior, so the map relies on the source index and sampled excerpts; unsampled protocol and configuration links are omitted where not evidenced.

Main entry points: [`src/main/java/net/spy/memcached/MemcachedConnection.java`](https://github.com/couchbase/spymemcached/blob/master/src/main/java/net/spy/memcached/MemcachedConnection.java) (Connection Manager), [`src/main/java/net/spy/memcached/MemcachedClient.java`](https://github.com/couchbase/spymemcached/blob/master/src/main/java/net/spy/memcached/MemcachedClient.java) (Memcached Client), [`src/main/java/net/spy/memcached/ops`](https://github.com/couchbase/spymemcached/tree/master/src/main/java/net/spy/memcached/ops) (Cache Operations), [`src/main/java/net/spy/memcached/tapmessage/ResponseMessage.java`](https://github.com/couchbase/spymemcached/blob/master/src/main/java/net/spy/memcached/tapmessage/ResponseMessage.java) (TAP Messages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Client API"]
  node_client["Memcached Client"]
  node_client_interface["Client Interface"]
  node_operation_factory["Operation Factory"]
  node_operation_types["Cache Operations"]
  node_futures["Operation Futures"]
end

subgraph group_runtime["Connection Runtime"]
  node_connection["Connection Manager"]
  node_node_api["Node Queue API<br/>[MemcachedNode.java]"]
  node_tcp_node["TCP Node Runtime"]
  node_locator["Node Locators<br/>[NodeLocator.java]"]
end

subgraph group_wire["Protocols and TAP"]
  node_protocol_base["Protocol Operations"]
  node_ascii["ASCII Protocol"]
  node_binary["Binary Protocol"]
  node_tap_client["TAP Client<br/>[TapClient.java]"]
  node_tap_messages["TAP Messages"]
end

subgraph group_support["Data and Support"]
  node_transcoder["Transcoders<br/>[Transcoder.java]"]
  node_cached_data["Cached Data<br/>[CachedData.java]"]
  node_auth["SASL Authentication<br/>[AuthThread.java]"]
  node_auth_config["Auth Descriptor"]
  node_metrics["Metrics Collector"]
end

node_application(("Application"))
node_memcached[("Memcached Servers")]

node_application -->|"calls"| node_client_interface
node_client -->|"creates operations"| node_operation_factory
node_client -->|"enqueues operations"| node_connection
node_client -->|"returns futures"| node_futures
node_client -->|"decodes values"| node_transcoder
node_client -->|"wraps response data"| node_cached_data
node_operation_factory -->|"creates"| node_operation_types
node_connection -->|"manages nodes"| node_node_api
node_connection -->|"initializes and routes"| node_operation_types
node_tcp_node -->|"implements"| node_node_api
node_connection -.->|"selects nodes"| node_locator
node_tcp_node -.->|"communicates"| node_memcached
node_protocol_base -.->|"implements"| node_operation_types
node_ascii -.->|"specializes"| node_protocol_base
node_binary -.->|"specializes"| node_protocol_base
node_tap_client -->|"submits TAP operations"| node_operation_types
node_tap_client -->|"uses messages"| node_tap_messages
node_tap_messages -->|"represents data"| node_cached_data
node_tap_messages -->|"uses serialization"| node_transcoder
node_auth -->|"uses credentials"| node_auth_config
node_auth -->|"coordinates authentication"| node_connection
node_connection -.->|"records metrics"| node_metrics

click node_client "https://github.com/couchbase/spymemcached/blob/master/src/main/java/net/spy/memcached/MemcachedClient.java"
click node_client_interface "https://github.com/couchbase/spymemcached/blob/master/src/main/java/net/spy/memcached/MemcachedClientIF.java"
click node_operation_factory "https://github.com/couchbase/spymemcached/blob/master/src/main/java/net/spy/memcached/OperationFactory.java"
click node_operation_types "https://github.com/couchbase/spymemcached/tree/master/src/main/java/net/spy/memcached/ops"
click node_futures "https://github.com/couchbase/spymemcached/blob/master/src/main/java/net/spy/memcached/internal/OperationFuture.java"
click node_connection "https://github.com/couchbase/spymemcached/blob/master/src/main/java/net/spy/memcached/MemcachedConnection.java"
click node_node_api "https://github.com/couchbase/spymemcached/blob/master/src/main/java/net/spy/memcached/MemcachedNode.java"
click node_tcp_node "https://github.com/couchbase/spymemcached/blob/master/src/main/java/net/spy/memcached/protocol/TCPMemcachedNodeImpl.java"
click node_locator "https://github.com/couchbase/spymemcached/blob/master/src/main/java/net/spy/memcached/NodeLocator.java"
click node_protocol_base "https://github.com/couchbase/spymemcached/blob/master/src/main/java/net/spy/memcached/protocol/BaseOperationImpl.java"
click node_ascii "https://github.com/couchbase/spymemcached/blob/master/src/main/java/net/spy/memcached/protocol/ascii/AsciiOperationFactory.java"
click node_binary "https://github.com/couchbase/spymemcached/blob/master/src/main/java/net/spy/memcached/protocol/binary/BinaryOperationFactory.java"
click node_tap_client "https://github.com/couchbase/spymemcached/blob/master/src/main/java/net/spy/memcached/TapClient.java"
click node_tap_messages "https://github.com/couchbase/spymemcached/blob/master/src/main/java/net/spy/memcached/tapmessage/ResponseMessage.java"
click node_transcoder "https://github.com/couchbase/spymemcached/blob/master/src/main/java/net/spy/memcached/transcoders/Transcoder.java"
click node_cached_data "https://github.com/couchbase/spymemcached/blob/master/src/main/java/net/spy/memcached/CachedData.java"
click node_auth "https://github.com/couchbase/spymemcached/blob/master/src/main/java/net/spy/memcached/auth/AuthThread.java"
click node_auth_config "https://github.com/couchbase/spymemcached/blob/master/src/main/java/net/spy/memcached/auth/AuthDescriptor.java"
click node_metrics "https://github.com/couchbase/spymemcached/blob/master/src/main/java/net/spy/memcached/metrics/DefaultMetricCollector.java"

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_client,node_client_interface,node_operation_factory,node_operation_types,node_futures toneBlue
class node_connection,node_node_api,node_tcp_node,node_locator,node_memcached toneAmber
class node_protocol_base,node_ascii,node_binary,node_tap_client,node_tap_messages toneMint
class node_transcoder,node_cached_data,node_auth,node_auth_config,node_metrics toneRose
class node_application toneIndigo
```

## Components

### Client API

- [Memcached Client](https://github.com/couchbase/spymemcached/blob/master/src/main/java/net/spy/memcached/MemcachedClient.java): `src/main/java/net/spy/memcached/MemcachedClient.java`
- [Client Interface](https://github.com/couchbase/spymemcached/blob/master/src/main/java/net/spy/memcached/MemcachedClientIF.java): `src/main/java/net/spy/memcached/MemcachedClientIF.java`
- [Operation Factory](https://github.com/couchbase/spymemcached/blob/master/src/main/java/net/spy/memcached/OperationFactory.java): `src/main/java/net/spy/memcached/OperationFactory.java`
- [Cache Operations](https://github.com/couchbase/spymemcached/tree/master/src/main/java/net/spy/memcached/ops): `src/main/java/net/spy/memcached/ops`
- [Operation Futures](https://github.com/couchbase/spymemcached/blob/master/src/main/java/net/spy/memcached/internal/OperationFuture.java): `src/main/java/net/spy/memcached/internal/OperationFuture.java`

### Connection Runtime

- [Connection Manager](https://github.com/couchbase/spymemcached/blob/master/src/main/java/net/spy/memcached/MemcachedConnection.java): `src/main/java/net/spy/memcached/MemcachedConnection.java`
- [Node Queue API](https://github.com/couchbase/spymemcached/blob/master/src/main/java/net/spy/memcached/MemcachedNode.java): `src/main/java/net/spy/memcached/MemcachedNode.java`
- [TCP Node Runtime](https://github.com/couchbase/spymemcached/blob/master/src/main/java/net/spy/memcached/protocol/TCPMemcachedNodeImpl.java): `src/main/java/net/spy/memcached/protocol/TCPMemcachedNodeImpl.java`
- [Node Locators](https://github.com/couchbase/spymemcached/blob/master/src/main/java/net/spy/memcached/NodeLocator.java): `src/main/java/net/spy/memcached/NodeLocator.java`

### Protocols and TAP

- [Protocol Operations](https://github.com/couchbase/spymemcached/blob/master/src/main/java/net/spy/memcached/protocol/BaseOperationImpl.java): `src/main/java/net/spy/memcached/protocol/BaseOperationImpl.java`
- [ASCII Protocol](https://github.com/couchbase/spymemcached/blob/master/src/main/java/net/spy/memcached/protocol/ascii/AsciiOperationFactory.java): `src/main/java/net/spy/memcached/protocol/ascii/AsciiOperationFactory.java`
- [Binary Protocol](https://github.com/couchbase/spymemcached/blob/master/src/main/java/net/spy/memcached/protocol/binary/BinaryOperationFactory.java): `src/main/java/net/spy/memcached/protocol/binary/BinaryOperationFactory.java`
- [TAP Client](https://github.com/couchbase/spymemcached/blob/master/src/main/java/net/spy/memcached/TapClient.java): `src/main/java/net/spy/memcached/TapClient.java`
- [TAP Messages](https://github.com/couchbase/spymemcached/blob/master/src/main/java/net/spy/memcached/tapmessage/ResponseMessage.java): `src/main/java/net/spy/memcached/tapmessage/ResponseMessage.java`

### Data and Support

- [Transcoders](https://github.com/couchbase/spymemcached/blob/master/src/main/java/net/spy/memcached/transcoders/Transcoder.java): `src/main/java/net/spy/memcached/transcoders/Transcoder.java`
- [Cached Data](https://github.com/couchbase/spymemcached/blob/master/src/main/java/net/spy/memcached/CachedData.java): `src/main/java/net/spy/memcached/CachedData.java`
- [SASL Authentication](https://github.com/couchbase/spymemcached/blob/master/src/main/java/net/spy/memcached/auth/AuthThread.java): `src/main/java/net/spy/memcached/auth/AuthThread.java`
- [Auth Descriptor](https://github.com/couchbase/spymemcached/blob/master/src/main/java/net/spy/memcached/auth/AuthDescriptor.java): `src/main/java/net/spy/memcached/auth/AuthDescriptor.java`
- [Metrics Collector](https://github.com/couchbase/spymemcached/blob/master/src/main/java/net/spy/memcached/metrics/DefaultMetricCollector.java): `src/main/java/net/spy/memcached/metrics/DefaultMetricCollector.java`

### Other components

- **Application**
- **Memcached Servers**

## Connections

- Application → Client Interface: calls (evidence: `src/main/java/net/spy/memcached/MemcachedClientIF.java`)
- Memcached Client → Operation Factory: creates operations (evidence: `src/main/java/net/spy/memcached/MemcachedClient.java`)
- Memcached Client → Connection Manager: enqueues operations (evidence: `src/main/java/net/spy/memcached/MemcachedClient.java`)
- Memcached Client → Operation Futures: returns futures (evidence: `src/main/java/net/spy/memcached/MemcachedClient.java`)
- Memcached Client → Transcoders: decodes values (evidence: `src/main/java/net/spy/memcached/MemcachedClient.java`)
- Memcached Client → Cached Data: wraps response data (evidence: `src/main/java/net/spy/memcached/MemcachedClient.java`)
- Operation Factory → Cache Operations: creates (evidence: `src/main/java/net/spy/memcached/OperationFactory.java`)
- Connection Manager → Node Queue API: manages nodes (evidence: `src/main/java/net/spy/memcached/MemcachedConnection.java`)
- Connection Manager → Cache Operations: initializes and routes (evidence: `src/main/java/net/spy/memcached/MemcachedConnection.java`)
- TCP Node Runtime → Node Queue API: implements (evidence: `src/main/java/net/spy/memcached/protocol/TCPMemcachedNodeImpl.java`)
- Connection Manager → Node Locators: selects nodes (evidence: `src/main/java/net/spy/memcached/MemcachedConnection.java`)
- TCP Node Runtime → Memcached Servers: communicates
- Protocol Operations → Cache Operations: implements (evidence: `src/main/java/net/spy/memcached/protocol/BaseOperationImpl.java`)
- ASCII Protocol → Protocol Operations: specializes
- Binary Protocol → Protocol Operations: specializes
- TAP Client → Cache Operations: submits TAP operations (evidence: `src/main/java/net/spy/memcached/TapClient.java`)
- TAP Client → TAP Messages: uses messages (evidence: `src/main/java/net/spy/memcached/TapClient.java`)
- TAP Messages → Cached Data: represents data (evidence: `src/main/java/net/spy/memcached/tapmessage/ResponseMessage.java`)
- TAP Messages → Transcoders: uses serialization (evidence: `src/main/java/net/spy/memcached/tapmessage/ResponseMessage.java`)
- SASL Authentication → Auth Descriptor: uses credentials (evidence: `src/main/java/net/spy/memcached/auth/AuthThread.java`)
- SASL Authentication → Connection Manager: coordinates authentication (evidence: `src/main/java/net/spy/memcached/auth/AuthThread.java`)
- Connection Manager → Metrics Collector: records metrics
