Building a Distributed Key-Value Store in C++ (Part 1)

I wanted to understand distributed systems properly, not just read about them. So I decided to build a key-value store from scratch in C++ - something that starts as a simple std::unordered_map and eventually becomes a multi-node cluster with leader election. This is the first post in that series.

The plan is six phases, built one at a time. Here's the rough roadmap:

• Phase 1 - Local store ✅: in-memory KVStore with put, get, del
• Phase 2 - Persistence: append-only log for crash recovery
• Phase 3 - Networking: TCP server and CLI client
• Phase 4 - Multi-node: replication across instances
• Phase 5 - Consensus: leader election (Bully algorithm)
• Phase 6 - Testing & resilience: fuzzing, chaos, graceful failure

Phase 1: the simplest thing that works

A key-value store is just a dictionary with some extras. For now, the extras are zero.

File structure

distribkvstore/
├── CMakeLists.txt
├── src/
│   ├── kvstore.cpp
│   ├── kvstore.hpp
│   └── main.cpp
└── tests/
    └── test_kvstore.cpp  (planned)

Three operations

• put(key, value) - insert or update
• get(key) - retrieve
• del(key) - delete

Example usage

int main() {
  KVStore store;
  store.put("hello", "world");
 
  if (auto val = store.get("hello")) {
    std::cout << "GET hello: " << *val << "\n";
  }
 
  if (store.del("hello")) {
    std::cout << "deleted hello\n";
  }
 
  if (!store.get("hello")) {
    std::cout << "hello not found after deletion\n";
  }
 
  return 0;
}

That's it for Phase 1. It compiles, it runs, and it's the foundation for everything else.

Architecture

What's next

Part 2 adds unit tests and an append-only log for persistence. Without that, the store forgets everything when the process exits.