Architecture

Layered, built strictly bottom-up

Every layer has one purpose and a narrow interface to the layer above, so it can be built and tested in isolation. If work stops after any phase, the result is a complete, smaller system — never a broken half of a larger one.

        ┌───────────────────────────────────────────────┐
        │  Control plane / shard router  (TS/Bun)        │  Phase 5
        │  placement · split/rebalance · cluster dashboard│
        └───────────────┬───────────────────────────────┘
                        │ routes keys → groups
   ┌────────────────────┼────────────────────┐
   ▼                    ▼                     ▼
┌─────────┐        ┌─────────┐          ┌─────────┐
│ Raft grp│        │ Raft grp│   ...    │ Raft grp│         Phase 4 (multi-Raft)
└────┬────┘        └────┬────┘          └────┬────┘
     ▼  each replica hosts, per group:
┌──────────────────────────────────────────────────┐
│  MVCC transaction layer  (Rust)                   │        Phase 3
├──────────────────────────────────────────────────┤
│  Raft consensus  (Rust)                           │        Phase 2 — core shipped
│  election · replication · read-index ✓ · snapshot · membership ← next
├──────────────────────────────────────────────────┤
│  Custom LSM storage engine  (Rust)                │        Phase 1 — shipped
│  WAL · memtable · SSTables · leveled compaction · bloom
└──────────────────────────────────────────────────┘

See Roadmap for status per phase — the diagram above orders layers by dependency, not delivery date; the source spec groups the LSM engine and Raft consensus together as the first cycle of work.

Components

1. LSM storage engine (Rust) — shipped

Durable, ordered, local key→value storage with point lookups (range scans land with the Raft state-machine integration). An append-only WAL (fsync on commit) feeds an in-memory memtable; the memtable flushes to immutable SSTables; leveled compaction reclaims space and drops obsolete versions; per-SSTable bloom filters short-circuit misses. Sequence numbers thread through every write so the future MVCC layer can store multiple versions per key. Depends on the filesystem only. Full internals: LSM Storage Engine.

2. Raft consensus (Rust) — core shipped

Replicates a log of commands across a group so every replica applies the same commands in the same order, tolerating a minority of node failures. Built: leader election with pre-vote, log replication with the consistency check and conflict back-up, commit-index advancement under Raft's current-term rule, and read-index for linearizable reads without a log write — as RaftCore, a pure, synchronous, I/O-free step function, proven against four safety invariants by a deterministic multi-node simulation. Next: log compaction via storage-engine snapshots and joint-consensus membership changes. Depends on a dedicated Raft log store (append-oriented, index-keyed — not the LSM KV engine; see Raft-over-Paxos and log-store vs. LSM reuse) and a pluggable transport trait so a deterministic in-memory implementation can drive multi-node simulation in tests. Full internals: Raft Consensus.

3. Transport / RPC (Rust) — shipped

Node-to-node messaging for Raft (AppendEntries, RequestVote, snapshots) and client request routing, behind a Transport trait with two implementations: a deterministic, seeded in-memory transport for simulation (fault injection: partition, drop, delay) and a length-prefixed framed TCP transport for a real cluster. Transport is kept deliberately dumb by design — the pluggable seam exists for the chaos harness, not for production networking features. Wiring it into an async node event loop is still ahead. See Transport.

4. MVCC transaction layer (Rust)

Multi-key transactions at snapshot isolation: begin() → txn, txn.get/put, txn.commit() → ok | conflict. Multi-version keys keyed by (key, version), a timestamp/version source ordered through the Raft log, snapshot-isolation conflict checks at commit, and garbage collection of obsolete versions during compaction. Depends on the LSM engine's versioned keys and Raft's commit ordering.

5. Multi-Raft (Rust)

Runs many independent Raft groups on the same node set, each owning a contiguous key range (a shard). One Raft instance per range, a shared heartbeat/transport, and per-group storage namespaced within the engine. Sharding is deliberately sequenced after Phases 1–3 are fully finished and chaos-tested, so it cannot destabilize a proven base.

6. Control plane + shard router (TS/Bun)

Decides which node hosts which shard, routes client keys to the right group, triggers splits/rebalances, and exposes cluster state. A client-facing KV/txn API, an admin API, and a live dashboard visualizing the shard map and per-group Raft leadership. This is the one deliberate language boundary in the system: everything below it is Rust; the router, control plane, and dashboard are TypeScript/Bun.

Data flow — a linearizable write (single group)

1. Client sends put(k, v) to the router; the router maps k to its Raft group and forwards to that group's leader.
2. The leader appends the command to its Raft log and replicates it via AppendEntries.
3. A majority persists the entry (WAL fsync in the storage engine) and acks.
4. The leader advances its commit index and applies the command to the state machine — MVCC/LSM put(k, v, version).
5. The leader acks the client. A subsequent linearizable read uses read-index to confirm leadership before serving from applied state.

Testing strategy

The differentiator between "senior architect" and "ambitious junior" is proving the guarantees, not asserting them:

• Unit + property tests per layer — the LSM engine is checked against a reference BTreeMap model under randomized operation sequences.
• Deterministic simulation of a cluster — a single-threaded, seeded scheduler drives multiple Raft nodes over the pluggable transport so runs are reproducible. Most consensus bugs get caught here, not in a live cluster.
• Chaos / Jepsen-style suite (the flagship deliverable) — inject network partitions, message drop/delay/reorder, node crashes and restarts, and clock skew while a workload runs; check the resulting history against a linearizability checker to prove the guarantees actually hold.
• Benchmarks — storage-engine throughput/latency, with before/after numbers when a compaction or memory optimization lands. See Benchmarks.