Synchronization Protocol
Understanding how TopGun moves data between clients and servers efficiently using Merkle Trees and WebSockets.
Sync vs. Request
Instead of writing thousands of API endpoints (GET /users, POST /todos), TopGun synchronizes state.
Traditional REST/GraphQL
- • Fetch data explicitly
- • Send requests to mutate
- • Handle loading/error states
- • Manual retry logic
TopGun Sync
- • Subscribe to datasets
- • Mutate local objects directly
- • Automatic retries & conflict resolution
- • Real-time updates pushed to you
Merkle Tree Synchronization
To keep bandwidth usage extremely low, TopGun doesn’t re-download the whole dataset every time you reconnect. It uses Merkle Trees (hash trees) to efficiently detect differences.
The Exchange Process
- 1
Handshake: Client and Server exchange the Root Hash of their respective Merkle Trees.
- 2
Comparison: If hashes match, data is identical. Sync complete (0 bytes transferred).
- 3
Drill Down: If hashes differ, they request hashes of child nodes (buckets) to pinpoint the exact difference.
- 4
Patch: Only the modified records (leaves) are transmitted over the wire.
Server Architecture
While clients are “Local-First”, TopGun is backed by a robust server cluster for persistence and scalability.
1. Gateway Node
Handles WebSocket connections and routes traffic.
2. Partition Engine
In-memory sharding logic that distributes data across the cluster.
3. Persistence Layer
Async write-behind to PostgreSQL (or in-memory for development).
4. Pub/Sub Bus
Broadcasts updates to other connected clients in real-time.