QuorumChat

A Python demo of a fault-tolerant distributed messaging backend inspired by distributed systems coursework on membership, Paxos, and DHTs.

Features

• 3-node cluster with heartbeat-based membership
• deterministic leader election (lowest alive node id)
• leader-based ordered replication with quorum commit
• persistent committed log (JSONL)
• sharded conversation history ownership by hash
• simple CLI client for sending messages and reading logs

Quick start

1) Run three nodes locally

Open three terminals:

python -m app.main node --config configs/cluster.local.json --node-id 1
python -m app.main node --config configs/cluster.local.json --node-id 2
python -m app.main node --config configs/cluster.local.json --node-id 3

2) Send messages

python -m app.main send --config configs/cluster.local.json --node-id 2 --conversation general --sender alice --text "hello"
python -m app.main send --config configs/cluster.local.json --node-id 3 --conversation general --sender bob --text "hi"

3) Read logs

python -m app.main show-log --config configs/cluster.local.json --node-id 1
python -m app.main show-log --config configs/cluster.local.json --node-id 2
python -m app.main show-log --config configs/cluster.local.json --node-id 3

4) Demo failover

Kill the leader process (node 1 by default), wait ~3 seconds, then send another message through node 2 or 3.

python -m app.main send --config configs/cluster.local.json --node-id 2 --conversation general --sender alice --text "still works"

Docker Compose

docker compose up --build

Project framing

This demo combines:

• membership + failure detection inspired by the membership service project
• ordered replicated commit inspired by Paxos / replicated-log ideas
• hash-based sharding inspired by the DHT project

Notes

This is an interview demo MVP, not a production-ready consensus implementation. It intentionally favors clarity and explainability over full protocol complexity.