Distributed Key Value Store

Distributed key-value store with an HTTP API, append-only WAL durability, consistent-hash partitioning, primary-replica replication, failover, and rebalancing.

Architecture

flowchart LR
	Client --> Flask[Flask HTTP API]
	Flask --> Cluster[ClusterRuntime]
	Cluster --> Ring[Consistent Hash Ring]
	Cluster --> Primary[Primary Store]
	Cluster --> ReplicaA[Replica Store A]
	Cluster --> ReplicaB[Replica Store B]
	Primary --> WAL[Append-only WAL]
	ReplicaA --> WAL
	ReplicaB --> WAL
	Cluster --> HB[Heartbeat / Failover]
	Cluster --> RB[Rebalancer]

Loading

API

• GET /v1/keys/<key>
• PUT /v1/keys/<key> with JSON body {"value": ...}
• DELETE /v1/keys/<key>
• GET /v1/cluster/state

Local Run

python -m distributed_kv_store --host 127.0.0.1 --port 8080 --data-dir ./var/data

Docker

docker compose up --build --wait app

The container runs a single Gunicorn worker so the in-process cluster state stays consistent.

Smoke test:

curl -s http://localhost:8080/healthz

Run the test suite in Docker:

docker compose run --rm tests

Tests

python -m unittest discover -s tests -v