# youngyangyang04/kamacache-cpp architecture

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

- Interactive diagram: https://gitdiagram.com/youngyangyang04/kamacache-cpp
- Repository: https://github.com/youngyangyang04/kamacache-cpp

## Overview

KCache is a distributed cache service with an SDK-driven workflow: applications call the SDK, which discovers nodes through etcd, routes keys using consistent hashing, and sends gRPC operations to a node. The node dispatches requests to a cache group backed by local LRU storage; misses use a getter callback, with SingleFlight coalescing concurrent loads. The README also documents coordinated invalidation and deletion plus an optional HTTP gateway. Some subsystem links rely on README documentation because their implementation files were not excerpted.

Main entry points: [`src/client/client_sdk.cpp`](https://github.com/youngyangyang04/kamacache-cpp/blob/main/src/client/client_sdk.cpp) (Client SDK), [`src/group/group.cpp`](https://github.com/youngyangyang04/kamacache-cpp/blob/main/src/group/group.cpp) (Cache group), [`src/server/server.cpp`](https://github.com/youngyangyang04/kamacache-cpp/blob/main/src/server/server.cpp) (gRPC server), [`src/main.cpp`](https://github.com/youngyangyang04/kamacache-cpp/blob/main/src/main.cpp) (Node entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client SDK"]
  node_sdk["Client SDK<br/>[client_sdk.cpp]"]
  node_hash["Consistent hash"]
  node_discovery["Service discovery<br/>[client_sdk.cpp]"]
end

subgraph group_node["Cache node"]
  node_nodeentry["Node entry<br/>[main.cpp]"]
  node_grpc["gRPC server<br/>[server.cpp]"]
  node_group["Cache group<br/>[group.cpp]"]
  node_lru["LRU cache<br/>[lru.cpp]"]
  node_singleflight["SingleFlight<br/>[singleflight.h]"]
  node_getter["Getter data source<br/>[main.cpp]"]
end

subgraph group_coord["Cluster coordination"]
  node_etcd[("etcd registry<br/>[registry.cpp]")]
end

subgraph group_integration["Integrations"]
  node_gateway["HTTP gateway<br/>[http_gateway.cpp]"]
end

node_application(("Application"))

node_application -->|"calls"| node_sdk
node_gateway -->|"uses"| node_sdk
node_sdk -->|"starts"| node_discovery
node_discovery -->|"watches services"| node_etcd
node_sdk -->|"routes keys"| node_hash
node_sdk -->|"sends RPCs"| node_grpc
node_sdk -->|"invalidates peers"| node_grpc
node_sdk -->|"broadcasts deletes"| node_grpc
node_nodeentry -->|"starts"| node_grpc
node_nodeentry -->|"registers node"| node_etcd
node_grpc -->|"dispatches requests"| node_group
node_nodeentry -->|"creates group"| node_group
node_group -->|"reads and writes"| node_lru
node_group -->|"coalesces loads"| node_singleflight
node_group -->|"loads on miss"| node_getter

click node_gateway "https://github.com/youngyangyang04/kamacache-cpp/blob/main/example/http_gateway/http_gateway.cpp"
click node_sdk "https://github.com/youngyangyang04/kamacache-cpp/blob/main/src/client/client_sdk.cpp"
click node_hash "https://github.com/youngyangyang04/kamacache-cpp/blob/main/src/consistent_hash/consistent_hash.cpp"
click node_discovery "https://github.com/youngyangyang04/kamacache-cpp/blob/main/src/client/client_sdk.cpp"
click node_etcd "https://github.com/youngyangyang04/kamacache-cpp/blob/main/src/registry/registry.cpp"
click node_nodeentry "https://github.com/youngyangyang04/kamacache-cpp/blob/main/src/main.cpp"
click node_grpc "https://github.com/youngyangyang04/kamacache-cpp/blob/main/src/server/server.cpp"
click node_group "https://github.com/youngyangyang04/kamacache-cpp/blob/main/src/group/group.cpp"
click node_lru "https://github.com/youngyangyang04/kamacache-cpp/blob/main/src/cache/lru.cpp"
click node_singleflight "https://github.com/youngyangyang04/kamacache-cpp/blob/main/src/include/kcache/singleflight.h"
click node_getter "https://github.com/youngyangyang04/kamacache-cpp/blob/main/src/main.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_sdk,node_hash,node_discovery toneBlue
class node_nodeentry,node_grpc,node_group,node_lru,node_singleflight,node_getter toneAmber
class node_etcd toneMint
class node_gateway toneRose
class node_application toneIndigo
```

## Components

### Client SDK

- [Client SDK](https://github.com/youngyangyang04/kamacache-cpp/blob/main/src/client/client_sdk.cpp): `src/client/client_sdk.cpp`
- [Consistent hash](https://github.com/youngyangyang04/kamacache-cpp/blob/main/src/consistent_hash/consistent_hash.cpp): `src/consistent_hash/consistent_hash.cpp`
- [Service discovery](https://github.com/youngyangyang04/kamacache-cpp/blob/main/src/client/client_sdk.cpp): `src/client/client_sdk.cpp`

### Cache node

- [Node entry](https://github.com/youngyangyang04/kamacache-cpp/blob/main/src/main.cpp): `src/main.cpp`
- [gRPC server](https://github.com/youngyangyang04/kamacache-cpp/blob/main/src/server/server.cpp): `src/server/server.cpp`
- [Cache group](https://github.com/youngyangyang04/kamacache-cpp/blob/main/src/group/group.cpp): `src/group/group.cpp`
- [LRU cache](https://github.com/youngyangyang04/kamacache-cpp/blob/main/src/cache/lru.cpp): `src/cache/lru.cpp`
- [SingleFlight](https://github.com/youngyangyang04/kamacache-cpp/blob/main/src/include/kcache/singleflight.h): `src/include/kcache/singleflight.h`
- [Getter data source](https://github.com/youngyangyang04/kamacache-cpp/blob/main/src/main.cpp): `src/main.cpp`

### Cluster coordination

- [etcd registry](https://github.com/youngyangyang04/kamacache-cpp/blob/main/src/registry/registry.cpp): `src/registry/registry.cpp`

### Integrations

- [HTTP gateway](https://github.com/youngyangyang04/kamacache-cpp/blob/main/example/http_gateway/http_gateway.cpp): `example/http_gateway/http_gateway.cpp`

### Other components

- **Application**

## Connections

- Application → Client SDK: calls (evidence: `README.md`)
- HTTP gateway → Client SDK: uses (evidence: `README.md`)
- Client SDK → Service discovery: starts (evidence: `src/client/client_sdk.cpp`)
- Service discovery → etcd registry: watches services (evidence: `src/client/client_sdk.cpp`)
- Client SDK → Consistent hash: routes keys (evidence: `src/client/client_sdk.cpp`)
- Client SDK → gRPC server: sends RPCs (evidence: `src/client/client_sdk.cpp`)
- Client SDK → gRPC server: invalidates peers (evidence: `src/client/client_sdk.cpp`)
- Client SDK → gRPC server: broadcasts deletes (evidence: `src/client/client_sdk.cpp`)
- Node entry → gRPC server: starts (evidence: `src/main.cpp`)
- Node entry → etcd registry: registers node
- gRPC server → Cache group: dispatches requests (evidence: `src/server/server.cpp`)
- Node entry → Cache group: creates group (evidence: `src/main.cpp`)
- Cache group → LRU cache: reads and writes (evidence: `src/group/group.cpp`)
- Cache group → SingleFlight: coalesces loads (evidence: `src/group/group.cpp`)
- Cache group → Getter data source: loads on miss (evidence: `src/group/group.cpp`)
