# iam-iftekhar/distributed-kv-system architecture

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

- Interactive diagram: https://gitdiagram.com/iam-iftekhar/distributed-kv-system
- Repository: https://github.com/iam-iftekhar/distributed-kv-system

## Overview

This Go product is a distributed key-value store with a line-oriented TCP interface, a Raft replication implementation, and two documented durability paths: a standalone KV WAL and Raft state/snapshot persistence. The README also describes request deduplication, snapshot installation, elections, and in-memory peer transport. The sampled executable wires the WAL-backed TCP server, not the RaftKV service; RaftKV is a separate implemented path. Arrows are limited to sampled calls or explicit README relationships, so unsampled wiring is not inferred.

Main entry points: [`cmd/kvserver/main.go`](https://github.com/iam-iftekhar/distributed-kv-system/blob/main/cmd/kvserver/main.go) (Node process), [`internal/raft/raft.go`](https://github.com/iam-iftekhar/distributed-kv-system/blob/main/internal/raft/raft.go) (Raft engine), [`internal/server/raft_kv.go`](https://github.com/iam-iftekhar/distributed-kv-system/blob/main/internal/server/raft_kv.go) (Raft KV service), [`internal/kv/store.go`](https://github.com/iam-iftekhar/distributed-kv-system/blob/main/internal/kv/store.go) (Memory store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client interface"]
  node_tcp["TCP command server<br/>[server.go]"]
  node_raftkv["Raft KV service<br/>[raft_kv.go]"]
end

subgraph group_raft["Raft consensus"]
  node_raftcore["Raft engine<br/>[raft.go]"]
  node_rpc["Consensus RPCs<br/>[rpc.go]"]
  node_transport["Peer transport<br/>[transport.go]"]
  node_peers(("Raft peer nodes"))
end

subgraph group_state["KV state"]
  node_store[("Memory store<br/>[store.go]")]
end

subgraph group_durability["Durability and operations"]
  node_binary["Node process<br/>[main.go]"]
  node_config["Configuration<br/>[config.go]"]
  node_logger["Structured logger<br/>[logger.go]"]
  node_wal[("KV write-ahead log<br/>[wal.go]")]
  node_persister[("Raft persister<br/>[persister.go]")]
end

node_client(("TCP client"))

node_client -->|"sends commands"| node_tcp
node_binary -->|"parses flags"| node_config
node_binary -->|"sets up"| node_logger
node_binary -->|"opens and replays"| node_wal
node_binary -->|"recovers entries"| node_store
node_binary -->|"starts"| node_tcp
node_tcp -->|"reads and mutates"| node_store
node_binary -->|"writes mutations"| node_wal
node_binary -->|"applies mutations"| node_store
node_raftkv -->|"starts commands"| node_raftcore
node_raftkv -->|"consumes apply messages"| node_raftcore
node_raftkv -->|"applies committed ops"| node_store
node_raftcore -->|"handles consensus RPCs"| node_rpc
node_raftcore -->|"sends peer RPCs"| node_transport
node_transport -->|"dispatches RPCs"| node_peers
node_raftcore -->|"persists state and snapshots"| node_persister
node_rpc -->|"delivers snapshots"| node_raftkv

click node_binary "https://github.com/iam-iftekhar/distributed-kv-system/blob/main/cmd/kvserver/main.go"
click node_config "https://github.com/iam-iftekhar/distributed-kv-system/blob/main/internal/config/config.go"
click node_logger "https://github.com/iam-iftekhar/distributed-kv-system/blob/main/internal/logger/logger.go"
click node_tcp "https://github.com/iam-iftekhar/distributed-kv-system/blob/main/internal/server/server.go"
click node_raftkv "https://github.com/iam-iftekhar/distributed-kv-system/blob/main/internal/server/raft_kv.go"
click node_store "https://github.com/iam-iftekhar/distributed-kv-system/blob/main/internal/kv/store.go"
click node_wal "https://github.com/iam-iftekhar/distributed-kv-system/blob/main/internal/storage/wal.go"
click node_raftcore "https://github.com/iam-iftekhar/distributed-kv-system/blob/main/internal/raft/raft.go"
click node_rpc "https://github.com/iam-iftekhar/distributed-kv-system/blob/main/internal/raft/rpc.go"
click node_transport "https://github.com/iam-iftekhar/distributed-kv-system/blob/main/internal/raft/transport.go"
click node_persister "https://github.com/iam-iftekhar/distributed-kv-system/blob/main/internal/raft/persister.go"

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_tcp,node_raftkv,node_client toneBlue
class node_raftcore,node_rpc,node_transport,node_peers toneAmber
class node_store toneMint
class node_binary,node_config,node_logger,node_wal,node_persister toneRose
```

## Components

### Client interface

- [TCP command server](https://github.com/iam-iftekhar/distributed-kv-system/blob/main/internal/server/server.go): `internal/server/server.go`
- [Raft KV service](https://github.com/iam-iftekhar/distributed-kv-system/blob/main/internal/server/raft_kv.go): `internal/server/raft_kv.go`

### Raft consensus

- [Raft engine](https://github.com/iam-iftekhar/distributed-kv-system/blob/main/internal/raft/raft.go): `internal/raft/raft.go`
- [Consensus RPCs](https://github.com/iam-iftekhar/distributed-kv-system/blob/main/internal/raft/rpc.go): `internal/raft/rpc.go`
- [Peer transport](https://github.com/iam-iftekhar/distributed-kv-system/blob/main/internal/raft/transport.go): `internal/raft/transport.go`
- **Raft peer nodes**

### KV state

- [Memory store](https://github.com/iam-iftekhar/distributed-kv-system/blob/main/internal/kv/store.go): `internal/kv/store.go`

### Durability and operations

- [Node process](https://github.com/iam-iftekhar/distributed-kv-system/blob/main/cmd/kvserver/main.go): `cmd/kvserver/main.go`
- [Configuration](https://github.com/iam-iftekhar/distributed-kv-system/blob/main/internal/config/config.go): `internal/config/config.go`
- [Structured logger](https://github.com/iam-iftekhar/distributed-kv-system/blob/main/internal/logger/logger.go): `internal/logger/logger.go`
- [KV write-ahead log](https://github.com/iam-iftekhar/distributed-kv-system/blob/main/internal/storage/wal.go): `internal/storage/wal.go`
- [Raft persister](https://github.com/iam-iftekhar/distributed-kv-system/blob/main/internal/raft/persister.go): `internal/raft/persister.go`

### Other components

- **TCP client**

## Connections

- TCP client → TCP command server: sends commands (evidence: `internal/server/server.go`)
- Node process → Configuration: parses flags (evidence: `cmd/kvserver/main.go`)
- Node process → Structured logger: sets up (evidence: `cmd/kvserver/main.go`)
- Node process → KV write-ahead log: opens and replays (evidence: `cmd/kvserver/main.go`)
- Node process → Memory store: recovers entries (evidence: `cmd/kvserver/main.go`)
- Node process → TCP command server: starts (evidence: `cmd/kvserver/main.go`)
- TCP command server → Memory store: reads and mutates (evidence: `internal/server/server.go`)
- Node process → KV write-ahead log: writes mutations (evidence: `cmd/kvserver/main.go`)
- Node process → Memory store: applies mutations (evidence: `cmd/kvserver/main.go`)
- Raft KV service → Raft engine: starts commands (evidence: `internal/server/raft_kv.go`)
- Raft KV service → Raft engine: consumes apply messages (evidence: `README.md`)
- Raft KV service → Memory store: applies committed ops (evidence: `internal/server/raft_kv.go`)
- Raft engine → Consensus RPCs: handles consensus RPCs (evidence: `README.md`)
- Raft engine → Peer transport: sends peer RPCs (evidence: `internal/raft/raft.go`)
- Peer transport → Raft peer nodes: dispatches RPCs (evidence: `internal/raft/transport.go`)
- Raft engine → Raft persister: persists state and snapshots (evidence: `README.md`)
- Consensus RPCs → Raft KV service: delivers snapshots (evidence: `README.md`)
