Distributed Key-Value Store

When one machine isn't enough, we spread data across many nodes. But adding or removing a node shouldn't require moving all data. This system uses consistent hashing to minimize disruption, and replication to keep data safe if a node fails.

All keys and nodes live on a circular hash ring (0–360°). A key is assigned to the first N nodes clockwise—those nodes store its data. This demo uses a replication factor of 3.

  • Adding a node: Only a small fraction of keys move—just those now closer to the new node.
  • Removing a node: Its keys are reassigned to the next nodes clockwise; other data stays put.
  • Reading or writing a key: The client computes the key’s position and contacts its replica nodes.
  • Failure tolerance: As long as one replica is alive, the data remains available.
node-a20°node-b95°node-c165°node-d240°node-e310°user:123
-> Key is written to the primary node and replicated clockwise

Simulate a Key

235.0°

Replica Nodes (RF = 2)

  • node-dPRIMARY240.0°
    stored value: hello
  • node-eREPLICA310.0°
    stored value: hello

Data is replicated to the next 2 nodes clockwise from the key’s position.

🔁 Try different keys like user:456,cache:xyz, or random strings.