System Architecture

See how all components — WAL, hash ring, quorum — fit together in a distributed key-value store.

How It Works

Each node runs an independent key-value engine using an in-memory table for fast reads, a Write-Ahead Log (WAL) for durability, and periodic snapshots to compact state. When you scale to multiple nodes, a hash ring maps keys to nodes, and writes require acknowledgment from a quorum (majority) of replicas to stay consistent even if some nodes fail.

Inside One Node

Memory Table
Fast in-memory storage for recent writes. Serves reads instantly.
WAL (Write-Ahead Log)
Append-only log on disk. Ensures durability: no data loss on crash.
Snapshot
Compact, point-in-time backup of the state. Used to truncate old WAL entries.

Across Multiple Nodes

Consistent Hash Ring
Maps every key to 2+ physical nodes using consistent hashing. Adding/removing nodes minimally redistributes keys.
Replication & Quorum
Each write goes to the primary + replicas. A quorum (e.g., 2 of 3) must acknowledge before success. Prevents split-brain.
Failure Handling
If a node dies, traffic reroutes via the hash ring. Snapshots + WAL let new nodes catch up quickly.

Example: Writing 'user:123'

  1. Key user:123 is hashed to angle 142.7° on the ring.
  2. Hash ring identifies Node B (145°) as primary and Node C (210°) as replica.
  3. Write request sent to both. Each appends to WAL and updates memory table.
  4. Once 2/2 nodes confirm, client gets success.
  5. Periodically, each node snapshots its state and truncates old WAL.