A distributed key-value store built from scratch with Raft consensus

Features • Quick Start • Architecture • Benchmarks • Chaos Testing • EKS Deployment Proof

• Raft Consensus — Leader election, log replication, and automatic failover with <550ms recovery
• LSM-Tree Storage — LevelDB-style tiered compaction with Bloom filters for 95% fewer disk lookups
• 10,000+ Write RPS — Achieved through custom Raft WAL with drain-loop batching, buffer pooling, and async persistence
• Kubernetes Native — StatefulSet deployment with persistent volumes and Prometheus/Grafana monitoring
• CLI Client — Full-featured command-line interface with configuration management, metrics, and testing tools

# Build CLI
make build-cli

# Basic operations
sicli put hello world
sicli get hello
sicli delete hello

# Configure server
sicli config set --server-url http://localhost:8081
sicli metrics

For detailed installation instructions, see cmd/cli/INSTALLATION.md.

docker-compose up
# Access: http://localhost:8001/put?key=hello&val=world
# Grafana: http://localhost:3000 (admin/admin)

kubectl apply -f deploy/k8s/

See INSTALL.md for detailed setup and EKS-INSTALL.md for AWS deployment.

The system consists of three layers:

See docs/ARCHITECHTURE.md for detailed documentation.

Custom appendable Raft WAL (d2d0e61) achieved a 3.3× throughput improvement through drain-loop batching, sync.Pool buffer reuse, and async fsync.

Custom arena allocator reduced write latency by 71% (82ns → 23ns) by eliminating GC pressure.

Benchmarks: docs/benchmarks/ | Arena profiling: docs/benchmarks/arena/

Chaos tests validate Raft's correctness guarantees under failure conditions.

Kills the leader mid-write and verifies no acknowledged data is lost.

[Step 1] Start 3-node cluster
[Step 2] Write 50 keys
[Step 3] SIGKILL the leader
[Step 4] Wait for new leader election (<550ms)
[Step 5] Write 50 more keys
[Step 6] Verify all 100 keys readable

Result: Zero data loss. All acknowledged writes survive leader failures.

Sends writes during election and verifies only one node accepts them.

# Run chaos tests
cd tests/chaos
go test -v -timeout 120s

See tests/chaos/README.md for details.

Built-in Prometheus metrics and Grafana dashboards:

• Write throughput (RPS per node)
• P99 latency
• Raft leader state
• Replication lag

# Access dashboards
kubectl port-forward svc/grafana 3000:3000
# Open http://localhost:3000 (admin/admin)

├── cmd/
│   ├── server/       # HTTP server entry point
│   └── cli/          # CLI client (sicli)
├── raft/             # Consensus implementation
├── kv/               # Storage engine (LSM-tree)
├── pkg/
│   ├── arena/        # Zero-allocation memory pool
│   ├── wal/          # Write-ahead log
│   └── bloom/        # Bloom filter
├── sstable/          # Sorted string tables
├── tests/chaos/      # Chaos tests
├── deploy/
│   ├── k8s/          # Kubernetes manifests
│   ├── prometheus/   # Monitoring config
│   └── grafana/      # Dashboards
└── docs/             # Architecture & benchmarks

MIT