The concepts the simulation is built on, in plain terms, each one a small module you can read in an afternoon.
Architecture
A metadata service maps every file path to its ordered list of chunk hashes and tracks the directory tree. A set of storage nodes hold the chunks themselves. A client talks to both. It asks metadata where a file's chunks live, then reads or writes those chunks on the storage nodes directly.
Nothing here needs a second machine. The metadata service, the nodes, and the message scheduler all run inside one process.
Chunking and content addressing
A file is split into fixed-size chunks. Each chunk is named by the SHA-256 hash of its own bytes, so identical content is stored once and every reference to a chunk carries a built-in integrity check.
The metadata for a file is just the ordered list of those hashes. To rebuild the file you fetch each chunk by hash and concatenate them back in order.
Replication and quorum
Every chunk is copied onto R storage nodes chosen by rendezvous hashing. Each node scores the chunk, and the top R scorers hold it. Losing one node moves only that node's chunks, not the whole placement.
A write is durable once a quorum of replicas acknowledge. Reads assemble the file from any live replica of each chunk, so a single slow or dead node never blocks a read.
The durability guarantee
There is no data loss with fewer than R node failures. Lose one or two nodes with R at three and every chunk still has a live copy. Under-replicated chunks re-replicate automatically once healthy capacity is available, restoring the full replica count.
Only when all R replicas of a specific chunk are gone is that file reported unavailable. It is never silently returned as corrupt bytes.
Deterministic simulation
The cluster runs on a seeded message scheduler that can delay, reorder, drop, and partition messages. The same seed produces the same run every time.
That is what makes failures testable. A partition or a dropped acknowledgement is not a flaky accident here. It is a reproducible event you can replay and reason about.
Erasure coding, optional
Instead of replicating each chunk R times, each chunk can be Reed Solomon encoded over GF(2^8) into k data plus m parity shards spread over distinct nodes. A read needs any k of the k+m shards, so up to m holders can be lost and the file still reads.
A fetched shard is verified against its content address, so a corrupt shard just counts as missing, and lost shard positions are re-encoded onto live nodes as repair.
