# ktaffy/distributed-kv architecture

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

- Interactive diagram: https://gitdiagram.com/ktaffy/distributed-kv
- Repository: https://github.com/ktaffy/distributed-kv

## Overview

This repository implements a distributed key-value store: clients issue GET/PUT/DELETE requests, while configured nodes coordinate through Raft and persist replicated state. The documented product also includes consistent-hash placement, crash recovery, and snapshots. Sampled code confirms the node’s ownership of Raft state, network, and persistence components; some application-level wiring and the exact client-to-node request path were not sampled, so those links are not expanded beyond documented behavior.

Main entry points: [`src/raft/raft_node.cpp`](https://github.com/ktaffy/distributed-kv/blob/master/src/raft/raft_node.cpp) (Raft node), [`src/network/network_manager.cpp`](https://github.com/ktaffy/distributed-kv/blob/master/src/network/network_manager.cpp) (Network manager), [`src/main.cpp`](https://github.com/ktaffy/distributed-kv/blob/master/src/main.cpp) (Node entry), [`src/kvstore/kv_store.cpp`](https://github.com/ktaffy/distributed-kv/blob/master/src/kvstore/kv_store.cpp) (KV client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client API"]
  node_clientapi["KV client<br/>[kv_store.cpp]"]
end

subgraph group_consensus["Raft Consensus"]
  node_raftnode["Raft node<br/>[raft_node.cpp]"]
  node_state["Raft state<br/>[raft_state.cpp]"]
  node_entry["Log entries<br/>[log_entry.cpp]"]
end

subgraph group_storage["Storage Engine"]
  node_kv["Key-value store<br/>[kv_store.cpp]"]
  node_hash["Consistent hashing"]
  node_persistent[("Persistent state")]
  node_logstorage[("Log and snapshots<br/>[log_storage.cpp]")]
end

subgraph group_transport["Node Transport"]
  node_network["Network manager"]
  node_message["RPC messages<br/>[message.cpp]"]
end

subgraph group_runtime["Node Runtime"]
  node_main["Node entry<br/>[main.cpp]"]
  node_config["Configuration<br/>[config.cpp]"]
end

node_user(("Client"))
node_peers(("Cluster peers"))

node_user -->|"issues operations"| node_clientapi
node_clientapi -->|"returns result"| node_user
node_main -->|"loads settings"| node_config
node_main -->|"starts node"| node_raftnode
node_raftnode -->|"updates consensus"| node_state
node_raftnode -->|"sends and handles RPCs"| node_network
node_raftnode -->|"persists term and vote"| node_persistent
node_raftnode -->|"reads and replicates log"| node_logstorage
node_raftnode -.->|"applies committed data"| node_kv
node_kv -.->|"chooses placement"| node_hash
node_logstorage -->|"stores entries"| node_entry
node_network -->|"serializes and dispatches"| node_message
node_network -->|"exchanges RPCs"| node_peers

click node_clientapi "https://github.com/ktaffy/distributed-kv/blob/master/src/kvstore/kv_store.cpp"
click node_kv "https://github.com/ktaffy/distributed-kv/blob/master/src/kvstore/kv_store.cpp"
click node_hash "https://github.com/ktaffy/distributed-kv/blob/master/src/kvstore/consistent_hash.cpp"
click node_main "https://github.com/ktaffy/distributed-kv/blob/master/src/main.cpp"
click node_config "https://github.com/ktaffy/distributed-kv/blob/master/src/utils/config.cpp"
click node_raftnode "https://github.com/ktaffy/distributed-kv/blob/master/src/raft/raft_node.cpp"
click node_state "https://github.com/ktaffy/distributed-kv/blob/master/src/raft/raft_state.cpp"
click node_entry "https://github.com/ktaffy/distributed-kv/blob/master/src/raft/log_entry.cpp"
click node_network "https://github.com/ktaffy/distributed-kv/blob/master/src/network/network_manager.cpp"
click node_message "https://github.com/ktaffy/distributed-kv/blob/master/src/network/message.cpp"
click node_persistent "https://github.com/ktaffy/distributed-kv/blob/master/src/persistence/persistent_state.cpp"
click node_logstorage "https://github.com/ktaffy/distributed-kv/blob/master/src/persistence/log_storage.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_clientapi,node_user toneBlue
class node_raftnode,node_state,node_entry toneAmber
class node_kv,node_hash,node_persistent,node_logstorage toneMint
class node_network,node_message toneRose
class node_main,node_config,node_peers toneIndigo
```

## Components

### Client API

- [KV client](https://github.com/ktaffy/distributed-kv/blob/master/src/kvstore/kv_store.cpp): `src/kvstore/kv_store.cpp`

### Raft Consensus

- [Raft node](https://github.com/ktaffy/distributed-kv/blob/master/src/raft/raft_node.cpp): `src/raft/raft_node.cpp`
- [Raft state](https://github.com/ktaffy/distributed-kv/blob/master/src/raft/raft_state.cpp): `src/raft/raft_state.cpp`
- [Log entries](https://github.com/ktaffy/distributed-kv/blob/master/src/raft/log_entry.cpp): `src/raft/log_entry.cpp`

### Storage Engine

- [Key-value store](https://github.com/ktaffy/distributed-kv/blob/master/src/kvstore/kv_store.cpp): `src/kvstore/kv_store.cpp`
- [Consistent hashing](https://github.com/ktaffy/distributed-kv/blob/master/src/kvstore/consistent_hash.cpp): `src/kvstore/consistent_hash.cpp`
- [Persistent state](https://github.com/ktaffy/distributed-kv/blob/master/src/persistence/persistent_state.cpp): `src/persistence/persistent_state.cpp`
- [Log and snapshots](https://github.com/ktaffy/distributed-kv/blob/master/src/persistence/log_storage.cpp): `src/persistence/log_storage.cpp`

### Node Transport

- [Network manager](https://github.com/ktaffy/distributed-kv/blob/master/src/network/network_manager.cpp): `src/network/network_manager.cpp`
- [RPC messages](https://github.com/ktaffy/distributed-kv/blob/master/src/network/message.cpp): `src/network/message.cpp`

### Node Runtime

- [Node entry](https://github.com/ktaffy/distributed-kv/blob/master/src/main.cpp): `src/main.cpp`
- [Configuration](https://github.com/ktaffy/distributed-kv/blob/master/src/utils/config.cpp): `src/utils/config.cpp`

### Other components

- **Client**
- **Cluster peers**

## Connections

- Client → KV client: issues operations
- KV client → Client: returns result
- Node entry → Configuration: loads settings
- Node entry → Raft node: starts node
- Raft node → Raft state: updates consensus
- Raft node → Network manager: sends and handles RPCs
- Raft node → Persistent state: persists term and vote
- Raft node → Log and snapshots: reads and replicates log
- Raft node → Key-value store: applies committed data
- Key-value store → Consistent hashing: chooses placement
- Log and snapshots → Log entries: stores entries
- Network manager → RPC messages: serializes and dispatches
- Network manager → Cluster peers: exchanges RPCs