SyncNotes: A Consistency-Oriented Replicated Store for Collaborative Notes

SyncNotes is a collaborative note-taking system built around a three-tier client-gateway-cluster architecture. A set of shared plain-text notes lives on a cluster of three interchangeable server replicas, the sole source of truth; a lightweight, stateless gateway is the cluster’s single logical entry point, so clients never learn how many replicas exist, which one is serving them, or that a failover happened. The client itself is a full-screen terminal UI requiring no knowledge of commands, note names or file paths, so a non-technical user can browse, edit, create and delete notes with nothing but the arrow keys. The system is deliberately CP in CAP terms. Writes are ordered by a Raft replicated log and applied identically on every replica, so all clients see the same version of every note, and a replica that loses quorum during a network partition refuses writes rather than diverging. Concurrent edits are reconciled by a three-way merge that runs inside the replicated operation itself: disjoint edits are combined automatically, and a directly conflicting line is resolved deterministically in the server’s favour, with the losing client told exactly what happened. On top of consensus, a background reconciliation loop lets a lagging or corrupted replica repair itself from a healthy peer, closing the one gap consensus cannot see: storage-level corruption that never went through
the log.
The whole cluster, plus the gateway, runs as Docker containers wired by a single compose file; the client runs on the host. Validation combines an automated pytest suite, an end-to-end merge demo against a real cluster, and chaos scripts that kill the leader, partition the network, corrupt a replica’s storage and restart a node, asserting the system recovers exactly as the requirements demand.