Distributed KV Store

I built this to actually learn how distributed systems work. Basically it's a small key-value store that replicates data across multiple nodes using the Raft consensus algorithm.

What it does

Each node runs a gRPC server backed by an in-memory map, guarded by a mutex for safe concurrent access. On top of that sits Raft, which handles leader election and log replication between nodes.

Writes only go through the current leader. A write is first proposed to the Raft log, replicated to a majority of nodes, and only then applied to each node's local store through an FSM (finite state machine) layer. Reads happen locally, so they don't need majority agreement.

If a client sends a write to a follower, it gets rejected with the address of the current leader instead of silently failing.

Why Raft

Raft solves the core problem of keeping multiple nodes in agreement: one leader is elected, all writes flow through it, and a change only counts once a majority of nodes have it. I used hashicorp/raft, a well-tested implementation, so I could focus on understanding the consensus model instead of debugging my own buggy version of it lol

What I verified

• Writes on the leader replicate correctly to all followers
• Followers reject direct writes and correctly report the current leader
• Killing the leader triggers automatic re-election, and the new leader takes over writes with no manual intervention
• Data stays consistent across a leadership change

Running it

Build the binary, then start three nodes with their own ID, ports, and data directory:

go build -o kvnode .

./kvnode -id=node1 -raft-addr=127.0.0.1:12000 -grpc-addr=:50051 -data-dir=./data-node1
./kvnode -id=node2 -raft-addr=127.0.0.1:12001 -grpc-addr=:50052 -data-dir=./data-node2
./kvnode -id=node3 -raft-addr=127.0.0.1:12002 -grpc-addr=:50053 -data-dir=./data-node3

Use grpcurl to send Put/Get/Delete requests to any node's gRPC address.

What I left out

No sharding, no hand-rolled Raft implementation, no client-side auto-retry on leader redirect. I scoped this to actually learning consensus and replication, not turning it into a months-long systems project bye