# dnmohanty/sharded-kv architecture

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

- Interactive diagram: https://gitdiagram.com/dnmohanty/sharded-kv
- Repository: https://github.com/dnmohanty/sharded-kv

## Overview

ShardedKV is a C++ key-value service: clients send line-based commands through a TCP proxy, which hashes each key to a backend; a backend applies SET/GET/DEL against its sharded in-memory store and persists mutations in a WAL. Backend restart replays that log, while background maintenance sweeps expired entries and compacts large logs. The graph preserves these workflows and the proxy’s health-based ring membership. Evidence is limited to the shown source excerpts and README; unsampled CLI details are represented only where documented.

Main entry points: [`src/Server.cpp`](https://github.com/dnmohanty/sharded-kv/blob/main/src/Server.cpp) (Backend command server), [`src/Proxy.cpp`](https://github.com/dnmohanty/sharded-kv/blob/main/src/Proxy.cpp) (TCP proxy), [`src/WAL.cpp`](https://github.com/dnmohanty/sharded-kv/blob/main/src/WAL.cpp) (Write-ahead log), [`src/ConsistentHash.cpp`](https://github.com/dnmohanty/sharded-kv/blob/main/src/ConsistentHash.cpp) (Consistent hash ring)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_cli["Interactive CLI<br/>[cli.cpp]"]
  node_main["Process entry<br/>[main.cpp]"]
end

subgraph group_routing["Routing and networking"]
  node_proxy["TCP proxy<br/>[Proxy.cpp]"]
  node_ring["Consistent hash ring<br/>[ConsistentHash.cpp]"]
  node_health["Backend health checks<br/>[Proxy.cpp]"]
end

subgraph group_data["Backend data path"]
  node_server["Backend command server<br/>[Server.cpp]"]
  node_store[("Sharded TTL store<br/>[Store.cpp]")]
end

subgraph group_durability["Persistence and maintenance"]
  node_wal[("Write-ahead log<br/>[WAL.cpp]")]
  node_maintenance["Sweep and compaction<br/>[Server.cpp]"]
end

node_client(("TCP client"))

node_client -->|"sends commands"| node_proxy
node_cli -->|"connects to"| node_proxy
node_main -->|"starts proxy"| node_proxy
node_main -->|"starts backend"| node_server
node_proxy -->|"routes keys"| node_ring
node_health -->|"updates membership"| node_ring
node_proxy -->|"forwards commands"| node_server
node_server -->|"checks key owner"| node_ring
node_server -->|"reads and mutates"| node_store
node_server -->|"appends mutations"| node_wal
node_server -->|"recovers on startup"| node_wal
node_maintenance -->|"sweeps expirations"| node_store
node_maintenance -->|"compacts log"| node_wal
node_wal -->|"replays and snapshots"| node_store

click node_cli "https://github.com/dnmohanty/sharded-kv/blob/main/src/cli.cpp"
click node_main "https://github.com/dnmohanty/sharded-kv/blob/main/src/main.cpp"
click node_proxy "https://github.com/dnmohanty/sharded-kv/blob/main/src/Proxy.cpp"
click node_ring "https://github.com/dnmohanty/sharded-kv/blob/main/src/ConsistentHash.cpp"
click node_health "https://github.com/dnmohanty/sharded-kv/blob/main/src/Proxy.cpp"
click node_server "https://github.com/dnmohanty/sharded-kv/blob/main/src/Server.cpp"
click node_store "https://github.com/dnmohanty/sharded-kv/blob/main/src/Store.cpp"
click node_wal "https://github.com/dnmohanty/sharded-kv/blob/main/src/WAL.cpp"
click node_maintenance "https://github.com/dnmohanty/sharded-kv/blob/main/src/Server.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_cli,node_main,node_client toneBlue
class node_proxy,node_ring,node_health toneAmber
class node_server,node_store toneMint
class node_wal,node_maintenance toneRose
```

## Components

### Entry points

- [Interactive CLI](https://github.com/dnmohanty/sharded-kv/blob/main/src/cli.cpp): `src/cli.cpp`
- [Process entry](https://github.com/dnmohanty/sharded-kv/blob/main/src/main.cpp): `src/main.cpp`

### Routing and networking

- [TCP proxy](https://github.com/dnmohanty/sharded-kv/blob/main/src/Proxy.cpp): `src/Proxy.cpp`
- [Consistent hash ring](https://github.com/dnmohanty/sharded-kv/blob/main/src/ConsistentHash.cpp): `src/ConsistentHash.cpp`
- [Backend health checks](https://github.com/dnmohanty/sharded-kv/blob/main/src/Proxy.cpp): `src/Proxy.cpp`

### Backend data path

- [Backend command server](https://github.com/dnmohanty/sharded-kv/blob/main/src/Server.cpp): `src/Server.cpp`
- [Sharded TTL store](https://github.com/dnmohanty/sharded-kv/blob/main/src/Store.cpp): `src/Store.cpp`

### Persistence and maintenance

- [Write-ahead log](https://github.com/dnmohanty/sharded-kv/blob/main/src/WAL.cpp): `src/WAL.cpp`
- [Sweep and compaction](https://github.com/dnmohanty/sharded-kv/blob/main/src/Server.cpp): `src/Server.cpp`

### Other components

- **TCP client**

## Connections

- TCP client → TCP proxy: sends commands (evidence: `README.md`)
- Interactive CLI → TCP proxy: connects to (evidence: `README.md`)
- Process entry → TCP proxy: starts proxy (evidence: `src/main.cpp`)
- Process entry → Backend command server: starts backend (evidence: `src/main.cpp`)
- TCP proxy → Consistent hash ring: routes keys (evidence: `src/Proxy.cpp`)
- Backend health checks → Consistent hash ring: updates membership (evidence: `src/Proxy.cpp`)
- TCP proxy → Backend command server: forwards commands (evidence: `src/Proxy.cpp`)
- Backend command server → Consistent hash ring: checks key owner (evidence: `src/Server.cpp`)
- Backend command server → Sharded TTL store: reads and mutates (evidence: `src/Server.cpp`)
- Backend command server → Write-ahead log: appends mutations (evidence: `src/Server.cpp`)
- Backend command server → Write-ahead log: recovers on startup (evidence: `src/Server.cpp`)
- Sweep and compaction → Sharded TTL store: sweeps expirations (evidence: `src/Server.cpp`)
- Sweep and compaction → Write-ahead log: compacts log (evidence: `src/Server.cpp`)
- Write-ahead log → Sharded TTL store: replays and snapshots (evidence: `src/WAL.cpp`)
